mirror of
				https://github.com/python/cpython.git
				synced 2025-11-03 19:34:08 +00:00 
			
		
		
		
	Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
translation more difficult, as well as reading the English more difficult for non-native speakers.
This commit is contained in:
		
							parent
							
								
									1a7f16ccdf
								
							
						
					
					
						commit
						15e33d828c
					
				
					 2 changed files with 23 additions and 23 deletions
				
			
		| 
						 | 
					@ -129,9 +129,9 @@ spam_system(self, args)
 | 
				
			||||||
\end{verbatim}
 | 
					\end{verbatim}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
There is a straightforward translation from the argument list in
 | 
					There is a straightforward translation from the argument list in
 | 
				
			||||||
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
 | 
					Python (for example, the single expression \code{"ls -l"}) to the
 | 
				
			||||||
passed to the C function.  The C function always has two arguments,
 | 
					arguments passed to the C function.  The C function always has two
 | 
				
			||||||
conventionally named \var{self} and \var{args}.
 | 
					arguments, conventionally named \var{self} and \var{args}.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
The \var{self} argument is only used when the C function implements a
 | 
					The \var{self} argument is only used when the C function implements a
 | 
				
			||||||
built-in method, not a function. In the example, \var{self} will
 | 
					built-in method, not a function. In the example, \var{self} will
 | 
				
			||||||
| 
						 | 
					@ -200,7 +200,7 @@ function call, since you should be able to tell from the return value.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
When a function \var{f} that calls another function \var{g} detects
 | 
					When a function \var{f} that calls another function \var{g} detects
 | 
				
			||||||
that the latter fails, \var{f} should itself return an error value
 | 
					that the latter fails, \var{f} should itself return an error value
 | 
				
			||||||
(e.g.\ \NULL{} or \code{-1}).  It should \emph{not} call one of the
 | 
					(usually \NULL{} or \code{-1}).  It should \emph{not} call one of the
 | 
				
			||||||
\cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
 | 
					\cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
 | 
				
			||||||
\var{f}'s caller is then supposed to also return an error indication
 | 
					\var{f}'s caller is then supposed to also return an error indication
 | 
				
			||||||
to \emph{its} caller, again \emph{without} calling \cfunction{PyErr_*()},
 | 
					to \emph{its} caller, again \emph{without} calling \cfunction{PyErr_*()},
 | 
				
			||||||
| 
						 | 
					@ -220,8 +220,8 @@ To ignore an exception set by a function call that failed, the exception
 | 
				
			||||||
condition must be cleared explicitly by calling \cfunction{PyErr_Clear()}. 
 | 
					condition must be cleared explicitly by calling \cfunction{PyErr_Clear()}. 
 | 
				
			||||||
The only time C code should call \cfunction{PyErr_Clear()} is if it doesn't
 | 
					The only time C code should call \cfunction{PyErr_Clear()} is if it doesn't
 | 
				
			||||||
want to pass the error on to the interpreter but wants to handle it
 | 
					want to pass the error on to the interpreter but wants to handle it
 | 
				
			||||||
completely by itself (e.g.\ by trying something else or pretending
 | 
					completely by itself (possibly by trying something else, or pretending
 | 
				
			||||||
nothing happened).
 | 
					nothing went wrong).
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Every failing \cfunction{malloc()} call must be turned into an
 | 
					Every failing \cfunction{malloc()} call must be turned into an
 | 
				
			||||||
exception --- the direct caller of \cfunction{malloc()} (or
 | 
					exception --- the direct caller of \cfunction{malloc()} (or
 | 
				
			||||||
| 
						 | 
					@ -241,8 +241,8 @@ you have already created) when you return an error indicator!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
The choice of which exception to raise is entirely yours.  There are
 | 
					The choice of which exception to raise is entirely yours.  There are
 | 
				
			||||||
predeclared C objects corresponding to all built-in Python exceptions,
 | 
					predeclared C objects corresponding to all built-in Python exceptions,
 | 
				
			||||||
e.g.\ \cdata{PyExc_ZeroDivisionError}, which you can use directly.  Of
 | 
					such as \cdata{PyExc_ZeroDivisionError}, which you can use directly.
 | 
				
			||||||
course, you should choose exceptions wisely --- don't use
 | 
					Of course, you should choose exceptions wisely --- don't use
 | 
				
			||||||
\cdata{PyExc_TypeError} to mean that a file couldn't be opened (that
 | 
					\cdata{PyExc_TypeError} to mean that a file couldn't be opened (that
 | 
				
			||||||
should probably be \cdata{PyExc_IOError}).  If something's wrong with
 | 
					should probably be \cdata{PyExc_IOError}).  If something's wrong with
 | 
				
			||||||
