mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Several changes, e.g. restructuring of the intro to be closer to what

Browse source 
it ought to be.  Maybe the last checkin before 1.5b1 is released.
This commit is contained in:
Guido van Rossum 1997-11-25 15:34:51 +00:00
parent 682fbe55e5
commit 580aa8dbc3
2 changed files with 272 additions and 476 deletions
Download patch file Download diff file Expand all files Collapse all files

374
Doc/api.tex
View file

@ -44,13 +44,13 @@ API functions in detail.
The Application Programmer's Interface to Python gives C and C++ The Application Programmer's Interface to Python gives C and C++
programmers access to the Python interpreter at a variety of levels. programmers access to the Python interpreter at a variety of levels.
There are two fundamentally different reasons for using the Python/C The API is equally usable from C++, but for brevity it is generally
API. (The API is equally usable from C++, but for brevity it is referred to as the Python/C API. There are two fundamentally
generally referred to as the Python/C API.) The first reason is to different reasons for using the Python/C API. The first reason is to
write ``extension modules'' for specific purposes; these are C modules write ``extension modules'' for specific purposes; these are C modules
that extend the Python interpreter. This is probably the most common that extend the Python interpreter. This is probably the most common
use. The second reason is to use Python as a component in a larger use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as ``embedding'' application; this technique is generally referred to as ``embedding''
Python in an application. Python in an application.
Writing an extension module is a relatively well-understood process, Writing an extension module is a relatively well-understood process,
@ -60,7 +60,7 @@ Python in other applications since its early existence, the process of
embedding Python is less straightforward that writing an extension. embedding Python is less straightforward that writing an extension.
Python 1.5 introduces a number of new API functions as well as some Python 1.5 introduces a number of new API functions as well as some
changes to the build process that make embedding much simpler. changes to the build process that make embedding much simpler.
This manual describes the 1.5 state of affair (as of Python 1.5a3). This manual describes the 1.5 state of affair.
% XXX Eventually, take the historical notes out % XXX Eventually, take the historical notes out
Many API functions are useful independent of whether you're embedding Many API functions are useful independent of whether you're embedding
@ -69,16 +69,36 @@ will need to provide a custom extension as well, so it's probably a
good idea to become familiar with writing an extension before good idea to become familiar with writing an extension before
attempting to embed Python in a real application. attempting to embed Python in a real application.
\section{Include Files}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
\code{\#include "Python.h"}
This implies inclusion of the following standard header files:
stdio.h, string.h, errno.h, and stdlib.h (if available).
All user visible names defined by Python.h (except those defined by
the included standard headers) have one of the prefixes \code{Py} or
\code{_Py}. Names beginning with \code{_Py} are for internal use
only. Structure member names do not have a reserved prefix.
Important: user code should never define names that begin with
\code{Py} or \code{_Py}. This confuses the reader, and jeopardizes
the portability of the user code to future Python versions, which may
define additional names beginning with one of these prefixes.
\section{Objects, Types and Reference Counts} \section{Objects, Types and Reference Counts}
Most Python/C API functions have one or more arguments as well as a Most Python/C API functions have one or more arguments as well as a
return value of type \code{PyObject *}. This type is a pointer return value of type \code{PyObject *}. This type is a pointer
(obviously!) to an opaque data type representing an arbitrary Python (obviously!) to an opaque data type representing an arbitrary Python
object. Since all Python object types are treated the same way by the object. Since all Python object types are treated the same way by the
Python language in most situations (e.g., assignments, scope rules, Python language in most situations (e.g., assignments, scope rules,
and argument passing), it is only fitting that they should be and argument passing), it is only fitting that they should be
represented by a single C type. All Python objects live on the heap: represented by a single C type. All Python objects live on the heap:
you never declare an automatic or static variable of type you never declare an automatic or static variable of type
\code{PyObject}, only pointer variables of type \code{PyObject *} can \code{PyObject}, only pointer variables of type \code{PyObject *} can
be declared. be declared.
@ -92,7 +112,7 @@ iff the object pointed to by \code{a} is a Python list.
\subsection{Reference Counts} \subsection{Reference Counts}
The reference count is important only because today's computers have a The reference count is important because today's computers have a
finite (and often severly limited) memory size; it counts how many finite (and often severly limited) memory size; it counts how many
different places there are that have a reference to an object. Such a different places there are that have a reference to an object. Such a
place could be another object, or a global (or static) C variable, or place could be another object, or a global (or static) C variable, or
@ -154,7 +174,7 @@ they are done with the result; this soon becomes second nature.
The reference count behavior of functions in the Python/C API is best The reference count behavior of functions in the Python/C API is best
expelained in terms of \emph{ownership of references}. Note that we expelained in terms of \emph{ownership of references}. Note that we
talk of owning reference, never of owning objects; objects are always talk of owning references, never of owning objects; objects are always
shared! When a function owns a reference, it has to dispose of it shared! When a function owns a reference, it has to dispose of it
properly -- either by passing ownership on (usually to its caller) or properly -- either by passing ownership on (usually to its caller) or
by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function
@ -163,16 +183,17 @@ to receive a \emph{new} reference. When to ownership is transferred,
the caller is said to \emph{borrow} the reference. Nothing needs to the caller is said to \emph{borrow} the reference. Nothing needs to
be done for a borrowed reference. be done for a borrowed reference.
Conversely, when calling a function while passing it a reference to an Conversely, when calling a function passes it a reference to an
object, there are two possibilities: the function \emph{steals} a object, there are two possibilities: the function \emph{steals} a
reference to the object, or it does not. Few functions steal reference to the object, or it does not. Few functions steal
references; the two notable exceptions are \code{PyList_SetItem()} and references; the two notable exceptions are \code{PyList_SetItem()} and
\code{PyTuple_SetItem()}, which steal a reference to the item (but not to \code{PyTuple_SetItem()}, which steal a reference to the item (but not to
the tuple or list into which the item it put!). These functions were the tuple or list into which the item it put!). These functions were
designed to steal a reference because of a common idiom for designed to steal a reference because of a common idiom for populating
populating a tuple or list with newly created objects; e.g., the code a tuple or list with newly created objects; for example, the code to
to create the tuple \code{(1, 2, "three")} could look like this create the tuple \code{(1, 2, "three")} could look like this
(forgetting about error handling for the moment): (forgetting about error handling for the moment; a better way to code
this is shown below anyway):
\begin{verbatim} \begin{verbatim}
PyObject *t; PyObject *t;
@ -203,10 +224,10 @@ x = PyString_FromString("three");
PyObject_SetItem(l, 2, x); Py_DECREF(x); PyObject_SetItem(l, 2, x); Py_DECREF(x);
\end{verbatim} \end{verbatim}
You might find it strange that the ``recommended'' approach takes You might find it strange that the ``recommended'' approach takes more
more code. in practice, you will rarely use these ways of creating code. However, in practice, you will rarely use these ways of
and populating a tuple or list, however; there's a generic function, creating and populating a tuple or list. There's a generic function,
\code{Py_BuildValue()} that can create most common objects from C \code{Py_BuildValue()}, that can create most common objects from C
values, directed by a ``format string''. For example, the above two values, directed by a ``format string''. For example, the above two
blocks of code could be replaced by the following (which also takes blocks of code could be replaced by the following (which also takes
care of the error checking!): care of the error checking!):
@ -306,7 +327,7 @@ long sum_sequence(PyObject *sequence)
\subsection{Types} \subsection{Types}
There are few other data types that play a significant role in There are few other data types that play a significant role in
the Python/C API; most are all simple C types such as \code{int}, the Python/C API; most are simple C types such as \code{int},
\code{long}, \code{double} and \code{char *}. A few structure types \code{long}, \code{double} and \code{char *}. A few structure types
are used to describe static tables used to list the functions exported are used to describe static tables used to list the functions exported
by a module or the data attributes of a new object type. These will by a module or the data attributes of a new object type. These will
@ -325,7 +346,7 @@ All functions in the Python/C API can raise exceptions, unless an
explicit claim is made otherwise in a function's documentation. In explicit claim is made otherwise in a function's documentation. In
general, when a function encounters an error, it sets an exception, general, when a function encounters an error, it sets an exception,
discards any object references that it owns, and returns an discards any object references that it owns, and returns an
error indicator -- usually \code{NULL} or \code{-1}. A few functions error indicator -- usually \NULL{} or \code{-1}. A few functions
return a Boolean true/false result, with false indicating an error. return a Boolean true/false result, with false indicating an error.
Very few functions return no explicit error indicator or have an Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with ambiguous return value, and require explicit testing for errors with
@ -336,13 +357,13 @@ equivalent to using global storage in an unthreaded application). A
thread can be on one of two states: an exception has occurred, or not. thread can be on one of two states: an exception has occurred, or not.
The function \code{PyErr_Occurred()} can be used to check for this: it The function \code{PyErr_Occurred()} can be used to check for this: it
returns a borrowed reference to the exception type object when an returns a borrowed reference to the exception type object when an
exception has occurred, and \code{NULL} otherwise. There are a number exception has occurred, and \NULL{} otherwise. There are a number
of functions to set the exception state: \code{PyErr_SetString()} is of functions to set the exception state: \code{PyErr_SetString()} is
the most common (though not the most general) function to set the the most common (though not the most general) function to set the
exception state, and \code{PyErr_Clear()} clears the exception state. exception state, and \code{PyErr_Clear()} clears the exception state.
The full exception state consists of three objects (all of which can The full exception state consists of three objects (all of which can
be \code{NULL} ): the exception type, the corresponding exception be \NULL{} ): the exception type, the corresponding exception
value, and the traceback. These have the same meanings as the Python value, and the traceback. These have the same meanings as the Python
object \code{sys.exc_type}, \code{sys.exc_value}, object \code{sys.exc_type}, \code{sys.exc_value},
\code{sys.exc_traceback}; however, they are not the same: the Python \code{sys.exc_traceback}; however, they are not the same: the Python
@ -376,37 +397,35 @@ A simple example of detecting exceptions and passing them on is shown
in the \code{sum_sequence()} example above. It so happens that that in the \code{sum_sequence()} example above. It so happens that that
example doesn't need to clean up any owned references when it detects example doesn't need to clean up any owned references when it detects
an error. The following example function shows some error cleanup. an error. The following example function shows some error cleanup.
First we show the equivalent Python code (to remind you why you like First, to remind you why you like Python, we show the equivalent
Python): Python code:
\begin{verbatim} \begin{verbatim}
def incr_item(seq, i): def incr_item(dict, key):
try: try:
item = seq[i] item = dict[key]
except IndexError: except KeyError:
item = 0 item = 0
seq[i] = item + 1 return item + 1
\end{verbatim} \end{verbatim}
Here is the corresponding C code, in all its glory: Here is the corresponding C code, in all its glory:
% XXX Is it better to have fewer comments in the code?
\begin{verbatim} \begin{verbatim}
int incr_item(PyObject *seq, int i) int incr_item(PyObject *dict, PyObject *key)
{ {
/* Objects all initialized to NULL for Py_XDECREF */ /* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (faulure) */ int rv = -1; /* Return value initialized to -1 (faulure) */
item = PySequence_GetItem(seq, i); item = PyObject_GetItem(dict, key);
if (item == NULL) { if (item == NULL) {
/* Handle IndexError only: */ /* Handle keyError only: */
if (PyErr_Occurred() != PyExc_IndexError) goto error; if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
/* Clear the error and use zero: */ /* Clear the error and use zero: */
PyErr_Clear(); PyErr_Clear();
item = PyInt_FromLong(1L); item = PyInt_FromLong(0L);
if (item == NULL) goto error; if (item == NULL) goto error;
} }
@ -416,7 +435,7 @@ int incr_item(PyObject *seq, int i)
incremented_item = PyNumber_Add(item, const_one); incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL) goto error; if (incremented_item == NULL) goto error;
if (PyObject_SetItem(seq, i, incremented_item) < 0) goto error; if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
rv = 0; /* Success */ rv = 0; /* Success */
/* Continue with cleanup code */ /* Continue with cleanup code */
@ -433,24 +452,24 @@ int incr_item(PyObject *seq, int i)
\end{verbatim} \end{verbatim}
This example represents an endorsed use of the \code{goto} statement This example represents an endorsed use of the \code{goto} statement
in C! It illustrates the use of \code{PyErr_Occurred()} and in C! It illustrates the use of \code{PyErr_ExceptionMatches()} and
\code{PyErr_Clear()} to handle specific exceptions, and the use of \code{PyErr_Clear()} to handle specific exceptions, and the use of
\code{Py_XDECREF()} to dispose of owned references that may be \code{Py_XDECREF()} to dispose of owned references that may be
\code{NULL} (note the `X' in the name; \code{Py_DECREF()} would crash \NULL{} (note the `X' in the name; \code{Py_DECREF()} would crash
when confronted with a \code{NULL} reference). It is important that when confronted with a \NULL{} reference). It is important that
the variables used to hold owned references are initialized to the variables used to hold owned references are initialized to
\code{NULL} for this to work; likewise, the proposed return value is \NULL{} for this to work; likewise, the proposed return value is
initialized to \code{-1} (failure) and only set to success after initialized to \code{-1} (failure) and only set to success after
the final call made is succesful. the final call made is succesful.
\section{Embedding Python} \section{Embedding Python}
The one important task that only embedders of the Python interpreter The one important task that only embedders (as opposed to extension
have to worry about is the initialization (and possibly the writers) of the Python interpreter have to worry about is the
finalization) of the Python interpreter. Most functionality of the initialization, and possibly the finalization, of the Python
interpreter can only be used after the interpreter has been interpreter. Most functionality of the interpreter can only be used
initialized. after the interpreter has been initialized.
The basic initialization function is \code{Py_Initialize()}. This The basic initialization function is \code{Py_Initialize()}. This
initializes the table of loaded modules, and creates the fundamental initializes the table of loaded modules, and creates the fundamental
@ -476,189 +495,64 @@ path (the environment variable \code{\$PATH}).
For instance, if the Python executable is found in For instance, if the Python executable is found in
\code{/usr/local/bin/python}, it will assume that the libraries are in \code{/usr/local/bin/python}, it will assume that the libraries are in
\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' \code{/usr/local/lib/python1.5}. (In fact, this particular path is
location, used when no executable file named \code{python} is found also the ``fallback'' location, used when no executable file named
along \code{\$PATH}. The user can change this behavior by setting the \code{python} is found along \code{\$PATH}.) The user can override
environment variable \code{\$PYTHONHOME}, and can insert additional this behavior by setting the environment variable \code{\$PYTHONHOME},
directories in front of the standard path by setting or insert additional directories in front of the standard path by
\code{\$PYTHONPATH}. setting \code{\$PYTHONPATH}.
The embedding application can steer the search by calling The embedding application can steer the search by calling
\code{Py_SetProgramName(\var{file})} \emph{before} calling \code{Py_SetProgramName(\var{file})} \emph{before} calling
\code{Py_Initialize()}. Note that \code{\$PYTHONHOME} still overrides \code{Py_Initialize()}. Note that \code{\$PYTHONHOME} still overrides
this and \code{\$PYTHONPATH} is still inserted in front of the this and \code{\$PYTHONPATH} is still inserted in front of the
standard path. standard path. An application that requires total control has to
provide its own implementation of \code{Py_GetPath()},
\code{Py_GetPrefix()}, \code{Py_GetExecPrefix()},
\code{Py_GetProgramFullPath()} (all defined in
\file{Modules/getpath.c}).
Sometimes, it is desirable to ``uninitialize'' Python. For instance, Sometimes, it is desirable to ``uninitialize'' Python. For instance,
the application may want to start over (make another call to the application may want to start over (make another call to
\code{Py_Initialize()}) or the application is simply done with its \code{Py_Initialize()}) or the application is simply done with its
use of Python and wants to free all memory allocated by Python. This use of Python and wants to free all memory allocated by Python. This
can be accomplished by calling \code{Py_Finalize()}. can be accomplished by calling \code{Py_Finalize()}. The function
% XXX More... \code{Py_IsInitialized()} returns true iff Python is currently in the
initialized state. More information about these functions is given in
\section{Embedding Python in Threaded Applications} a later chapter.
\chapter{Basic Utilities}
XXX These utilities should be moved to some other section...
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and kill the process. No cleanup is
performed. This function should only be invoked when a condition is
detected that would make it dangerous to continue using the Python
interpreter; e.g., when the object administration appears to be
corrupted. On Unix, the standard C library function \code{abort()} is
\chapter{Old Introduction} called which will attempt to produce a \file{core} file.
(XXX This is the old introduction, mostly by Jim Fulton -- should be
rewritten.)
From the viewpoint of of C access to Python services, we have:
\begin{enumerate}
\item "Very high level layer": two or three functions that let you
exec or eval arbitrary Python code given as a string in a module whose
name is given, passing C values in and getting C values out using
mkvalue/getargs style format strings. This does not require the user
to declare any variables of type \code{PyObject *}. This should be
enough to write a simple application that gets Python code from the
user, execs it, and returns the output or errors.
\item "Abstract objects layer": which is the subject of this chapter.
It has many functions operating on objects, and lets you do many
things from C that you can also write in Python, without going through
the Python parser.
\item "Concrete objects layer": This is the public type-dependent
interface provided by the standard built-in types, such as floats,
strings, and lists. This interface exists and is currently documented
by the collection of include files provides with the Python
distributions.
\end{enumerate}
From the point of view of Python accessing services provided by C
modules:
\begin{enumerate}
\item[4.] "Python module interface": this interface consist of the basic
routines used to define modules and their members. Most of the
current extensions-writing guide deals with this interface.
\item[5.] "Built-in object interface": this is the interface that a new
built-in type must provide and the mechanisms and rules that a
developer of a new built-in type must use and follow.
\end{enumerate}
The Python C API provides four groups of operations on objects,
corresponding to the same operations in the Python language: object,
numeric, sequence, and mapping. Each protocol consists of a
collection of related operations. If an operation that is not
provided by a particular type is invoked, then the standard exception
\code{TypeError} is raised with a operation name as an argument.
In addition, for convenience this interface defines a set of
constructors for building objects of built-in types. This is needed
so new objects can be returned from C functions that otherwise treat
objects generically.
\section{Reference Counting}
For most of the functions in the Python/C API, if a function retains a
reference to a Python object passed as an argument, then the function
will increase the reference count of the object. It is unnecessary
for the caller to increase the reference count of an argument in
anticipation of the object's retention.
Usually, Python objects returned from functions should be treated as
new objects. Functions that return objects assume that the caller
will retain a reference and the reference count of the object has
already been incremented to account for this fact. A caller that does
not retain a reference to an object that is returned from a function
must decrement the reference count of the object (using
\code{Py_DECREF()}) to prevent memory leaks.
Exceptions to these rules will be noted with the individual functions.
\section{Include Files}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
\code{\#include "Python.h"}
This implies inclusion of the following standard header files:
stdio.h, string.h, errno.h, and stdlib.h (if available).
All user visible names defined by Python.h (except those defined by
the included standard headers) have one of the prefixes \code{Py} or
\code{_Py}. Names beginning with \code{_Py} are for internal use
only.
\chapter{Initialization and Shutdown of an Embedded Python Interpreter}
When embedding the Python interpreter in a C or C++ program, the
interpreter must be initialized.
\begin{cfuncdesc}{void}{PyInitialize}{}
This function initializes the interpreter. It must be called before
any interaction with the interpreter takes place. If it is called
more than once, the second and further calls have no effect.
The function performs the following tasks: create an environment in
which modules can be imported and Python code can be executed;
initialize the \code{__builtin__} module; initialize the \code{sys}
module; initialize \code{sys.path}; initialize signal handling; and
create the empty \code{__main__} module.
In the current system, there is no way to undo all these
initializations or to create additional interpreter environments.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
Register a cleanup function to be called when Python exits. The
cleanup function will be called with no arguments and should return no
value. At most 32 cleanup functions can be registered. When the
registration is successful, \code{Py_AtExit} returns 0; on failure, it
returns -1. Each cleanup function will be called t most once. The
cleanup function registered last is called first.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Exit}{int status} \begin{cfuncdesc}{void}{Py_Exit}{int status}
Exit the current process. This calls \code{Py_Cleanup()} (see next Exit the current process. This calls \code{Py_Finalize()} and then
item) and performs additional cleanup (under some circumstances it calls the standard C library function \code{exit(0)}.
will attempt to delete all modules), and then calls the standard C
library function \code{exit(status)}.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Cleanup}{} \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
Perform some of the cleanup that \code{Py_Exit} performs, but don't Register a cleanup function to be called by \code{Py_Finalize()}. The
exit the process. In particular, this invokes the user's cleanup function will be called with no arguments and should return no
\code{sys.exitfunc} function (if defined at all), and it invokes the value. At most 32 cleanup functions can be registered. When the
cleanup functions registered with \code{Py_AtExit()}, in reverse order registration is successful, \code{Py_AtExit} returns 0; on failure, it
of their registration. returns -1. The cleanup function registered last is called first.
Each cleanup function will be called at most once.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and die. No cleanup is performed. This
function should only be invoked when a condition is detected that
would make it dangerous to continue using the Python interpreter;
e.g., when the object administration appears to be corrupted.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyBuiltin_Init}{}
Initialize the \code{__builtin__} module. For internal use only.
\end{cfuncdesc}
XXX Other init functions: PyOS_InitInterrupts,
PyMarshal_Init, PySys_Init.
\chapter{Reference Counting} \chapter{Reference Counting}
The functions in this chapter are used for managing reference counts The macros in this section are used for managing reference counts
of Python objects. of Python objects.
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
@ -669,7 +563,7 @@ not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
Increment the reference count for object \code{o}. The object may be Increment the reference count for object \code{o}. The object may be
\NULL{}, in which case the function has no effect. \NULL{}, in which case the macro has no effect.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
@ -692,15 +586,19 @@ temporary variable.
\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
Decrement the reference count for object \code{o}.The object may be Decrement the reference count for object \code{o}.The object may be
\NULL{}, in which case the function has no effect; otherwise the \NULL{}, in which case the macro has no effect; otherwise the
effect is the same as for \code{Py_DECREF()}, and the same warning effect is the same as for \code{Py_DECREF()}, and the same warning
applies. applies.
\end{cfuncdesc} \end{cfuncdesc}
The following functions are only for internal use: The following functions or macros are only for internal use:
\code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_Py_NewReference}, \code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_Py_NewReference},
as well as the global variable \code{_Py_RefTotal}. as well as the global variable \code{_Py_RefTotal}.
XXX Should mention Py_Malloc(), Py_Realloc(), Py_Free(),
PyMem_Malloc(), PyMem_Realloc(), PyMem_Free(), PyMem_NEW(),
PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
\chapter{Exception Handling} \chapter{Exception Handling}
@ -875,7 +773,7 @@ PyObject *base, PyObject *dict}
This utility function creates and returns a new exception object. The This utility function creates and returns a new exception object. The
\var{name} argument must be the name of the new exception, a C string \var{name} argument must be the name of the new exception, a C string
of the form \code{module.class}. The \var{base} and \var{dict} of the form \code{module.class}. The \var{base} and \var{dict}
arguments are normally \code{NULL}. Normally, this creates a class arguments are normally \NULL{}. Normally, this creates a class
object derived from the root for all exceptions, the built-in name object derived from the root for all exceptions, the built-in name
\code{Exception} (accessible in C as \code{PyExc_Exception}). In this \code{Exception} (accessible in C as \code{PyExc_Exception}). In this
case the \code{__module__} attribute of the new class is set to the case the \code{__module__} attribute of the new class is set to the
@ -883,7 +781,7 @@ first part (up to the last dot) of the \var{name} argument, and the
class name is set to the last part (after the last dot). When the class name is set to the last part (after the last dot). When the
user has specified the \code{-X} command line option to use string user has specified the \code{-X} command line option to use string
exceptions, for backward compatibility, or when the \var{base} exceptions, for backward compatibility, or when the \var{base}
argument is not a class object (and not \code{NULL}), a string object argument is not a class object (and not \NULL{}), a string object
created from the entire \var{name} argument is returned. The created from the entire \var{name} argument is returned. The
\var{base} argument can be used to specify an alternate base class. \var{base} argument can be used to specify an alternate base class.
The \var{dict} argument can be used to specify a dictionary of class The \var{dict} argument can be used to specify a dictionary of class
@ -952,7 +850,7 @@ the standard C library function \code{time()}.
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} \begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \code{PyImport_ImportModuleEx} This is a simplified interface to \code{PyImport_ImportModuleEx}
below, leaving the \var{globals} and \var{locals} arguments set to below, leaving the \var{globals} and \var{locals} arguments set to
\code{NULL}. When the \var{name} argument contains a dot (i.e., when \NULL{}. When the \var{name} argument contains a dot (i.e., when
it specifies a submodule of a package), the \var{fromlist} argument is it specifies a submodule of a package), the \var{fromlist} argument is
set to the list \code{['*']} so that the return value is the named set to the list \code{['*']} so that the return value is the named
module rather than the top-level package containing it as would module rather than the top-level package containing it as would
@ -960,7 +858,7 @@ otherwise be the case. (Unfortunately, this has an additional side
effect when \var{name} in fact specifies a subpackage instead of a effect when \var{name} in fact specifies a subpackage instead of a
submodule: the submodules specified in the package's \code{__all__} submodule: the submodules specified in the package's \code{__all__}
variable are loaded.) Return a new reference to the imported module, variable are loaded.) Return a new reference to the imported module,
or \code{NULL} with an exception set on failure (the module may still or \NULL{} with an exception set on failure (the module may still
be created in this case). be created in this case).
\end{cfuncdesc} \end{cfuncdesc}
@ -971,7 +869,7 @@ Python function \code{__import()__}, as the standard
\code{__import__()} function calls this function directly. \code{__import__()} function calls this function directly.
The return value is a new reference to the imported module or The return value is a new reference to the imported module or
top-level package, or \code{NULL} with an exception set on failure top-level package, or \NULL{} with an exception set on failure
(the module may still be created in this case). Like for (the module may still be created in this case). Like for
\code{__import__()}, the return value when a submodule of a package \code{__import__()}, the return value when a submodule of a package
was requested is normally the top-level package, unless a non-empty was requested is normally the top-level package, unless a non-empty
@ -990,7 +888,7 @@ current environment, e.g. by \code{rexec} or \code{ihooks}.
Reload a module. This is best described by referring to the built-in Reload a module. This is best described by referring to the built-in
Python function \code{reload()}, as the standard \code{reload()} Python function \code{reload()}, as the standard \code{reload()}
function calls this function directly. Return a new reference to the function calls this function directly. Return a new reference to the
reloaded module, or \code{NULL} with an exception set on failure (the reloaded module, or \NULL{} with an exception set on failure (the
module still exists in this case). module still exists in this case).
\end{cfuncdesc} \end{cfuncdesc}
@ -1000,7 +898,7 @@ Return the module object corresponding to a module name. The
check the modules dictionary if there's one there, and if not, create check the modules dictionary if there's one there, and if not, create
a new one and insert in in the modules dictionary. Because the former a new one and insert in in the modules dictionary. Because the former
action is most common, this does not return a new reference, and you action is most common, this does not return a new reference, and you
do not own the returned reference. Return \code{NULL} with an do not own the returned reference. Return \NULL{} with an
exception set on failure. exception set on failure.
\end{cfuncdesc} \end{cfuncdesc}
@ -1008,7 +906,7 @@ exception set on failure.
Given a module name (possibly of the form \code{package.module}) and a Given a module name (possibly of the form \code{package.module}) and a
code object read from a Python bytecode file or obtained from the code object read from a Python bytecode file or obtained from the
built-in function \code{compile()}, load the module. Return a new built-in function \code{compile()}, load the module. Return a new
reference to the module object, or \code{NULL} with an exception set reference to the module object, or \NULL{} with an exception set
if an error occurred (the module may still be created in this case). if an error occurred (the module may still be created in this case).
(This function would reload the module if it was already imported.) (This function would reload the module if it was already imported.)
\end{cfuncdesc} \end{cfuncdesc}
@ -1069,7 +967,7 @@ struct _frozen {
\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules} \begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
This pointer is initialized to point to an array of \code{struct This pointer is initialized to point to an array of \code{struct
_frozen} records, terminated by one whose members are all \code{NULL} _frozen} records, terminated by one whose members are all \NULL{}
or zero. When a frozen module is imported, it is searched in this or zero. When a frozen module is imported, it is searched in this
table. Third party code could play tricks with this to provide a table. Third party code could play tricks with this to provide a
dynamically created collection of frozen modules. dynamically created collection of frozen modules.
@ -1798,7 +1696,7 @@ The return value points to the first thread state created in the new
sub-interpreter. This thread state is made the current thread state. sub-interpreter. This thread state is made the current thread state.
Note that no actual thread is created; see the discussion of thread Note that no actual thread is created; see the discussion of thread
states below. If creation of the new interpreter is unsuccessful, states below. If creation of the new interpreter is unsuccessful,
\code{NULL} is returned; no exception is set since the exception state \NULL{} is returned; no exception is set since the exception state
is stored in the current thread state and there may not be a current is stored in the current thread state and there may not be a current
thread state. (Like all other Python/C API functions, the global thread state. (Like all other Python/C API functions, the global
interpreter lock must be held before calling this function and is interpreter lock must be held before calling this function and is
@ -1839,7 +1737,7 @@ a hard-to-fix bug that will be addressed in a future release.)
Destroy the (sub-)interpreter represented by the given thread state. Destroy the (sub-)interpreter represented by the given thread state.
The given thread state must be the current thread state. See the The given thread state must be the current thread state. See the
discussion of thread states below. When the call returns, the current discussion of thread states below. When the call returns, the current
thread state is \code{NULL}. All thread states associated with this thread state is \NULL{}. All thread states associated with this
interpreted are destroyed. (The global interpreter lock must be held interpreted are destroyed. (The global interpreter lock must be held
before calling this function and is still held when it returns.) before calling this function and is still held when it returns.)
\code{Py_Finalize()} will destroy all sub-interpreters that haven't \code{Py_Finalize()} will destroy all sub-interpreters that haven't
@ -2205,7 +2103,7 @@ compile time.
\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
\strong{(NEW in 1.5a3!)} \strong{(NEW in 1.5a3!)}
Acquire the global interpreter lock and then set the current thread Acquire the global interpreter lock and then set the current thread
state to \var{tstate}, which should not be \code{NULL}. The lock must state to \var{tstate}, which should not be \NULL{}. The lock must
have been created earlier. If this thread already has the lock, have been created earlier. If this thread already has the lock,
deadlock ensues. This function is not available when thread support deadlock ensues. This function is not available when thread support
is disabled at is disabled at
@ -2214,10 +2112,10 @@ compile time.
\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
\strong{(NEW in 1.5a3!)} \strong{(NEW in 1.5a3!)}
Reset the current thread state to \code{NULL} and release the global Reset the current thread state to \NULL{} and release the global
interpreter lock. The lock must have been created earlier and must be interpreter lock. The lock must have been created earlier and must be
held by the current thread. The \var{tstate} argument, which must not held by the current thread. The \var{tstate} argument, which must not
be \code{NULL}, is only used to check that it represents the current be \NULL{}, is only used to check that it represents the current
thread state -- if it isn't, a fatal error is reported. This function thread state -- if it isn't, a fatal error is reported. This function
is not available when thread support is disabled at is not available when thread support is disabled at
compile time. compile time.
@ -2226,8 +2124,8 @@ compile time.
\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{} \begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
\strong{(Different return type in 1.5a3!)} \strong{(Different return type in 1.5a3!)}
Release the interpreter lock (if it has been created and thread Release the interpreter lock (if it has been created and thread
support is enabled) and reset the thread state to \code{NULL}, support is enabled) and reset the thread state to \NULL{},
returning the previous thread state (which is not \code{NULL}). If returning the previous thread state (which is not \NULL{}). If
the lock has been created, the current thread must have acquired it. the lock has been created, the current thread must have acquired it.
(This function is available even when thread support is disabled at (This function is available even when thread support is disabled at
compile time.) compile time.)
@ -2237,7 +2135,7 @@ compile time.)
\strong{(Different argument type in 1.5a3!)} \strong{(Different argument type in 1.5a3!)}
Acquire the interpreter lock (if it has been created and thread Acquire the interpreter lock (if it has been created and thread
support is enabled) and set the thread state to \var{tstate}, which support is enabled) and set the thread state to \var{tstate}, which
must not be \code{NULL}. If the lock has been created, the current must not be \NULL{}. If the lock has been created, the current
thread must not have acquired it, otherwise deadlock ensues. (This thread must not have acquired it, otherwise deadlock ensues. (This
function is available even when thread support is disabled at compile function is available even when thread support is disabled at compile
time.) time.)
@ -2314,13 +2212,13 @@ call to \code{PyThreadState_Clear()}.
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{} \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
Return the current thread state. The interpreter lock must be held. Return the current thread state. The interpreter lock must be held.
When the current thread state is \code{NULL}, this issues a fatal When the current thread state is \NULL{}, this issues a fatal
error (so that the caller needn't check for \code{NULL}. error (so that the caller needn't check for \NULL{}.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate} \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
Swap the current thread state with the thread state given by the Swap the current thread state with the thread state given by the
argument \var{tstate}, which may be \code{NULL}. The interpreter lock argument \var{tstate}, which may be \NULL{}. The interpreter lock
must be held. must be held.
\end{cfuncdesc} \end{cfuncdesc}

