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:
Fred Drake 2001-07-06 06:49:32 +00:00
parent 1a7f16ccdf
commit 15e33d828c
2 changed files with 23 additions and 23 deletions

View File

@ -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

View File

@ -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}