the argument list, the \cfunction{PyArg_ParseTuple()} function usually
 | 
					the argument list, the \cfunction{PyArg_ParseTuple()} function usually
 | 
				
			||||||
| 
						 | 
					@ -252,14 +252,14 @@ must be in a particular range or must satisfy other conditions,
 | 
				
			||||||
 | 
					
 | 
				
			||||||
You can also define a new exception that is unique to your module.
 | 
					You can also define a new exception that is unique to your module.
 | 
				
			||||||
For this, you usually declare a static object variable at the
 | 
					For this, you usually declare a static object variable at the
 | 
				
			||||||
beginning of your file, e.g.
 | 
					beginning of your file:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
\begin{verbatim}
 | 
					\begin{verbatim}
 | 
				
			||||||
static PyObject *SpamError;
 | 
					static PyObject *SpamError;
 | 
				
			||||||
\end{verbatim}
 | 
					\end{verbatim}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
and initialize it in your module's initialization function
 | 
					and initialize it in your module's initialization function
 | 
				
			||||||
(\cfunction{initspam()}) with an exception object, e.g.\ (leaving out
 | 
					(\cfunction{initspam()}) with an exception object (leaving out
 | 
				
			||||||
the error checking for now):
 | 
					the error checking for now):
 | 
				
			||||||
 | 
					
 | 
				
			||||||
\begin{verbatim}
 | 
					\begin{verbatim}
 | 
				
			||||||
| 
						 | 
					@ -1316,7 +1316,7 @@ of it.
 | 
				
			||||||
A borrowed reference can be changed into an owned reference by calling
 | 
					A borrowed reference can be changed into an owned reference by calling
 | 
				
			||||||
\cfunction{Py_INCREF()}.  This does not affect the status of the owner from
 | 
					\cfunction{Py_INCREF()}.  This does not affect the status of the owner from
 | 
				
			||||||
which the reference was borrowed --- it creates a new owned reference,
 | 
					which the reference was borrowed --- it creates a new owned reference,
 | 
				
			||||||
and gives full owner responsibilities (i.e., the new owner must
 | 
					and gives full owner responsibilities (the new owner must
 | 
				
			||||||
dispose of the reference properly, as well as the previous owner).
 | 
					dispose of the reference properly, as well as the previous owner).
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
| 
						 | 
					@ -1329,7 +1329,7 @@ transferred with the reference or not.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Most functions that return a reference to an object pass on ownership
 | 
					Most functions that return a reference to an object pass on ownership
 | 
				
			||||||
with the reference.  In particular, all functions whose function it is
 | 
					with the reference.  In particular, all functions whose function it is
 | 
				
			||||||
to create a new object, e.g.\ \cfunction{PyInt_FromLong()} and
 | 
					to create a new object, such as \cfunction{PyInt_FromLong()} and
 | 
				
			||||||
\cfunction{Py_BuildValue()}, pass ownership to the receiver.  Even if in
 | 
					\cfunction{Py_BuildValue()}, pass ownership to the receiver.  Even if in
 | 
				
			||||||
fact, in some cases, you don't receive a reference to a brand new
 | 
					fact, in some cases, you don't receive a reference to a brand new
 | 
				
			||||||
object, you still receive ownership of the reference.  For instance,
 | 
					object, you still receive ownership of the reference.  For instance,
 | 
				
			||||||
| 
						 | 
					@ -1467,8 +1467,8 @@ other function --- if each function were to test for \NULL{},
 | 
				
			||||||
there would be a lot of redundant tests and the code would run more
 | 
					there would be a lot of redundant tests and the code would run more
 | 
				
			||||||
slowly.
 | 
					slowly.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
It is better to test for \NULL{} only at the ``source'', i.e.\ when a
 | 
					It is better to test for \NULL{} only at the ``source:'' when a
 | 
				
			||||||
pointer that may be \NULL{} is received, e.g.\ from
 | 
					pointer that may be \NULL{} is received, for example, from
 | 
				
			||||||
\cfunction{malloc()} or from a function that may raise an exception.
 | 
					\cfunction{malloc()} or from a function that may raise an exception.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
 | 
					The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
 | 
				
			||||||
| 
						 | 
					@ -1535,11 +1535,11 @@ interpreter. When modules are used as shared libraries, however, the
 | 
				
			||||||
symbols defined in one module may not be visible to another module.
 | 
					symbols defined in one module may not be visible to another module.
 | 
				
			||||||
