summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Doc/ext.tex71
-rw-r--r--Doc/ext/ext.tex71
2 files changed, 98 insertions, 44 deletions
diff --git a/Doc/ext.tex b/Doc/ext.tex
index d8d5a43..af745f1 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -30,17 +30,17 @@ dynamically (at run time) into the interpreter, if the underlying
operating system supports this feature.
This document assumes basic knowledge about Python. For an informal
-introduction to the language, see the Python Tutorial. The Python
-Reference Manual gives a more formal definition of the language. The
-Python Library Reference documents the existing object types,
+introduction to the language, see the Python Tutorial. The \emph{Python
+Reference Manual} gives a more formal definition of the language. The
+\emph{Python Library Reference} documents the existing object types,
functions and modules (both built-in and written in Python) that give
the language its wide application range.
For a detailed description of the whole Python/\C{} API, see the separate
-Python/\C{} API Reference Manual. \strong{Note:} While that manual is
-still in a state of flux, it is safe to say that it is much more up to
-date than the manual you're reading currently (which has been in need
-for an upgrade for some time now).
+\emph{Python/\C{} API Reference Manual}. \strong{Note:} While that
+manual is still in a state of flux, it is safe to say that it is much
+more up to date than the manual you're reading currently (which has
+been in need for an upgrade for some time now).
\end{abstract}
@@ -51,7 +51,8 @@ for an upgrade for some time now).
\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
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}
+\label{simpleExample}
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
@@ -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
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
-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{}
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
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
whose addresses are passed. It returns false (zero) if an invalid
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}
+\label{errors}
An important convention throughout the Python interpreter is the
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.
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
\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
\code{PyExc_TypeError} to mean that a file couldn't be opened (that
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
which must be in a particular range or must satisfy other conditions,
\code{PyExc_ValueError} is appropriate.
@@ -277,6 +280,7 @@ the string \code{"spam.error"}.
\section{Back to the Example}
+\label{backToExample}
Going back to our example function, you should now be able to
understand this statement:
@@ -288,7 +292,7 @@ understand this statement:
It returns \NULL{} (the error indicator for functions returning
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
\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
@@ -296,7 +300,7 @@ to modify the string to which it points (so in Standard \C{}, the variable
*command}).
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}
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}
as a Python object. This is done using the function
\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
\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}
+\label{methodTable}
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
@@ -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{}
function. It should normally always be \samp{METH_VARARGS} or
\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
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
arguments should be passed to the function. In this case, the \C{}
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.
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}
+\label{compilation}
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
@@ -419,6 +425,7 @@ spam spammodule.o -lX11
\end{verbatim}
\section{Calling Python Functions From \C{}}
+\label{callingPython}
So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from \C{}.
@@ -543,8 +550,9 @@ be checked.
\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}
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
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
addresses of \C{} variables passed to the call: if you make mistakes
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
a parenthesized sequence of format units. With a few exceptions, a
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
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{}
@@ -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
existing string is stored into the character pointer variable whose
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.
\item[\samp{s\#} (string) {[char *, int]}]
@@ -748,6 +756,7 @@ Some example calls:
\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
+\label{parseTupleAndKeywords}
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows:
@@ -817,6 +826,7 @@ initkeywdarg()
\section{The \sectcode{Py_BuildValue()} Function}
+\label{buildValue}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows:
@@ -945,8 +955,9 @@ Examples (to the left the call, to the right the resulting Python value):
\end{verbatim}
\section{Reference Counts}
+\label{refcounts}
-\subsection{Introduction}
+%\subsection{Introduction}
In languages like \C{} or \Cpp{}, the programmer is responsible for
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.
\subsection{Reference Counting in Python}
+\label{refcountsInPython}
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
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).
\subsection{Ownership Rules}
+\label{ownershipRules}
Whenever an object reference is passed into or out of a function, it
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.
\subsection{Thin Ice}
+\label{thinIce}
There are a few situations where seemingly harmless use of a borrowed
reference can lead to problems. These all have to do with implicit
@@ -1181,6 +1195,7 @@ bug(PyObject *list) {
\end{verbatim}
\subsection{NULL Pointers}
+\label{nullPointers}
In general, functions that take object references as arguments don't
expect you to pass them \NULL{} pointers, and will dump core (or
@@ -1217,6 +1232,7 @@ the Python user.
\section{Writing Extensions in \Cpp{}}
+\label{cplusplus}
It is possible to write extension modules in \Cpp{}. Some restrictions
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).
\chapter{Embedding Python in another application}
+\label{embedding}
Embedding Python is similar to extending it, but not quite. 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{}}
+\label{embeddingInCplusplus}
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
@@ -1267,6 +1285,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading}
+\label{dynload}
On most modern systems it is possible to configure Python to support
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}
+\label{dynloadConfig}
There are three styles of dynamic loading: one using shared libraries,
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
loading.
\subsection{Shared Libraries}
+\label{sharedlibs}
The following systems support dynamic loading using shared libraries:
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.
\subsection{SGI IRIX 4 Dynamic Loading}
+\label{irixDynload}
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
@@ -1329,6 +1351,7 @@ Now build and install Python as you normally would (see the
\file{README} file in the toplevel Python directory.)
\subsection{GNU Dynamic Loading}
+\label{gnuDynload}
GNU dynamic loading supports (according to its \file{README} file) the
following hardware and software combinations: VAX (Ultrix), Sun 3
@@ -1359,6 +1382,7 @@ will support GNU dynamic loading.
\section{Building a Dynamically Loadable Module}
+\label{makedynload}
Since there are three styles of dynamic loading, there are also three
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}
+\label{linking}
You must link the \file{.o} file to produce a shared library. This is
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}
+\label{irixLinking}
\strong{IMPORTANT:} You must compile your extension module with 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}
+\label{gnuLinking}
Just copy \file{spammodule.o} into a directory along the Python module
search path.
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index d8d5a43..af745f1 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -30,17 +30,17 @@ dynamically (at run time) into the interpreter, if the underlying
operating system supports this feature.
This document assumes basic knowledge about Python. For an informal
-introduction to the language, see the Python Tutorial. The Python
-Reference Manual gives a more formal definition of the language. The
-Python Library Reference documents the existing object types,
+introduction to the language, see the Python Tutorial. The \emph{Python
+Reference Manual} gives a more formal definition of the language. The
+\emph{Python Library Reference} documents the existing object types,
functions and modules (both built-in and written in Python) that give
the language its wide application range.
For a detailed description of the whole Python/\C{} API, see the separate
-Python/\C{} API Reference Manual. \strong{Note:} While that manual is
-still in a state of flux, it is safe to say that it is much more up to
-date than the manual you're reading currently (which has been in need
-for an upgrade for some time now).
+\emph{Python/\C{} API Reference Manual}. \strong{Note:} While that
+manual is still in a state of flux, it is safe to say that it is much
+more up to date than the manual you're reading currently (which has
+been in need for an upgrade for some time now).
\end{abstract}
@@ -51,7 +51,8 @@ for an upgrade for some time now).
\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
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}
+\label{simpleExample}
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
@@ -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
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
-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{}
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
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
whose addresses are passed. It returns false (zero) if an invalid
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}
+\label{errors}
An important convention throughout the Python interpreter is the
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.
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
\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
\code{PyExc_TypeError} to mean that a file couldn't be opened (that
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
which must be in a particular range or must satisfy other conditions,
\code{PyExc_ValueError} is appropriate.
@@ -277,6 +280,7 @@ the string \code{"spam.error"}.
\section{Back to the Example}
+\label{backToExample}
Going back to our example function, you should now be able to
understand this statement:
@@ -288,7 +292,7 @@ understand this statement:
It returns \NULL{} (the error indicator for functions returning
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
\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
@@ -296,7 +300,7 @@ to modify the string to which it points (so in Standard \C{}, the variable
*command}).
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}
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}
as a Python object. This is done using the function
\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
\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}
+\label{methodTable}
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
@@ -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{}
function. It should normally always be \samp{METH_VARARGS} or
\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
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
arguments should be passed to the function. In this case, the \C{}
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.
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}
+\label{compilation}
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
@@ -419,6 +425,7 @@ spam spammodule.o -lX11
\end{verbatim}
\section{Calling Python Functions From \C{}}
+\label{callingPython}
So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from \C{}.
@@ -543,8 +550,9 @@ be checked.
\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}
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
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
addresses of \C{} variables passed to the call: if you make mistakes
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
a parenthesized sequence of format units. With a few exceptions, a
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
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{}
@@ -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
existing string is stored into the character pointer variable whose
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.
\item[\samp{s\#} (string) {[char *, int]}]
@@ -748,6 +756,7 @@ Some example calls:
\section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
+\label{parseTupleAndKeywords}
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows:
@@ -817,6 +826,7 @@ initkeywdarg()
\section{The \sectcode{Py_BuildValue()} Function}
+\label{buildValue}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows:
@@ -945,8 +955,9 @@ Examples (to the left the call, to the right the resulting Python value):
\end{verbatim}
\section{Reference Counts}
+\label{refcounts}
-\subsection{Introduction}
+%\subsection{Introduction}
In languages like \C{} or \Cpp{}, the programmer is responsible for
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.
\subsection{Reference Counting in Python}
+\label{refcountsInPython}
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
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).
\subsection{Ownership Rules}
+\label{ownershipRules}
Whenever an object reference is passed into or out of a function, it
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.
\subsection{Thin Ice}
+\label{thinIce}
There are a few situations where seemingly harmless use of a borrowed
reference can lead to problems. These all have to do with implicit
@@ -1181,6 +1195,7 @@ bug(PyObject *list) {
\end{verbatim}
\subsection{NULL Pointers}
+\label{nullPointers}
In general, functions that take object references as arguments don't
expect you to pass them \NULL{} pointers, and will dump core (or
@@ -1217,6 +1232,7 @@ the Python user.
\section{Writing Extensions in \Cpp{}}
+\label{cplusplus}
It is possible to write extension modules in \Cpp{}. Some restrictions
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).
\chapter{Embedding Python in another application}
+\label{embedding}
Embedding Python is similar to extending it, but not quite. 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{}}
+\label{embeddingInCplusplus}
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
@@ -1267,6 +1285,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading}
+\label{dynload}
On most modern systems it is possible to configure Python to support
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}
+\label{dynloadConfig}
There are three styles of dynamic loading: one using shared libraries,
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
loading.
\subsection{Shared Libraries}
+\label{sharedlibs}
The following systems support dynamic loading using shared libraries:
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.
\subsection{SGI IRIX 4 Dynamic Loading}
+\label{irixDynload}
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
@@ -1329,6 +1351,7 @@ Now build and install Python as you normally would (see the
\file{README} file in the toplevel Python directory.)
\subsection{GNU Dynamic Loading}
+\label{gnuDynload}
GNU dynamic loading supports (according to its \file{README} file) the
following hardware and software combinations: VAX (Ultrix), Sun 3
@@ -1359,6 +1382,7 @@ will support GNU dynamic loading.
\section{Building a Dynamically Loadable Module}
+\label{makedynload}
Since there are three styles of dynamic loading, there are also three
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}
+\label{linking}
You must link the \file{.o} file to produce a shared library. This is
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}
+\label{irixLinking}
\strong{IMPORTANT:} You must compile your extension module with 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}
+\label{gnuLinking}
Just copy \file{spammodule.o} into a directory along the Python module
search path.
generated by cgit v0.12 at 2024-10-10 19:19:15 (GMT)