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
|
@ -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…
Reference in New Issue