The details of visibility depend on the operating system; some systems
 | 
					The details of visibility depend on the operating system; some systems
 | 
				
			||||||
use one global namespace for the Python interpreter and all extension
 | 
					use one global namespace for the Python interpreter and all extension
 | 
				
			||||||
modules (e.g.\ Windows), whereas others require an explicit list of
 | 
					modules (Windows, for example), whereas others require an explicit
 | 
				
			||||||
imported symbols at module link time (e.g.\ AIX), or offer a choice of
 | 
					list of imported symbols at module link time (AIX is one example), or
 | 
				
			||||||
different strategies (most Unices). And even if symbols are globally
 | 
					offer a choice of different strategies (most Unices). And even if
 | 
				
			||||||
visible, the module whose functions one wishes to call might not have
 | 
					symbols are globally visible, the module whose functions one wishes to
 | 
				
			||||||
been loaded yet!
 | 
					call might not have been loaded yet!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Portability therefore requires not to make any assumptions about
 | 
					Portability therefore requires not to make any assumptions about
 | 
				
			||||||
symbol visibility. This means that all symbols in extension modules
 | 
					symbol visibility. This means that all symbols in extension modules
 | 
				
			||||||
| 
						 | 
					@ -1549,8 +1549,8 @@ extension modules (as discussed in section~\ref{methodTable}). And it
 | 
				
			||||||
means that symbols that \emph{should} be accessible from other
 | 
					means that symbols that \emph{should} be accessible from other
 | 
				
			||||||
extension modules must be exported in a different way.
 | 
					extension modules must be exported in a different way.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Python provides a special mechanism to pass C-level information (i.e.
 | 
					Python provides a special mechanism to pass C-level information
 | 
				
			||||||
pointers) from one extension module to another one: CObjects.
 | 
					(pointers) from one extension module to another one: CObjects.
 | 
				
			||||||
A CObject is a Python data type which stores a pointer (\ctype{void
 | 
					A CObject is a Python data type which stores a pointer (\ctype{void
 | 
				
			||||||
*}).  CObjects can only be created and accessed via their C API, but
 | 
					*}).  CObjects can only be created and accessed via their C API, but
 | 
				
			||||||
they can be passed around like any other Python object. In particular, 
 | 
					they can be passed around like any other Python object. In particular, 
 | 
				
			||||||
| 
						 | 
					@ -1904,7 +1904,7 @@ Almost always, you create objects with a call of the form:
 | 
				
			||||||
PyObject_New(<type>, &<type object>);
 | 
					PyObject_New(<type>, &<type object>);
 | 
				
			||||||
\end{verbatim}
 | 
					\end{verbatim}
 | 
				
			||||||
 | 
					
 | 
				
			||||||
This allocates the memory and then initializes the object (i.e.\ sets
 | 
					This allocates the memory and then initializes the object (sets
 | 
				
			||||||
the reference count to one, makes the \cdata{ob_type} pointer point at
 | 
					the reference count to one, makes the \cdata{ob_type} pointer point at
 | 
				
			||||||
the right place and maybe some other stuff, depending on build options).
 | 
					the right place and maybe some other stuff, depending on build options).
 | 
				
			||||||
You \emph{can} do these steps separately if you have some reason to
 | 
					You \emph{can} do these steps separately if you have some reason to
 | 
				
			||||||
| 
						 | 
					
 | 
				
			||||||
| 
						 | 
					@ -85,7 +85,7 @@ Accept (when \var{yesno} is non-zero) or reject an incoming call after
 | 
				
			||||||
 | 
					
 | 
				
			||||||
\begin{methoddesc}[connection]{Close}{timeout, now}
 | 
					\begin{methoddesc}[connection]{Close}{timeout, now}
 | 
				
			||||||
Close a connection. When \var{now} is zero, the close is orderly
 | 
					Close a connection. When \var{now} is zero, the close is orderly
 | 
				
			||||||
(i.e.\ outstanding output is flushed, etc.)\ with a timeout of
 | 
					(outstanding output is flushed, etc.)\ with a timeout of
 | 
				
			||||||
\var{timeout} seconds. When \var{now} is non-zero the close is
 | 
					\var{timeout} seconds. When \var{now} is non-zero the close is
 | 
				
			||||||
immediate, discarding output.
 | 
					immediate, discarding output.
 | 
				
			||||||
\end{methoddesc}
 | 
					\end{methoddesc}
 | 
				
			||||||
| 
						 | 
					
 | 
				
			||||||
		Loading…
	
	Add table
		Add a link
		
	
		Reference in a new issue