374
Doc/api/api.tex
View file

@ -44,13 +44,13 @@ API functions in detail.
The Application Programmer's Interface to Python gives C and C++ The Application Programmer's Interface to Python gives C and C++
programmers access to the Python interpreter at a variety of levels. programmers access to the Python interpreter at a variety of levels.
There are two fundamentally different reasons for using the Python/C The API is equally usable from C++, but for brevity it is generally
API. (The API is equally usable from C++, but for brevity it is referred to as the Python/C API. There are two fundamentally
generally referred to as the Python/C API.) The first reason is to different reasons for using the Python/C API. The first reason is to
write ``extension modules'' for specific purposes; these are C modules write ``extension modules'' for specific purposes; these are C modules
that extend the Python interpreter. This is probably the most common that extend the Python interpreter. This is probably the most common
use. The second reason is to use Python as a component in a larger use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as ``embedding'' application; this technique is generally referred to as ``embedding''
Python in an application. Python in an application.
Writing an extension module is a relatively well-understood process, Writing an extension module is a relatively well-understood process,
@ -60,7 +60,7 @@ Python in other applications since its early existence, the process of
embedding Python is less straightforward that writing an extension. embedding Python is less straightforward that writing an extension.
Python 1.5 introduces a number of new API functions as well as some Python 1.5 introduces a number of new API functions as well as some
changes to the build process that make embedding much simpler. changes to the build process that make embedding much simpler.
This manual describes the 1.5 state of affair (as of Python 1.5a3). This manual describes the 1.5 state of affair.
% XXX Eventually, take the historical notes out % XXX Eventually, take the historical notes out
Many API functions are useful independent of whether you're embedding Many API functions are useful independent of whether you're embedding
@ -69,16 +69,36 @@ will need to provide a custom extension as well, so it's probably a
good idea to become familiar with writing an extension before good idea to become familiar with writing an extension before
attempting to embed Python in a real application. attempting to embed Python in a real application.
\section{Include Files}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
\code{\#include "Python.h"}
This implies inclusion of the following standard header files:
stdio.h, string.h, errno.h, and stdlib.h (if available).
All user visible names defined by Python.h (except those defined by
the included standard headers) have one of the prefixes \code{Py} or
\code{_Py}. Names beginning with \code{_Py} are for internal use
only. Structure member names do not have a reserved prefix.
Important: user code should never define names that begin with
\code{Py} or \code{_Py}. This confuses the reader, and jeopardizes
the portability of the user code to future Python versions, which may
define additional names beginning with one of these prefixes.
\section{Objects, Types and Reference Counts} \section{Objects, Types and Reference Counts}
Most Python/C API functions have one or more arguments as well as a Most Python/C API functions have one or more arguments as well as a
return value of type \code{PyObject *}. This type is a pointer return value of type \code{PyObject *}. This type is a pointer
(obviously!) to an opaque data type representing an arbitrary Python (obviously!) to an opaque data type representing an arbitrary Python
object. Since all Python object types are treated the same way by the object. Since all Python object types are treated the same way by the
Python language in most situations (e.g., assignments, scope rules, Python language in most situations (e.g., assignments, scope rules,
and argument passing), it is only fitting that they should be and argument passing), it is only fitting that they should be
represented by a single C type. All Python objects live on the heap: represented by a single C type. All Python objects live on the heap:
you never declare an automatic or static variable of type you never declare an automatic or static variable of type
\code{PyObject}, only pointer variables of type \code{PyObject *} can \code{PyObject}, only pointer variables of type \code{PyObject *} can
be declared. be declared.
@ -92,7 +112,7 @@ iff the object pointed to by \code{a} is a Python list.
\subsection{Reference Counts} \subsection{Reference Counts}
The reference count is important only because today's computers have a The reference count is important because today's computers have a
finite (and often severly limited) memory size; it counts how many finite (and often severly limited) memory size; it counts how many
different places there are that have a reference to an object. Such a different places there are that have a reference to an object. Such a
place could be another object, or a global (or static) C variable, or place could be another object, or a global (or static) C variable, or
@ -154,7 +174,7 @@ they are done with the result; this soon becomes second nature.
The reference count behavior of functions in the Python/C API is best The reference count behavior of functions in the Python/C API is best
expelained in terms of \emph{ownership of references}. Note that we expelained in terms of \emph{ownership of references}. Note that we
talk of owning reference, never of owning objects; objects are always talk of owning references, never of owning objects; objects are always
shared! When a function owns a reference, it has to dispose of it shared! When a function owns a reference, it has to dispose of it
properly -- either by passing ownership on (usually to its caller) or properly -- either by passing ownership on (usually to its caller) or
by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a function
@ -163,16 +183,17 @@ to receive a \emph{new} reference. When to ownership is transferred,
the caller is said to \emph{borrow} the reference. Nothing needs to the caller is said to \emph{borrow} the reference. Nothing needs to
be done for a borrowed reference. be done for a borrowed reference.
Conversely, when calling a function while passing it a reference to an Conversely, when calling a function passes it a reference to an
object, there are two possibilities: the function \emph{steals} a object, there are two possibilities: the function \emph{steals} a
reference to the object, or it does not. Few functions steal reference to the object, or it does not. Few functions steal
references; the two notable exceptions are \code{PyList_SetItem()} and references; the two notable exceptions are \code{PyList_SetItem()} and
\code{PyTuple_SetItem()}, which steal a reference to the item (but not to \code{PyTuple_SetItem()}, which steal a reference to the item (but not to
the tuple or list into which the item it put!). These functions were the tuple or list into which the item it put!). These functions were
designed to steal a reference because of a common idiom for designed to steal a reference because of a common idiom for populating
populating a tuple or list with newly created objects; e.g., the code a tuple or list with newly created objects; for example, the code to
to create the tuple \code{(1, 2, "three")} could look like this create the tuple \code{(1, 2, "three")} could look like this
(forgetting about error handling for the moment): (forgetting about error handling for the moment; a better way to code
this is shown below anyway):
\begin{verbatim} \begin{verbatim}
PyObject *t; PyObject *t;
@ -203,10 +224,10 @@ x = PyString_FromString("three");
PyObject_SetItem(l, 2, x); Py_DECREF(x); PyObject_SetItem(l, 2, x); Py_DECREF(x);
\end{verbatim} \end{verbatim}
You might find it strange that the ``recommended'' approach takes You might find it strange that the ``recommended'' approach takes more
more code. in practice, you will rarely use these ways of creating code. However, in practice, you will rarely use these ways of
and populating a tuple or list, however; there's a generic function, creating and populating a tuple or list. There's a generic function,
\code{Py_BuildValue()} that can create most common objects from C \code{Py_BuildValue()}, that can create most common objects from C
values, directed by a ``format string''. For example, the above two values, directed by a ``format string''. For example, the above two
blocks of code could be replaced by the following (which also takes blocks of code could be replaced by the following (which also takes
care of the error checking!): care of the error checking!):
@ -306,7 +327,7 @@ long sum_sequence(PyObject *sequence)
\subsection{Types} \subsection{Types}
There are few other data types that play a significant role in There are few other data types that play a significant role in
the Python/C API; most are all simple C types such as \code{int}, the Python/C API; most are simple C types such as \code{int},
\code{long}, \code{double} and \code{char *}. A few structure types \code{long}, \code{double} and \code{char *}. A few structure types
are used to describe static tables used to list the functions exported are used to describe static tables used to list the functions exported
by a module or the data attributes of a new object type. These will by a module or the data attributes of a new object type. These will
@ -325,7 +346,7 @@ All functions in the Python/C API can raise exceptions, unless an
explicit claim is made otherwise in a function's documentation. In explicit claim is made otherwise in a function's documentation. In
general, when a function encounters an error, it sets an exception, general, when a function encounters an error, it sets an exception,
discards any object references that it owns, and returns an discards any object references that it owns, and returns an
error indicator -- usually \code{NULL} or \code{-1}. A few functions error indicator -- usually \NULL{} or \code{-1}. A few functions
return a Boolean true/false result, with false indicating an error. return a Boolean true/false result, with false indicating an error.
Very few functions return no explicit error indicator or have an Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with ambiguous return value, and require explicit testing for errors with
@ -336,13 +357,13 @@ equivalent to using global storage in an unthreaded application). A
thread can be on one of two states: an exception has occurred, or not. thread can be on one of two states: an exception has occurred, or not.
The function \code{PyErr_Occurred()} can be used to check for this: it The function \code{PyErr_Occurred()} can be used to check for this: it
returns a borrowed reference to the exception type object when an returns a borrowed reference to the exception type object when an
exception has occurred, and \code{NULL} otherwise. There are a number exception has occurred, and \NULL{} otherwise. There are a number
of functions to set the exception state: \code{PyErr_SetString()} is of functions to set the exception state: \code{PyErr_SetString()} is
the most common (though not the most general) function to set the the most common (though not the most general) function to set the
exception state, and \code{PyErr_Clear()} clears the exception state. exception state, and \code{PyErr_Clear()} clears the exception state.
The full exception state consists of three objects (all of which can The full exception state consists of three objects (all of which can
be \code{NULL} ): the exception type, the corresponding exception be \NULL{} ): the exception type, the corresponding exception
value, and the traceback. These have the same meanings as the Python value, and the traceback. These have the same meanings as the Python
object \code{sys.exc_type}, \code{sys.exc_value}, object \code{sys.exc_type}, \code{sys.exc_value},
\code{sys.exc_traceback}; however, they are not the same: the Python \code{sys.exc_traceback}; however, they are not the same: the Python
@ -376,37 +397,35 @@ A simple example of detecting exceptions and passing them on is shown
in the \code{sum_sequence()} example above. It so happens that that in the \code{sum_sequence()} example above. It so happens that that
example doesn't need to clean up any owned references when it detects example doesn't need to clean up any owned references when it detects
an error. The following example function shows some error cleanup. an error. The following example function shows some error cleanup.
First we show the equivalent Python code (to remind you why you like First, to remind you why you like Python, we show the equivalent
Python): Python code:
\begin{verbatim} \begin{verbatim}
def incr_item(seq, i): def incr_item(dict, key):
try: try:
item = seq[i] item = dict[key]
except IndexError: except KeyError:
item = 0 item = 0
seq[i] = item + 1 return item + 1
\end{verbatim} \end{verbatim}
Here is the corresponding C code, in all its glory: Here is the corresponding C code, in all its glory:
% XXX Is it better to have fewer comments in the code?
\begin{verbatim} \begin{verbatim}
int incr_item(PyObject *seq, int i) int incr_item(PyObject *dict, PyObject *key)
{ {
/* Objects all initialized to NULL for Py_XDECREF */ /* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (faulure) */ int rv = -1; /* Return value initialized to -1 (faulure) */
item = PySequence_GetItem(seq, i); item = PyObject_GetItem(dict, key);
if (item == NULL) { if (item == NULL) {
/* Handle IndexError only: */ /* Handle keyError only: */
if (PyErr_Occurred() != PyExc_IndexError) goto error; if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
/* Clear the error and use zero: */ /* Clear the error and use zero: */
PyErr_Clear(); PyErr_Clear();
item = PyInt_FromLong(1L); item = PyInt_FromLong(0L);
if (item == NULL) goto error; if (item == NULL) goto error;
} }
@ -416,7 +435,7 @@ int incr_item(PyObject *seq, int i)
incremented_item = PyNumber_Add(item, const_one); incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL) goto error; if (incremented_item == NULL) goto error;
if (PyObject_SetItem(seq, i, incremented_item) < 0) goto error; if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
rv = 0; /* Success */ rv = 0; /* Success */
/* Continue with cleanup code */ /* Continue with cleanup code */
@ -433,24 +452,24 @@ int incr_item(PyObject *seq, int i)
\end{verbatim} \end{verbatim}
This example represents an endorsed use of the \code{goto} statement This example represents an endorsed use of the \code{goto} statement
in C! It illustrates the use of \code{PyErr_Occurred()} and in C! It illustrates the use of \code{PyErr_ExceptionMatches()} and
\code{PyErr_Clear()} to handle specific exceptions, and the use of \code{PyErr_Clear()} to handle specific exceptions, and the use of
\code{Py_XDECREF()} to dispose of owned references that may be \code{Py_XDECREF()} to dispose of owned references that may be
\code{NULL} (note the `X' in the name; \code{Py_DECREF()} would crash \NULL{} (note the `X' in the name; \code{Py_DECREF()} would crash
when confronted with a \code{NULL} reference). It is important that when confronted with a \NULL{} reference). It is important that
the variables used to hold owned references are initialized to the variables used to hold owned references are initialized to
\code{NULL} for this to work; likewise, the proposed return value is \NULL{} for this to work; likewise, the proposed return value is
initialized to \code{-1} (failure) and only set to success after initialized to \code{-1} (failure) and only set to success after
the final call made is succesful. the final call made is succesful.
\section{Embedding Python} \section{Embedding Python}
The one important task that only embedders of the Python interpreter The one important task that only embedders (as opposed to extension
have to worry about is the initialization (and possibly the writers) of the Python interpreter have to worry about is the
finalization) of the Python interpreter. Most functionality of the initialization, and possibly the finalization, of the Python
interpreter can only be used after the interpreter has been interpreter. Most functionality of the interpreter can only be used
initialized. after the interpreter has been initialized.
The basic initialization function is \code{Py_Initialize()}. This The basic initialization function is \code{Py_Initialize()}. This
initializes the table of loaded modules, and creates the fundamental initializes the table of loaded modules, and creates the fundamental
@ -476,189 +495,64 @@ path (the environment variable \code{\$PATH}).
For instance, if the Python executable is found in For instance, if the Python executable is found in
\code{/usr/local/bin/python}, it will assume that the libraries are in \code{/usr/local/bin/python}, it will assume that the libraries are in
\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' \code{/usr/local/lib/python1.5}. (In fact, this particular path is
location, used when no executable file named \code{python} is found also the ``fallback'' location, used when no executable file named
along \code{\$PATH}. The user can change this behavior by setting the \code{python} is found along \code{\$PATH}.) The user can override
environment variable \code{\$PYTHONHOME}, and can insert additional this behavior by setting the environment variable \code{\$PYTHONHOME},
directories in front of the standard path by setting or insert additional directories in front of the standard path by
\code{\$PYTHONPATH}. setting \code{\$PYTHONPATH}.
The embedding application can steer the search by calling The embedding application can steer the search by calling
\code{Py_SetProgramName(\var{file})} \emph{before} calling \code{Py_SetProgramName(\var{file})} \emph{before} calling
\code{Py_Initialize()}. Note that \code{\$PYTHONHOME} still overrides \code{Py_Initialize()}. Note that \code{\$PYTHONHOME} still overrides
this and \code{\$PYTHONPATH} is still inserted in front of the this and \code{\$PYTHONPATH} is still inserted in front of the
standard path. standard path. An application that requires total control has to
provide its own implementation of \code{Py_GetPath()},
\code{Py_GetPrefix()}, \code{Py_GetExecPrefix()},
\code{Py_GetProgramFullPath()} (all defined in
\file{Modules/getpath.c}).
Sometimes, it is desirable to ``uninitialize'' Python. For instance, Sometimes, it is desirable to ``uninitialize'' Python. For instance,
the application may want to start over (make another call to the application may want to start over (make another call to
\code{Py_Initialize()}) or the application is simply done with its \code{Py_Initialize()}) or the application is simply done with its
use of Python and wants to free all memory allocated by Python. This use of Python and wants to free all memory allocated by Python. This
can be accomplished by calling \code{Py_Finalize()}. can be accomplished by calling \code{Py_Finalize()}. The function
% XXX More... \code{Py_IsInitialized()} returns true iff Python is currently in the
initialized state. More information about these functions is given in
\section{Embedding Python in Threaded Applications} a later chapter.
\chapter{Basic Utilities}
XXX These utilities should be moved to some other section...
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and kill the process. No cleanup is
performed. This function should only be invoked when a condition is
detected that would make it dangerous to continue using the Python
interpreter; e.g., when the object administration appears to be
corrupted. On Unix, the standard C library function \code{abort()} is
\chapter{Old Introduction} called which will attempt to produce a \file{core} file.
(XXX This is the old introduction, mostly by Jim Fulton -- should be
rewritten.)
From the viewpoint of of C access to Python services, we have:
\begin{enumerate}
\item "Very high level layer": two or three functions that let you
exec or eval arbitrary Python code given as a string in a module whose
name is given, passing C values in and getting C values out using
mkvalue/getargs style format strings. This does not require the user
to declare any variables of type \code{PyObject *}. This should be
enough to write a simple application that gets Python code from the
user, execs it, and returns the output or errors.
\item "Abstract objects layer": which is the subject of this chapter.
It has many functions operating on objects, and lets you do many
things from C that you can also write in Python, without going through
the Python parser.
\item "Concrete objects layer": This is the public type-dependent
interface provided by the standard built-in types, such as floats,
strings, and lists. This interface exists and is currently documented
by the collection of include files provides with the Python
distributions.
\end{enumerate}
From the point of view of Python accessing services provided by C
modules:
\begin{enumerate}
\item[4.] "Python module interface": this interface consist of the basic
routines used to define modules and their members. Most of the
current extensions-writing guide deals with this interface.
\item[5.] "Built-in object interface": this is the interface that a new
built-in type must provide and the mechanisms and rules that a
developer of a new built-in type must use and follow.
\end{enumerate}
The Python C API provides four groups of operations on objects,
corresponding to the same operations in the Python language: object,
numeric, sequence, and mapping. Each protocol consists of a
collection of related operations. If an operation that is not
provided by a particular type is invoked, then the standard exception
\code{TypeError} is raised with a operation name as an argument.
In addition, for convenience this interface defines a set of
constructors for building objects of built-in types. This is needed
so new objects can be returned from C functions that otherwise treat
objects generically.
\section{Reference Counting}
For most of the functions in the Python/C API, if a function retains a
reference to a Python object passed as an argument, then the function
will increase the reference count of the object. It is unnecessary
for the caller to increase the reference count of an argument in
anticipation of the object's retention.
Usually, Python objects returned from functions should be treated as
new objects. Functions that return objects assume that the caller
will retain a reference and the reference count of the object has
already been incremented to account for this fact. A caller that does
not retain a reference to an object that is returned from a function
must decrement the reference count of the object (using
\code{Py_DECREF()}) to prevent memory leaks.
Exceptions to these rules will be noted with the individual functions.
\section{Include Files}
All function, type and macro definitions needed to use the Python/C
API are included in your code by the following line:
\code{\#include "Python.h"}
This implies inclusion of the following standard header files:
stdio.h, string.h, errno.h, and stdlib.h (if available).
All user visible names defined by Python.h (except those defined by
the included standard headers) have one of the prefixes \code{Py} or
\code{_Py}. Names beginning with \code{_Py} are for internal use
only.
\chapter{Initialization and Shutdown of an Embedded Python Interpreter}
When embedding the Python interpreter in a C or C++ program, the
interpreter must be initialized.
\begin{cfuncdesc}{void}{PyInitialize}{}
This function initializes the interpreter. It must be called before
any interaction with the interpreter takes place. If it is called
more than once, the second and further calls have no effect.
The function performs the following tasks: create an environment in
which modules can be imported and Python code can be executed;
initialize the \code{__builtin__} module; initialize the \code{sys}
module; initialize \code{sys.path}; initialize signal handling; and
create the empty \code{__main__} module.
In the current system, there is no way to undo all these
initializations or to create additional interpreter environments.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
Register a cleanup function to be called when Python exits. The
cleanup function will be called with no arguments and should return no
value. At most 32 cleanup functions can be registered. When the
registration is successful, \code{Py_AtExit} returns 0; on failure, it
returns -1. Each cleanup function will be called t most once. The
cleanup function registered last is called first.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Exit}{int status} \begin{cfuncdesc}{void}{Py_Exit}{int status}
Exit the current process. This calls \code{Py_Cleanup()} (see next Exit the current process. This calls \code{Py_Finalize()} and then
item) and performs additional cleanup (under some circumstances it calls the standard C library function \code{exit(0)}.
will attempt to delete all modules), and then calls the standard C
library function \code{exit(status)}.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_Cleanup}{} \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
Perform some of the cleanup that \code{Py_Exit} performs, but don't Register a cleanup function to be called by \code{Py_Finalize()}. The
exit the process. In particular, this invokes the user's cleanup function will be called with no arguments and should return no
\code{sys.exitfunc} function (if defined at all), and it invokes the value. At most 32 cleanup functions can be registered. When the
cleanup functions registered with \code{Py_AtExit()}, in reverse order registration is successful, \code{Py_AtExit} returns 0; on failure, it
of their registration. returns -1. The cleanup function registered last is called first.
Each cleanup function will be called at most once.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
Print a fatal error message and die. No cleanup is performed. This
function should only be invoked when a condition is detected that
would make it dangerous to continue using the Python interpreter;
e.g., when the object administration appears to be corrupted.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyBuiltin_Init}{}
Initialize the \code{__builtin__} module. For internal use only.
\end{cfuncdesc}
XXX Other init functions: PyOS_InitInterrupts,
PyMarshal_Init, PySys_Init.
\chapter{Reference Counting} \chapter{Reference Counting}
The functions in this chapter are used for managing reference counts The macros in this section are used for managing reference counts
of Python objects. of Python objects.
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
@ -669,7 +563,7 @@ not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
Increment the reference count for object \code{o}. The object may be Increment the reference count for object \code{o}. The object may be
\NULL{}, in which case the function has no effect. \NULL{}, in which case the macro has no effect.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
@ -692,15 +586,19 @@ temporary variable.
\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
Decrement the reference count for object \code{o}.The object may be Decrement the reference count for object \code{o}.The object may be
\NULL{}, in which case the function has no effect; otherwise the \NULL{}, in which case the macro has no effect; otherwise the
effect is the same as for \code{Py_DECREF()}, and the same warning effect is the same as for \code{Py_DECREF()}, and the same warning
applies. applies.
\end{cfuncdesc} \end{cfuncdesc}
The following functions are only for internal use: The following functions or macros are only for internal use:
\code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_Py_NewReference}, \code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_Py_NewReference},
as well as the global variable \code{_Py_RefTotal}. as well as the global variable \code{_Py_RefTotal}.
XXX Should mention Py_Malloc(), Py_Realloc(), Py_Free(),
PyMem_Malloc(), PyMem_Realloc(), PyMem_Free(), PyMem_NEW(),
PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
\chapter{Exception Handling} \chapter{Exception Handling}
@ -875,7 +773,7 @@ PyObject *base, PyObject *dict}
This utility function creates and returns a new exception object. The This utility function creates and returns a new exception object. The
\var{name} argument must be the name of the new exception, a C string \var{name} argument must be the name of the new exception, a C string
of the form \code{module.class}. The \var{base} and \var{dict} of the form \code{module.class}. The \var{base} and \var{dict}
arguments are normally \code{NULL}. Normally, this creates a class arguments are normally \NULL{}. Normally, this creates a class
object derived from the root for all exceptions, the built-in name object derived from the root for all exceptions, the built-in name
\code{Exception} (accessible in C as \code{PyExc_Exception}). In this \code{Exception} (accessible in C as \code{PyExc_Exception}). In this
case the \code{__module__} attribute of the new class is set to the case the \code{__module__} attribute of the new class is set to the
@ -883,7 +781,7 @@ first part (up to the last dot) of the \var{name} argument, and the
class name is set to the last part (after the last dot). When the class name is set to the last part (after the last dot). When the
user has specified the \code{-X} command line option to use string user has specified the \code{-X} command line option to use string
exceptions, for backward compatibility, or when the \var{base} exceptions, for backward compatibility, or when the \var{base}
argument is not a class object (and not \code{NULL}), a string object argument is not a class object (and not \NULL{}), a string object
created from the entire \var{name} argument is returned. The created from the entire \var{name} argument is returned. The
\var{base} argument can be used to specify an alternate base class. \var{base} argument can be used to specify an alternate base class.
The \var{dict} argument can be used to specify a dictionary of class The \var{dict} argument can be used to specify a dictionary of class
@ -952,7 +850,7 @@ the standard C library function \code{time()}.
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} \begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \code{PyImport_ImportModuleEx} This is a simplified interface to \code{PyImport_ImportModuleEx}
below, leaving the \var{globals} and \var{locals} arguments set to below, leaving the \var{globals} and \var{locals} arguments set to
\code{NULL}. When the \var{name} argument contains a dot (i.e., when \NULL{}. When the \var{name} argument contains a dot (i.e., when
it specifies a submodule of a package), the \var{fromlist} argument is it specifies a submodule of a package), the \var{fromlist} argument is
set to the list \code{['*']} so that the return value is the named set to the list \code{['*']} so that the return value is the named
module rather than the top-level package containing it as would module rather than the top-level package containing it as would
@ -960,7 +858,7 @@ otherwise be the case. (Unfortunately, this has an additional side
effect when \var{name} in fact specifies a subpackage instead of a effect when \var{name} in fact specifies a subpackage instead of a
submodule: the submodules specified in the package's \code{__all__} submodule: the submodules specified in the package's \code{__all__}
variable are loaded.) Return a new reference to the imported module, variable are loaded.) Return a new reference to the imported module,
or \code{NULL} with an exception set on failure (the module may still or \NULL{} with an exception set on failure (the module may still
be created in this case). be created in this case).
\end{cfuncdesc} \end{cfuncdesc}
@ -971,7 +869,7 @@ Python function \code{__import()__}, as the standard
\code{__import__()} function calls this function directly. \code{__import__()} function calls this function directly.
The return value is a new reference to the imported module or The return value is a new reference to the imported module or
top-level package, or \code{NULL} with an exception set on failure top-level package, or \NULL{} with an exception set on failure
(the module may still be created in this case). Like for (the module may still be created in this case). Like for
\code{__import__()}, the return value when a submodule of a package \code{__import__()}, the return value when a submodule of a package
was requested is normally the top-level package, unless a non-empty was requested is normally the top-level package, unless a non-empty
@ -990,7 +888,7 @@ current environment, e.g. by \code{rexec} or \code{ihooks}.
Reload a module. This is best described by referring to the built-in Reload a module. This is best described by referring to the built-in
Python function \code{reload()}, as the standard \code{reload()} Python function \code{reload()}, as the standard \code{reload()}
function calls this function directly. Return a new reference to the function calls this function directly. Return a new reference to the
reloaded module, or \code{NULL} with an exception set on failure (the reloaded module, or \NULL{} with an exception set on failure (the
module still exists in this case). module still exists in this case).
\end{cfuncdesc} \end{cfuncdesc}
@ -1000,7 +898,7 @@ Return the module object corresponding to a module name. The
check the modules dictionary if there's one there, and if not, create check the modules dictionary if there's one there, and if not, create
a new one and insert in in the modules dictionary. Because the former a new one and insert in in the modules dictionary. Because the former
action is most common, this does not return a new reference, and you action is most common, this does not return a new reference, and you
do not own the returned reference. Return \code{NULL} with an do not own the returned reference. Return \NULL{} with an
exception set on failure. exception set on failure.
\end{cfuncdesc} \end{cfuncdesc}
@ -1008,7 +906,7 @@ exception set on failure.
Given a module name (possibly of the form \code{package.module}) and a Given a module name (possibly of the form \code{package.module}) and a
code object read from a Python bytecode file or obtained from the code object read from a Python bytecode file or obtained from the
built-in function \code{compile()}, load the module. Return a new built-in function \code{compile()}, load the module. Return a new
reference to the module object, or \code{NULL} with an exception set reference to the module object, or \NULL{} with an exception set
if an error occurred (the module may still be created in this case). if an error occurred (the module may still be created in this case).
(This function would reload the module if it was already imported.) (This function would reload the module if it was already imported.)
\end{cfuncdesc} \end{cfuncdesc}
@ -1069,7 +967,7 @@ struct _frozen {
\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules} \begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
This pointer is initialized to point to an array of \code{struct This pointer is initialized to point to an array of \code{struct
_frozen} records, terminated by one whose members are all \code{NULL} _frozen} records, terminated by one whose members are all \NULL{}
or zero. When a frozen module is imported, it is searched in this or zero. When a frozen module is imported, it is searched in this
table. Third party code could play tricks with this to provide a table. Third party code could play tricks with this to provide a
dynamically created collection of frozen modules. dynamically created collection of frozen modules.
@ -1798,7 +1696,7 @@ The return value points to the first thread state created in the new
sub-interpreter. This thread state is made the current thread state. sub-interpreter. This thread state is made the current thread state.
Note that no actual thread is created; see the discussion of thread Note that no actual thread is created; see the discussion of thread
states below. If creation of the new interpreter is unsuccessful, states below. If creation of the new interpreter is unsuccessful,
\code{NULL} is returned; no exception is set since the exception state \NULL{} is returned; no exception is set since the exception state
is stored in the current thread state and there may not be a current is stored in the current thread state and there may not be a current
thread state. (Like all other Python/C API functions, the global thread state. (Like all other Python/C API functions, the global
interpreter lock must be held before calling this function and is interpreter lock must be held before calling this function and is
@ -1839,7 +1737,7 @@ a hard-to-fix bug that will be addressed in a future release.)
Destroy the (sub-)interpreter represented by the given thread state. Destroy the (sub-)interpreter represented by the given thread state.
The given thread state must be the current thread state. See the The given thread state must be the current thread state. See the
discussion of thread states below. When the call returns, the current discussion of thread states below. When the call returns, the current
thread state is \code{NULL}. All thread states associated with this thread state is \NULL{}. All thread states associated with this
interpreted are destroyed. (The global interpreter lock must be held interpreted are destroyed. (The global interpreter lock must be held
before calling this function and is still held when it returns.) before calling this function and is still held when it returns.)
\code{Py_Finalize()} will destroy all sub-interpreters that haven't \code{Py_Finalize()} will destroy all sub-interpreters that haven't
@ -2205,7 +2103,7 @@ compile time.
\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
\strong{(NEW in 1.5a3!)} \strong{(NEW in 1.5a3!)}
Acquire the global interpreter lock and then set the current thread Acquire the global interpreter lock and then set the current thread
state to \var{tstate}, which should not be \code{NULL}. The lock must state to \var{tstate}, which should not be \NULL{}. The lock must
have been created earlier. If this thread already has the lock, have been created earlier. If this thread already has the lock,
deadlock ensues. This function is not available when thread support deadlock ensues. This function is not available when thread support
is disabled at is disabled at
@ -2214,10 +2112,10 @@ compile time.
\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
\strong{(NEW in 1.5a3!)} \strong{(NEW in 1.5a3!)}
Reset the current thread state to \code{NULL} and release the global Reset the current thread state to \NULL{} and release the global
interpreter lock. The lock must have been created earlier and must be interpreter lock. The lock must have been created earlier and must be
held by the current thread. The \var{tstate} argument, which must not held by the current thread. The \var{tstate} argument, which must not
be \code{NULL}, is only used to check that it represents the current be \NULL{}, is only used to check that it represents the current
thread state -- if it isn't, a fatal error is reported. This function thread state -- if it isn't, a fatal error is reported. This function
is not available when thread support is disabled at is not available when thread support is disabled at
compile time. compile time.
@ -2226,8 +2124,8 @@ compile time.
\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{} \begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
\strong{(Different return type in 1.5a3!)} \strong{(Different return type in 1.5a3!)}
Release the interpreter lock (if it has been created and thread Release the interpreter lock (if it has been created and thread
support is enabled) and reset the thread state to \code{NULL}, support is enabled) and reset the thread state to \NULL{},
returning the previous thread state (which is not \code{NULL}). If returning the previous thread state (which is not \NULL{}). If
the lock has been created, the current thread must have acquired it. the lock has been created, the current thread must have acquired it.
(This function is available even when thread support is disabled at (This function is available even when thread support is disabled at
compile time.) compile time.)
@ -2237,7 +2135,7 @@ compile time.)
\strong{(Different argument type in 1.5a3!)} \strong{(Different argument type in 1.5a3!)}
Acquire the interpreter lock (if it has been created and thread Acquire the interpreter lock (if it has been created and thread
support is enabled) and set the thread state to \var{tstate}, which support is enabled) and set the thread state to \var{tstate}, which
must not be \code{NULL}. If the lock has been created, the current must not be \NULL{}. If the lock has been created, the current
thread must not have acquired it, otherwise deadlock ensues. (This thread must not have acquired it, otherwise deadlock ensues. (This
function is available even when thread support is disabled at compile function is available even when thread support is disabled at compile
time.) time.)
@ -2314,13 +2212,13 @@ call to \code{PyThreadState_Clear()}.
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{} \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
Return the current thread state. The interpreter lock must be held. Return the current thread state. The interpreter lock must be held.
When the current thread state is \code{NULL}, this issues a fatal When the current thread state is \NULL{}, this issues a fatal
error (so that the caller needn't check for \code{NULL}. error (so that the caller needn't check for \NULL{}.
\end{cfuncdesc} \end{cfuncdesc}
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate} \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
Swap the current thread state with the thread state given by the Swap the current thread state with the thread state given by the
argument \var{tstate}, which may be \code{NULL}. The interpreter lock argument \var{tstate}, which may be \NULL{}. The interpreter lock
must be held. must be held.
\end{cfuncdesc} \end{cfuncdesc}