mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-30 01:47:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Marked references to the other manuals as \emph{} in the abstract.

Browse source 
Added \label{}s for logical addressing.
This commit is contained in:
Fred Drake 1998-02-26 18:49:12 +00:00
parent 6e73af723c
commit 3da06a69b9
2 changed files with 98 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

71
Doc/ext.tex
View file

@ -30,17 +30,17 @@ dynamically (at run time) into the interpreter, if the underlying
operating system supports this feature. operating system supports this feature.
This document assumes basic knowledge about Python. For an informal This document assumes basic knowledge about Python. For an informal
introduction to the language, see the Python Tutorial. The Python introduction to the language, see the Python Tutorial. The \emph{Python
Reference Manual gives a more formal definition of the language. The Reference Manual} gives a more formal definition of the language. The
Python Library Reference documents the existing object types, \emph{Python Library Reference} documents the existing object types,
functions and modules (both built-in and written in Python) that give functions and modules (both built-in and written in Python) that give
the language its wide application range. the language its wide application range.
For a detailed description of the whole Python/\C{} API, see the separate For a detailed description of the whole Python/\C{} API, see the separate
Python/\C{} API Reference Manual. \strong{Note:} While that manual is \emph{Python/\C{} API Reference Manual}. \strong{Note:} While that
still in a state of flux, it is safe to say that it is much more up to manual is still in a state of flux, it is safe to say that it is much
date than the manual you're reading currently (which has been in need more up to date than the manual you're reading currently (which has
for an upgrade for some time now). been in need for an upgrade for some time now).
\end{abstract} \end{abstract}
@ -51,7 +51,8 @@ for an upgrade for some time now).
\chapter{Extending Python with \C{} or \Cpp{} code} \chapter{Extending Python with \C{} or \Cpp{} code}
\section{Introduction} %\section{Introduction}
\label{intro}
It is quite easy to add new built-in modules to Python, if you know It is quite easy to add new built-in modules to Python, if you know
how to program in \C{}. Such \dfn{extension modules} can do two things how to program in \C{}. Such \dfn{extension modules} can do two things
@ -69,6 +70,7 @@ well as on your system setup; details are given in a later section.
\section{A Simple Example} \section{A Simple Example}
\label{simpleExample}
Let's create an extension module called \samp{spam} (the favorite food Let's create an extension module called \samp{spam} (the favorite food
of Monty Python fans...) and let's say we want to create a Python of Monty Python fans...) and let's say we want to create a Python
@ -141,13 +143,13 @@ The \var{args} argument will be a pointer to a Python tuple object
containing the arguments. Each item of the tuple corresponds to an containing the arguments. Each item of the tuple corresponds to an
argument in the call's argument list. The arguments are Python argument in the call's argument list. The arguments are Python
objects --- in order to do anything with them in our \C{} function we have objects --- in order to do anything with them in our \C{} function we have
to convert them to \C{} values. The function \code{PyArg_ParseTuple()} to convert them to \C{} values. The function \cfunction{PyArg_ParseTuple()}
in the Python API checks the argument types and converts them to \C{} in the Python API checks the argument types and converts them to \C{}
values. It uses a template string to determine the required types of values. It uses a template string to determine the required types of
the arguments as well as the types of the \C{} variables into which to the arguments as well as the types of the \C{} variables into which to
store the converted values. More about this later. store the converted values. More about this later.
\code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have \cfunction{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
the right type and its components have been stored in the variables the right type and its components have been stored in the variables
whose addresses are passed. It returns false (zero) if an invalid whose addresses are passed. It returns false (zero) if an invalid
argument list was passed. In the latter case it also raises an argument list was passed. In the latter case it also raises an
@ -156,6 +158,7 @@ appropriate exception by so the calling function can return
\section{Intermezzo: Errors and Exceptions} \section{Intermezzo: Errors and Exceptions}
\label{errors}
An important convention throughout the Python interpreter is the An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition following: when a function fails, it should set an exception condition
@ -226,7 +229,7 @@ failure indicator itself. All the object-creating functions
\code{malloc()} directly this note is of importance. \code{malloc()} directly this note is of importance.
Also note that, with the important exception of Also note that, with the important exception of
\code{PyArg_ParseTuple()} and friends, functions that return an \cfunction{PyArg_ParseTuple()} and friends, functions that return an
integer status usually return a positive value or zero for success and integer status usually return a positive value or zero for success and
\code{-1} for failure, like \UNIX{} system calls. \code{-1} for failure, like \UNIX{} system calls.
@ -240,7 +243,7 @@ e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of
course, you should choose exceptions wisely --- don't use course, you should choose exceptions wisely --- don't use
\code{PyExc_TypeError} to mean that a file couldn't be opened (that \code{PyExc_TypeError} to mean that a file couldn't be opened (that
should probably be \code{PyExc_IOError}). If something's wrong with should probably be \code{PyExc_IOError}). If something's wrong with
the argument list, the \code{PyArg_ParseTuple()} function usually the argument list, the \cfunction{PyArg_ParseTuple()} function usually
raises \code{PyExc_TypeError}. If you have an argument whose value raises \code{PyExc_TypeError}. If you have an argument whose value
which must be in a particular range or must satisfy other conditions, which must be in a particular range or must satisfy other conditions,
\code{PyExc_ValueError} is appropriate. \code{PyExc_ValueError} is appropriate.
@ -277,6 +280,7 @@ the string \code{"spam.error"}.
\section{Back to the Example} \section{Back to the Example}
\label{backToExample}
Going back to our example function, you should now be able to Going back to our example function, you should now be able to
understand this statement: understand this statement:
@ -288,7 +292,7 @@ understand this statement:
It returns \NULL{} (the error indicator for functions returning It returns \NULL{} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the on the exception set by \cfunction{PyArg_ParseTuple()}. Otherwise the
string value of the argument has been copied to the local variable string value of the argument has been copied to the local variable
\code{command}. This is a pointer assignment and you are not supposed \code{command}. This is a pointer assignment and you are not supposed
to modify the string to which it points (so in Standard \C{}, the variable to modify the string to which it points (so in Standard \C{}, the variable
@ -296,7 +300,7 @@ to modify the string to which it points (so in Standard \C{}, the variable
*command}). *command}).
The next statement is a call to the \UNIX{} function \code{system()}, The next statement is a call to the \UNIX{} function \code{system()},
passing it the string we just got from \code{PyArg_ParseTuple()}: passing it the string we just got from \cfunction{PyArg_ParseTuple()}:
\begin{verbatim} \begin{verbatim}
sts = system(command); sts = system(command);
@ -305,7 +309,7 @@ passing it the string we just got from \code{PyArg_ParseTuple()}:
Our \code{spam.system()} function must return the value of \code{sts} Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of \code{Py_BuildValue()}, which is something like the inverse of
\code{PyArg_ParseTuple()}: it takes a format string and an arbitrary \cfunction{PyArg_ParseTuple()}: it takes a format string and an arbitrary
number of \C{} values, and returns a new Python object. More info on number of \C{} values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later. \code{Py_BuildValue()} is given later.
@ -331,6 +335,7 @@ pointer, which means ``error'' in most contexts, as we have seen).
\section{The Module's Method Table and Initialization Function} \section{The Module's Method Table and Initialization Function}
\label{methodTable}
I promised to show how \code{spam_system()} is called from Python I promised to show how \code{spam_system()} is called from Python
programs. First, we need to list its name and address in a ``method programs. First, we need to list its name and address in a ``method
@ -349,7 +354,7 @@ Note the third entry (\samp{METH_VARARGS}). This is a flag telling
the interpreter the calling convention to be used for the \C{} the interpreter the calling convention to be used for the \C{}
function. It should normally always be \samp{METH_VARARGS} or function. It should normally always be \samp{METH_VARARGS} or
\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an \samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
obsolete variant of \code{PyArg_ParseTuple()} is used. obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
When using only \samp{METH_VARARGS}, the function should expect When using only \samp{METH_VARARGS}, the function should expect
the Python-level parameters to be passed in as a tuple acceptable for the Python-level parameters to be passed in as a tuple acceptable for
@ -359,7 +364,7 @@ function is provided below.
The \code{METH_KEYWORDS} bit may be set in the third field if keyword The \code{METH_KEYWORDS} bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the \C{} arguments should be passed to the function. In this case, the \C{}
function should accept a third \samp{PyObject *} parameter which will function should accept a third \samp{PyObject *} parameter which will
be a dictionary of keywords. Use \code{PyArg_ParseTupleAndKeywords()} be a dictionary of keywords. Use \cfunction{PyArg_ParseTupleAndKeywords()}
to parse the arguemts to such a function. to parse the arguemts to such a function.
The method table must be passed to the interpreter in the module's The method table must be passed to the interpreter in the module's
@ -387,6 +392,7 @@ so the caller doesn't need to check for errors.
\section{Compilation and Linkage} \section{Compilation and Linkage}
\label{compilation}
There are two more things to do before you can use your new extension: There are two more things to do before you can use your new extension:
compiling and linking it with the Python system. If you use dynamic compiling and linking it with the Python system. If you use dynamic
@ -419,6 +425,7 @@ spam spammodule.o -lX11
\end{verbatim} \end{verbatim}
\section{Calling Python Functions From \C{}} \section{Calling Python Functions From \C{}}
\label{callingPython}
So far we have concentrated on making \C{} functions callable from So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from \C{}. Python. The reverse is also useful: calling Python functions from \C{}.
@ -543,8 +550,9 @@ be checked.
\section{Format Strings for \sectcode{PyArg_ParseTuple()}} \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
\label{parseTuple}
The \code{PyArg_ParseTuple()} function is declared as follows: The \cfunction{PyArg_ParseTuple()} function is declared as follows:
\begin{verbatim} \begin{verbatim}
int PyArg_ParseTuple(PyObject *arg, char *format, ...); int PyArg_ParseTuple(PyObject *arg, char *format, ...);
@ -558,7 +566,7 @@ determined by the format string. For the conversion to succeed, the
\var{arg} object must match the format and the format must be \var{arg} object must match the format and the format must be
exhausted. exhausted.
Note that while \code{PyArg_ParseTuple()} checks that the Python Note that while \cfunction{PyArg_ParseTuple()} checks that the Python
arguments have the required types, it cannot check the validity of the arguments have the required types, it cannot check the validity of the
addresses of \C{} variables passed to the call: if you make mistakes addresses of \C{} variables passed to the call: if you make mistakes
there, your code will probably crash or at least overwrite random bits there, your code will probably crash or at least overwrite random bits
@ -568,7 +576,7 @@ A format string consists of zero or more ``format units''. A format
unit describes one Python object; it is usually a single character or unit describes one Python object; it is usually a single character or
a parenthesized sequence of format units. With a few exceptions, a a parenthesized sequence of format units. With a few exceptions, a
format unit that is not a parenthesized sequence normally corresponds format unit that is not a parenthesized sequence normally corresponds
to a single address argument to \code{PyArg_ParseTuple()}. In the to a single address argument to \cfunction{PyArg_ParseTuple()}. In the
following description, the quoted form is the format unit; the entry following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that matches the in (round) parentheses is the Python object type that matches the
format unit; and the entry in [square] brackets is the type of the \C{} format unit; and the entry in [square] brackets is the type of the \C{}
@ -582,7 +590,7 @@ Convert a Python string to a \C{} pointer to a character string. You
must not provide storage for the string itself; a pointer to an must not provide storage for the string itself; a pointer to an
existing string is stored into the character pointer variable whose existing string is stored into the character pointer variable whose
address you pass. The \C{} string is null-terminated. The Python string address you pass. The \C{} string is null-terminated. The Python string
must not contain embedded null bytes; if it does, a \code{TypeError} must not contain embedded null bytes; if it does, a \exception{TypeError}
exception is raised. exception is raised.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
@ -748,6 +756,7 @@ Some example calls:
\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}} \section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
\label{parseTupleAndKeywords}
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows: follows:
@ -817,6 +826,7 @@ initkeywdarg()
\section{The \sectcode{Py_BuildValue()} Function} \section{The \sectcode{Py_BuildValue()} Function}
\label{buildValue}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows: declared as follows:
@ -945,8 +955,9 @@ Examples (to the left the call, to the right the resulting Python value):
\end{verbatim} \end{verbatim}
\section{Reference Counts} \section{Reference Counts}
\label{refcounts}
\subsection{Introduction} %\subsection{Introduction}
In languages like \C{} or \Cpp{}, the programmer is responsible for In languages like \C{} or \Cpp{}, the programmer is responsible for
dynamic allocation and deallocation of memory on the heap. In \C{}, this dynamic allocation and deallocation of memory on the heap. In \C{}, this
@ -1007,6 +1018,7 @@ will be available for \C{}. Until then, we'll have to live with
reference counts. reference counts.
\subsection{Reference Counting in Python} \subsection{Reference Counting in Python}
\label{refcountsInPython}
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)}, There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
which handle the incrementing and decrementing of the reference count. which handle the incrementing and decrementing of the reference count.
@ -1054,6 +1066,7 @@ and gives full owner responsibilities (i.e., 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).
\subsection{Ownership Rules} \subsection{Ownership Rules}
\label{ownershipRules}
Whenever an object reference is passed into or out of a function, it Whenever an object reference is passed into or out of a function, it
is part of the function's interface specification whether ownership is is part of the function's interface specification whether ownership is
@ -1102,6 +1115,7 @@ Python must be an owned reference --- ownership is tranferred from the
function to its caller. function to its caller.
\subsection{Thin Ice} \subsection{Thin Ice}
\label{thinIce}
There are a few situations where seemingly harmless use of a borrowed There are a few situations where seemingly harmless use of a borrowed
reference can lead to problems. These all have to do with implicit reference can lead to problems. These all have to do with implicit
@ -1181,6 +1195,7 @@ bug(PyObject *list) {
\end{verbatim} \end{verbatim}
\subsection{NULL Pointers} \subsection{NULL Pointers}
\label{nullPointers}
In general, functions that take object references as arguments don't In general, functions that take object references as arguments don't
expect you to pass them \NULL{} pointers, and will dump core (or expect you to pass them \NULL{} pointers, and will dump core (or
@ -1217,6 +1232,7 @@ the Python user.
\section{Writing Extensions in \Cpp{}} \section{Writing Extensions in \Cpp{}}
\label{cplusplus}
It is possible to write extension modules in \Cpp{}. Some restrictions It is possible to write extension modules in \Cpp{}. Some restrictions
apply. If the main program (the Python interpreter) is compiled and apply. If the main program (the Python interpreter) is compiled and
@ -1231,6 +1247,7 @@ It is unnecessary to enclose the Python header files in
symbol). symbol).
\chapter{Embedding Python in another application} \chapter{Embedding Python in another application}
\label{embedding}
Embedding Python is similar to extending it, but not quite. The Embedding Python is similar to extending it, but not quite. The
difference is that when you extend Python, the main program of the difference is that when you extend Python, the main program of the
@ -1258,6 +1275,7 @@ A simple demo of embedding Python can be found in the directory
\section{Embedding Python in \Cpp{}} \section{Embedding Python in \Cpp{}}
\label{embeddingInCplusplus}
It is also possible to embed Python in a \Cpp{} program; precisely how this It is also possible to embed Python in a \Cpp{} program; precisely how this
is done will depend on the details of the \Cpp{} system used; in general you is done will depend on the details of the \Cpp{} system used; in general you
@ -1267,6 +1285,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading} \chapter{Dynamic Loading}
\label{dynload}
On most modern systems it is possible to configure Python to support On most modern systems it is possible to configure Python to support
dynamic loading of extension modules implemented in \C{}. When shared dynamic loading of extension modules implemented in \C{}. When shared
@ -1290,12 +1309,14 @@ loading a module that was compiled for a different version of Python
\section{Configuring and Building the Interpreter for Dynamic Loading} \section{Configuring and Building the Interpreter for Dynamic Loading}
\label{dynloadConfig}
There are three styles of dynamic loading: one using shared libraries, There are three styles of dynamic loading: one using shared libraries,
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
loading. loading.
\subsection{Shared Libraries} \subsection{Shared Libraries}
\label{sharedlibs}
The following systems support dynamic loading using shared libraries: The following systems support dynamic loading using shared libraries:
SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
@ -1308,6 +1329,7 @@ systems --- the \file{configure} detects the presence of the
loading. loading.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
\label{irixDynload}
Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
loading. (SGI IRIX 5 might also support it but it is inferior to loading. (SGI IRIX 5 might also support it but it is inferior to
@ -1329,6 +1351,7 @@ Now build and install Python as you normally would (see the
\file{README} file in the toplevel Python directory.) \file{README} file in the toplevel Python directory.)
\subsection{GNU Dynamic Loading} \subsection{GNU Dynamic Loading}
\label{gnuDynload}
GNU dynamic loading supports (according to its \file{README} file) the GNU dynamic loading supports (according to its \file{README} file) the
following hardware and software combinations: VAX (Ultrix), Sun 3 following hardware and software combinations: VAX (Ultrix), Sun 3
@ -1359,6 +1382,7 @@ will support GNU dynamic loading.
\section{Building a Dynamically Loadable Module} \section{Building a Dynamically Loadable Module}
\label{makedynload}
Since there are three styles of dynamic loading, there are also three Since there are three styles of dynamic loading, there are also three
groups of instructions for building a dynamically loadable module. groups of instructions for building a dynamically loadable module.
@ -1379,6 +1403,7 @@ contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
\subsection{Shared Libraries} \subsection{Shared Libraries}
\label{linking}
You must link the \file{.o} file to produce a shared library. This is You must link the \file{.o} file to produce a shared library. This is
done using a special invocation of the \UNIX{} loader/linker, done using a special invocation of the \UNIX{} loader/linker,
@ -1413,6 +1438,7 @@ along the Python module search path.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
\label{irixLinking}
\strong{IMPORTANT:} You must compile your extension module with the \strong{IMPORTANT:} You must compile your extension module with the
additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the
@ -1441,6 +1467,7 @@ normally only \samp{-l} options or absolute pathnames of libraries
\subsection{GNU Dynamic Loading} \subsection{GNU Dynamic Loading}
\label{gnuLinking}
Just copy \file{spammodule.o} into a directory along the Python module Just copy \file{spammodule.o} into a directory along the Python module
search path. search path.

71
Doc/ext/ext.tex
View file

@ -30,17 +30,17 @@ dynamically (at run time) into the interpreter, if the underlying
operating system supports this feature. operating system supports this feature.
This document assumes basic knowledge about Python. For an informal This document assumes basic knowledge about Python. For an informal
introduction to the language, see the Python Tutorial. The Python introduction to the language, see the Python Tutorial. The \emph{Python
Reference Manual gives a more formal definition of the language. The Reference Manual} gives a more formal definition of the language. The
Python Library Reference documents the existing object types, \emph{Python Library Reference} documents the existing object types,
functions and modules (both built-in and written in Python) that give functions and modules (both built-in and written in Python) that give
the language its wide application range. the language its wide application range.
For a detailed description of the whole Python/\C{} API, see the separate For a detailed description of the whole Python/\C{} API, see the separate
Python/\C{} API Reference Manual. \strong{Note:} While that manual is \emph{Python/\C{} API Reference Manual}. \strong{Note:} While that
still in a state of flux, it is safe to say that it is much more up to manual is still in a state of flux, it is safe to say that it is much
date than the manual you're reading currently (which has been in need more up to date than the manual you're reading currently (which has
for an upgrade for some time now). been in need for an upgrade for some time now).
\end{abstract} \end{abstract}
@ -51,7 +51,8 @@ for an upgrade for some time now).
\chapter{Extending Python with \C{} or \Cpp{} code} \chapter{Extending Python with \C{} or \Cpp{} code}
\section{Introduction} %\section{Introduction}
\label{intro}
It is quite easy to add new built-in modules to Python, if you know It is quite easy to add new built-in modules to Python, if you know
how to program in \C{}. Such \dfn{extension modules} can do two things how to program in \C{}. Such \dfn{extension modules} can do two things
@ -69,6 +70,7 @@ well as on your system setup; details are given in a later section.
\section{A Simple Example} \section{A Simple Example}
\label{simpleExample}
Let's create an extension module called \samp{spam} (the favorite food Let's create an extension module called \samp{spam} (the favorite food
of Monty Python fans...) and let's say we want to create a Python of Monty Python fans...) and let's say we want to create a Python
@ -141,13 +143,13 @@ The \var{args} argument will be a pointer to a Python tuple object
containing the arguments. Each item of the tuple corresponds to an containing the arguments. Each item of the tuple corresponds to an
argument in the call's argument list. The arguments are Python argument in the call's argument list. The arguments are Python
objects --- in order to do anything with them in our \C{} function we have objects --- in order to do anything with them in our \C{} function we have
to convert them to \C{} values. The function \code{PyArg_ParseTuple()} to convert them to \C{} values. The function \cfunction{PyArg_ParseTuple()}
in the Python API checks the argument types and converts them to \C{} in the Python API checks the argument types and converts them to \C{}
values. It uses a template string to determine the required types of values. It uses a template string to determine the required types of
the arguments as well as the types of the \C{} variables into which to the arguments as well as the types of the \C{} variables into which to
store the converted values. More about this later. store the converted values. More about this later.
\code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have \cfunction{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
the right type and its components have been stored in the variables the right type and its components have been stored in the variables
whose addresses are passed. It returns false (zero) if an invalid whose addresses are passed. It returns false (zero) if an invalid
argument list was passed. In the latter case it also raises an argument list was passed. In the latter case it also raises an
@ -156,6 +158,7 @@ appropriate exception by so the calling function can return
\section{Intermezzo: Errors and Exceptions} \section{Intermezzo: Errors and Exceptions}
\label{errors}
An important convention throughout the Python interpreter is the An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition following: when a function fails, it should set an exception condition
@ -226,7 +229,7 @@ failure indicator itself. All the object-creating functions
\code{malloc()} directly this note is of importance. \code{malloc()} directly this note is of importance.
Also note that, with the important exception of Also note that, with the important exception of
\code{PyArg_ParseTuple()} and friends, functions that return an \cfunction{PyArg_ParseTuple()} and friends, functions that return an
integer status usually return a positive value or zero for success and integer status usually return a positive value or zero for success and
\code{-1} for failure, like \UNIX{} system calls. \code{-1} for failure, like \UNIX{} system calls.
@ -240,7 +243,7 @@ e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of
course, you should choose exceptions wisely --- don't use course, you should choose exceptions wisely --- don't use
\code{PyExc_TypeError} to mean that a file couldn't be opened (that \code{PyExc_TypeError} to mean that a file couldn't be opened (that
should probably be \code{PyExc_IOError}). If something's wrong with should probably be \code{PyExc_IOError}). If something's wrong with
the argument list, the \code{PyArg_ParseTuple()} function usually the argument list, the \cfunction{PyArg_ParseTuple()} function usually
raises \code{PyExc_TypeError}. If you have an argument whose value raises \code{PyExc_TypeError}. If you have an argument whose value
which must be in a particular range or must satisfy other conditions, which must be in a particular range or must satisfy other conditions,
\code{PyExc_ValueError} is appropriate. \code{PyExc_ValueError} is appropriate.
@ -277,6 +280,7 @@ the string \code{"spam.error"}.
\section{Back to the Example} \section{Back to the Example}
\label{backToExample}
Going back to our example function, you should now be able to Going back to our example function, you should now be able to
understand this statement: understand this statement:
@ -288,7 +292,7 @@ understand this statement:
It returns \NULL{} (the error indicator for functions returning It returns \NULL{} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the on the exception set by \cfunction{PyArg_ParseTuple()}. Otherwise the
string value of the argument has been copied to the local variable string value of the argument has been copied to the local variable
\code{command}. This is a pointer assignment and you are not supposed \code{command}. This is a pointer assignment and you are not supposed
to modify the string to which it points (so in Standard \C{}, the variable to modify the string to which it points (so in Standard \C{}, the variable
@ -296,7 +300,7 @@ to modify the string to which it points (so in Standard \C{}, the variable
*command}). *command}).
The next statement is a call to the \UNIX{} function \code{system()}, The next statement is a call to the \UNIX{} function \code{system()},
passing it the string we just got from \code{PyArg_ParseTuple()}: passing it the string we just got from \cfunction{PyArg_ParseTuple()}:
\begin{verbatim} \begin{verbatim}
sts = system(command); sts = system(command);
@ -305,7 +309,7 @@ passing it the string we just got from \code{PyArg_ParseTuple()}:
Our \code{spam.system()} function must return the value of \code{sts} Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of \code{Py_BuildValue()}, which is something like the inverse of
\code{PyArg_ParseTuple()}: it takes a format string and an arbitrary \cfunction{PyArg_ParseTuple()}: it takes a format string and an arbitrary
number of \C{} values, and returns a new Python object. More info on number of \C{} values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later. \code{Py_BuildValue()} is given later.
@ -331,6 +335,7 @@ pointer, which means ``error'' in most contexts, as we have seen).
\section{The Module's Method Table and Initialization Function} \section{The Module's Method Table and Initialization Function}
\label{methodTable}
I promised to show how \code{spam_system()} is called from Python I promised to show how \code{spam_system()} is called from Python
programs. First, we need to list its name and address in a ``method programs. First, we need to list its name and address in a ``method
@ -349,7 +354,7 @@ Note the third entry (\samp{METH_VARARGS}). This is a flag telling
the interpreter the calling convention to be used for the \C{} the interpreter the calling convention to be used for the \C{}
function. It should normally always be \samp{METH_VARARGS} or function. It should normally always be \samp{METH_VARARGS} or
\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an \samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
obsolete variant of \code{PyArg_ParseTuple()} is used. obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
When using only \samp{METH_VARARGS}, the function should expect When using only \samp{METH_VARARGS}, the function should expect
the Python-level parameters to be passed in as a tuple acceptable for the Python-level parameters to be passed in as a tuple acceptable for
@ -359,7 +364,7 @@ function is provided below.
The \code{METH_KEYWORDS} bit may be set in the third field if keyword The \code{METH_KEYWORDS} bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the \C{} arguments should be passed to the function. In this case, the \C{}
function should accept a third \samp{PyObject *} parameter which will function should accept a third \samp{PyObject *} parameter which will
be a dictionary of keywords. Use \code{PyArg_ParseTupleAndKeywords()} be a dictionary of keywords. Use \cfunction{PyArg_ParseTupleAndKeywords()}
to parse the arguemts to such a function. to parse the arguemts to such a function.
The method table must be passed to the interpreter in the module's The method table must be passed to the interpreter in the module's
@ -387,6 +392,7 @@ so the caller doesn't need to check for errors.
\section{Compilation and Linkage} \section{Compilation and Linkage}
\label{compilation}
There are two more things to do before you can use your new extension: There are two more things to do before you can use your new extension:
compiling and linking it with the Python system. If you use dynamic compiling and linking it with the Python system. If you use dynamic
@ -419,6 +425,7 @@ spam spammodule.o -lX11
\end{verbatim} \end{verbatim}
\section{Calling Python Functions From \C{}} \section{Calling Python Functions From \C{}}
\label{callingPython}
So far we have concentrated on making \C{} functions callable from So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from \C{}. Python. The reverse is also useful: calling Python functions from \C{}.
@ -543,8 +550,9 @@ be checked.
\section{Format Strings for \sectcode{PyArg_ParseTuple()}} \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
\label{parseTuple}
The \code{PyArg_ParseTuple()} function is declared as follows: The \cfunction{PyArg_ParseTuple()} function is declared as follows:
\begin{verbatim} \begin{verbatim}
int PyArg_ParseTuple(PyObject *arg, char *format, ...); int PyArg_ParseTuple(PyObject *arg, char *format, ...);
@ -558,7 +566,7 @@ determined by the format string. For the conversion to succeed, the
\var{arg} object must match the format and the format must be \var{arg} object must match the format and the format must be
exhausted. exhausted.
Note that while \code{PyArg_ParseTuple()} checks that the Python Note that while \cfunction{PyArg_ParseTuple()} checks that the Python
arguments have the required types, it cannot check the validity of the arguments have the required types, it cannot check the validity of the
addresses of \C{} variables passed to the call: if you make mistakes addresses of \C{} variables passed to the call: if you make mistakes
there, your code will probably crash or at least overwrite random bits there, your code will probably crash or at least overwrite random bits
@ -568,7 +576,7 @@ A format string consists of zero or more ``format units''. A format
unit describes one Python object; it is usually a single character or unit describes one Python object; it is usually a single character or
a parenthesized sequence of format units. With a few exceptions, a a parenthesized sequence of format units. With a few exceptions, a
format unit that is not a parenthesized sequence normally corresponds format unit that is not a parenthesized sequence normally corresponds
to a single address argument to \code{PyArg_ParseTuple()}. In the to a single address argument to \cfunction{PyArg_ParseTuple()}. In the
following description, the quoted form is the format unit; the entry following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that matches the in (round) parentheses is the Python object type that matches the
format unit; and the entry in [square] brackets is the type of the \C{} format unit; and the entry in [square] brackets is the type of the \C{}
@ -582,7 +590,7 @@ Convert a Python string to a \C{} pointer to a character string. You
must not provide storage for the string itself; a pointer to an must not provide storage for the string itself; a pointer to an
existing string is stored into the character pointer variable whose existing string is stored into the character pointer variable whose
address you pass. The \C{} string is null-terminated. The Python string address you pass. The \C{} string is null-terminated. The Python string
must not contain embedded null bytes; if it does, a \code{TypeError} must not contain embedded null bytes; if it does, a \exception{TypeError}
exception is raised. exception is raised.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
@ -748,6 +756,7 @@ Some example calls:
\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}} \section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
\label{parseTupleAndKeywords}
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows: follows:
@ -817,6 +826,7 @@ initkeywdarg()
\section{The \sectcode{Py_BuildValue()} Function} \section{The \sectcode{Py_BuildValue()} Function}
\label{buildValue}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows: declared as follows:
@ -945,8 +955,9 @@ Examples (to the left the call, to the right the resulting Python value):
\end{verbatim} \end{verbatim}
\section{Reference Counts} \section{Reference Counts}
\label{refcounts}
\subsection{Introduction} %\subsection{Introduction}
In languages like \C{} or \Cpp{}, the programmer is responsible for In languages like \C{} or \Cpp{}, the programmer is responsible for
dynamic allocation and deallocation of memory on the heap. In \C{}, this dynamic allocation and deallocation of memory on the heap. In \C{}, this
@ -1007,6 +1018,7 @@ will be available for \C{}. Until then, we'll have to live with
reference counts. reference counts.
\subsection{Reference Counting in Python} \subsection{Reference Counting in Python}
\label{refcountsInPython}
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)}, There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
which handle the incrementing and decrementing of the reference count. which handle the incrementing and decrementing of the reference count.
@ -1054,6 +1066,7 @@ and gives full owner responsibilities (i.e., 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).
\subsection{Ownership Rules} \subsection{Ownership Rules}
\label{ownershipRules}
Whenever an object reference is passed into or out of a function, it Whenever an object reference is passed into or out of a function, it
is part of the function's interface specification whether ownership is is part of the function's interface specification whether ownership is
@ -1102,6 +1115,7 @@ Python must be an owned reference --- ownership is tranferred from the
function to its caller. function to its caller.
\subsection{Thin Ice} \subsection{Thin Ice}
\label{thinIce}
There are a few situations where seemingly harmless use of a borrowed There are a few situations where seemingly harmless use of a borrowed
reference can lead to problems. These all have to do with implicit reference can lead to problems. These all have to do with implicit
@ -1181,6 +1195,7 @@ bug(PyObject *list) {
\end{verbatim} \end{verbatim}
\subsection{NULL Pointers} \subsection{NULL Pointers}
\label{nullPointers}
In general, functions that take object references as arguments don't In general, functions that take object references as arguments don't
expect you to pass them \NULL{} pointers, and will dump core (or expect you to pass them \NULL{} pointers, and will dump core (or
@ -1217,6 +1232,7 @@ the Python user.
\section{Writing Extensions in \Cpp{}} \section{Writing Extensions in \Cpp{}}
\label{cplusplus}
It is possible to write extension modules in \Cpp{}. Some restrictions It is possible to write extension modules in \Cpp{}. Some restrictions
apply. If the main program (the Python interpreter) is compiled and apply. If the main program (the Python interpreter) is compiled and
@ -1231,6 +1247,7 @@ It is unnecessary to enclose the Python header files in
symbol). symbol).
\chapter{Embedding Python in another application} \chapter{Embedding Python in another application}
\label{embedding}
Embedding Python is similar to extending it, but not quite. The Embedding Python is similar to extending it, but not quite. The
difference is that when you extend Python, the main program of the difference is that when you extend Python, the main program of the
@ -1258,6 +1275,7 @@ A simple demo of embedding Python can be found in the directory
\section{Embedding Python in \Cpp{}} \section{Embedding Python in \Cpp{}}
\label{embeddingInCplusplus}
It is also possible to embed Python in a \Cpp{} program; precisely how this It is also possible to embed Python in a \Cpp{} program; precisely how this
is done will depend on the details of the \Cpp{} system used; in general you is done will depend on the details of the \Cpp{} system used; in general you
@ -1267,6 +1285,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading} \chapter{Dynamic Loading}
\label{dynload}
On most modern systems it is possible to configure Python to support On most modern systems it is possible to configure Python to support
dynamic loading of extension modules implemented in \C{}. When shared dynamic loading of extension modules implemented in \C{}. When shared
@ -1290,12 +1309,14 @@ loading a module that was compiled for a different version of Python
\section{Configuring and Building the Interpreter for Dynamic Loading} \section{Configuring and Building the Interpreter for Dynamic Loading}
\label{dynloadConfig}
There are three styles of dynamic loading: one using shared libraries, There are three styles of dynamic loading: one using shared libraries,
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
loading. loading.
\subsection{Shared Libraries} \subsection{Shared Libraries}
\label{sharedlibs}
The following systems support dynamic loading using shared libraries: The following systems support dynamic loading using shared libraries:
SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
@ -1308,6 +1329,7 @@ systems --- the \file{configure} detects the presence of the
loading. loading.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
\label{irixDynload}
Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
loading. (SGI IRIX 5 might also support it but it is inferior to loading. (SGI IRIX 5 might also support it but it is inferior to
@ -1329,6 +1351,7 @@ Now build and install Python as you normally would (see the
\file{README} file in the toplevel Python directory.) \file{README} file in the toplevel Python directory.)
\subsection{GNU Dynamic Loading} \subsection{GNU Dynamic Loading}
\label{gnuDynload}
GNU dynamic loading supports (according to its \file{README} file) the GNU dynamic loading supports (according to its \file{README} file) the
following hardware and software combinations: VAX (Ultrix), Sun 3 following hardware and software combinations: VAX (Ultrix), Sun 3
@ -1359,6 +1382,7 @@ will support GNU dynamic loading.
\section{Building a Dynamically Loadable Module} \section{Building a Dynamically Loadable Module}
\label{makedynload}
Since there are three styles of dynamic loading, there are also three Since there are three styles of dynamic loading, there are also three
groups of instructions for building a dynamically loadable module. groups of instructions for building a dynamically loadable module.
@ -1379,6 +1403,7 @@ contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
\subsection{Shared Libraries} \subsection{Shared Libraries}
\label{linking}
You must link the \file{.o} file to produce a shared library. This is You must link the \file{.o} file to produce a shared library. This is
done using a special invocation of the \UNIX{} loader/linker, done using a special invocation of the \UNIX{} loader/linker,
@ -1413,6 +1438,7 @@ along the Python module search path.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
\label{irixLinking}
\strong{IMPORTANT:} You must compile your extension module with the \strong{IMPORTANT:} You must compile your extension module with the
additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the
@ -1441,6 +1467,7 @@ normally only \samp{-l} options or absolute pathnames of libraries
\subsection{GNU Dynamic Loading} \subsection{GNU Dynamic Loading}
\label{gnuLinking}
Just copy \file{spammodule.o} into a directory along the Python module Just copy \file{spammodule.o} into a directory along the Python module
search path. search path.