2869 lines
111 KiB
TeX
2869 lines
111 KiB
TeX
\documentclass[twoside,openright]{report}
|
|
\usepackage{myformat}
|
|
|
|
\title{Python/C API Reference Manual}
|
|
|
|
\input{boilerplate}
|
|
|
|
\makeindex % tell \index to actually write the .idx file
|
|
|
|
|
|
\begin{document}
|
|
|
|
\maketitle
|
|
|
|
\input{copyright}
|
|
|
|
\begin{abstract}
|
|
|
|
\noindent
|
|
This manual documents the API used by \C{} (or \Cpp{}) programmers who
|
|
want to write extension modules or embed Python. It is a companion to
|
|
\emph{Extending and Embedding the Python Interpreter}, which describes
|
|
the general principles of extension writing but does not document the
|
|
API functions in detail.
|
|
|
|
\strong{Warning:} The current version of this document is incomplete.
|
|
I hope that it is nevertheless useful. I will continue to work on it,
|
|
and release new versions from time to time, independent from Python
|
|
source code releases.
|
|
|
|
\end{abstract}
|
|
|
|
\tableofcontents
|
|
|
|
% XXX Consider moving all this back to ext.tex and giving api.tex
|
|
% XXX a *really* short intro only.
|
|
|
|
\chapter{Introduction}
|
|
|
|
The Application Programmer's Interface to Python gives \C{} and \Cpp{}
|
|
programmers access to the Python interpreter at a variety of levels.
|
|
The API is equally usable from \Cpp{}, but for brevity it is generally
|
|
referred to as the Python/\C{} API. There are two fundamentally
|
|
different reasons for using the Python/\C{} API. The first reason is
|
|
to write \emph{extension modules} for specific purposes; these are
|
|
\C{} modules 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 application; this technique is generally referred to as
|
|
\dfn{embedding} Python in an application.
|
|
|
|
Writing an extension module is a relatively well-understood process,
|
|
where a ``cookbook'' approach works well. There are several tools
|
|
that automate the process to some extent. While people have embedded
|
|
Python in other applications since its early existence, the process of
|
|
embedding Python is less straightforward that writing an extension.
|
|
Python 1.5 introduces a number of new API functions as well as some
|
|
changes to the build process that make embedding much simpler.
|
|
This manual describes the \version\ state of affair.
|
|
% XXX Eventually, take the historical notes out
|
|
|
|
Many API functions are useful independent of whether you're embedding
|
|
or extending Python; moreover, most applications that embed Python
|
|
will need to provide a custom extension as well, so it's probably a
|
|
good idea to become familiar with writing an extension before
|
|
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:
|
|
|
|
\begin{verbatim}
|
|
#include "Python.h"
|
|
\end{verbatim}
|
|
|
|
This implies inclusion of the following standard headers:
|
|
\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
|
|
\code{<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 \samp{Py} or
|
|
\samp{_Py}. Names beginning with \samp{_Py} are for internal use
|
|
only. Structure member names do not have a reserved prefix.
|
|
|
|
\strong{Important:} user code should never define names that begin
|
|
with \samp{Py} or \samp{_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}
|
|
|
|
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
|
|
to an opaque data type representing an arbitrary Python
|
|
object. Since all Python object types are treated the same way by the
|
|
Python language in most situations (e.g., assignments, scope rules,
|
|
and argument passing), it is only fitting that they should be
|
|
represented by a single \C{} type. All Python objects live on the heap:
|
|
you never declare an automatic or static variable of type
|
|
\code{PyObject}, only pointer variables of type \code{PyObject *} can
|
|
be declared.
|
|
|
|
All Python objects (even Python integers) have a \dfn{type} and a
|
|
\dfn{reference count}. An object's type determines what kind of object
|
|
it is (e.g., an integer, a list, or a user-defined function; there are
|
|
many more as explained in the \emph{Python Reference Manual}). For
|
|
each of the well-known types there is a macro to check whether an
|
|
object is of that type; for instance, \samp{PyList_Check(\var{a})} is
|
|
true iff the object pointed to by \var{a} is a Python list.
|
|
|
|
\subsection{Reference Counts}
|
|
|
|
The reference count is important because today's computers have a
|
|
finite (and often severly limited) memory size; it counts how many
|
|
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
|
|
a local variable in some \C{} function. When an object's reference count
|
|
becomes zero, the object is deallocated. If it contains references to
|
|
other objects, their reference count is decremented. Those other
|
|
objects may be deallocated in turn, if this decrement makes their
|
|
reference count become zero, and so on. (There's an obvious problem
|
|
with objects that reference each other here; for now, the solution is
|
|
``don't do that''.)
|
|
|
|
Reference counts are always manipulated explicitly. The normal way is
|
|
to use the macro \cfunction{Py_INCREF()} to increment an object's
|
|
reference count by one, and \cfunction{Py_DECREF()} to decrement it by
|
|
one. The decref macro is considerably more complex than the incref one,
|
|
since it must check whether the reference count becomes zero and then
|
|
cause the object's deallocator, which is a function pointer contained
|
|
in the object's type structure. The type-specific deallocator takes
|
|
care of decrementing the reference counts for other objects contained
|
|
in the object, and so on, if this is a compound object type such as a
|
|
list. There's no chance that the reference count can overflow; at
|
|
least as many bits are used to hold the reference count as there are
|
|
distinct memory locations in virtual memory (assuming
|
|
\code{sizeof(long) >= sizeof(char *)}). Thus, the reference count
|
|
increment is a simple operation.
|
|
|
|
It is not necessary to increment an object's reference count for every
|
|
local variable that contains a pointer to an object. In theory, the
|
|
object's reference count goes up by one when the variable is made to
|
|
point to it and it goes down by one when the variable goes out of
|
|
scope. However, these two cancel each other out, so at the end the
|
|
reference count hasn't changed. The only real reason to use the
|
|
reference count is to prevent the object from being deallocated as
|
|
long as our variable is pointing to it. If we know that there is at
|
|
least one other reference to the object that lives at least as long as
|
|
our variable, there is no need to increment the reference count
|
|
temporarily. An important situation where this arises is in objects
|
|
that are passed as arguments to \C{} functions in an extension module
|
|
that are called from Python; the call mechanism guarantees to hold a
|
|
reference to every argument for the duration of the call.
|
|
|
|
However, a common pitfall is to extract an object from a list and
|
|
hold on to it for a while without incrementing its reference count.
|
|
Some other operation might conceivably remove the object from the
|
|
list, decrementing its reference count and possible deallocating it.
|
|
The real danger is that innocent-looking operations may invoke
|
|
arbitrary Python code which could do this; there is a code path which
|
|
allows control to flow back to the user from a \cfunction{Py_DECREF()},
|
|
so almost any operation is potentially dangerous.
|
|
|
|
A safe approach is to always use the generic operations (functions
|
|
whose name begins with \samp{PyObject_}, \samp{PyNumber_},
|
|
\samp{PySequence_} or \samp{PyMapping_}). These operations always
|
|
increment the reference count of the object they return. This leaves
|
|
the caller with the responsibility to call \cfunction{Py_DECREF()}
|
|
when they are done with the result; this soon becomes second nature.
|
|
|
|
\subsubsection{Reference Count Details}
|
|
|
|
The reference count behavior of functions in the Python/C API is best
|
|
expelained in terms of \emph{ownership of references}. Note that we
|
|
talk of owning references, never of owning objects; objects are always
|
|
shared! When a function owns a reference, it has to dispose of it
|
|
properly --- either by passing ownership on (usually to its caller) or
|
|
by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
|
|
a function passes ownership of a reference on to its caller, the
|
|
caller is said to receive a \emph{new} reference. When no ownership
|
|
is transferred, the caller is said to \emph{borrow} the reference.
|
|
Nothing needs to be done for a borrowed reference.
|
|
|
|
Conversely, when calling a function passes it a reference to an
|
|
object, there are two possibilities: the function \emph{steals} a
|
|
reference to the object, or it does not. Few functions steal
|
|
references; the two notable exceptions are
|
|
\cfunction{PyList_SetItem()} and \cfunction{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 designed to steal a reference
|
|
because of a common idiom for populating a tuple or list with newly
|
|
created objects; for example, the code to create the tuple \code{(1,
|
|
2, "three")} could look like this (forgetting about error handling for
|
|
the moment; a better way to code this is shown below anyway):
|
|
|
|
\begin{verbatim}
|
|
PyObject *t;
|
|
t = PyTuple_New(3);
|
|
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
|
|
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
|
|
PyTuple_SetItem(t, 2, PyString_FromString("three"));
|
|
\end{verbatim}
|
|
|
|
Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
|
|
set tuple items; \cfunction{PySequence_SetItem()} and
|
|
\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
|
|
immutable data type. You should only use
|
|
\cfunction{PyTuple_SetItem()} for tuples that you are creating
|
|
yourself.
|
|
|
|
Equivalent code for populating a list can be written using
|
|
\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
|
|
can also use \cfunction{PySequence_SetItem()}; this illustrates the
|
|
difference between the two (the extra \cfunction{Py_DECREF()} calls):
|
|
|
|
\begin{verbatim}
|
|
PyObject *l, *x;
|
|
l = PyList_New(3);
|
|
x = PyInt_FromLong(1L);
|
|
PySequence_SetItem(l, 0, x); Py_DECREF(x);
|
|
x = PyInt_FromLong(2L);
|
|
PySequence_SetItem(l, 1, x); Py_DECREF(x);
|
|
x = PyString_FromString("three");
|
|
PySequence_SetItem(l, 2, x); Py_DECREF(x);
|
|
\end{verbatim}
|
|
|
|
You might find it strange that the ``recommended'' approach takes more
|
|
code. However, in practice, you will rarely use these ways of
|
|
creating and populating a tuple or list. There's a generic function,
|
|
\cfunction{Py_BuildValue()}, that can create most common objects from
|
|
\C{} values, directed by a \dfn{format string}. For example, the
|
|
above two blocks of code could be replaced by the following (which
|
|
also takes care of the error checking):
|
|
|
|
\begin{verbatim}
|
|
PyObject *t, *l;
|
|
t = Py_BuildValue("(iis)", 1, 2, "three");
|
|
l = Py_BuildValue("[iis]", 1, 2, "three");
|
|
\end{verbatim}
|
|
|
|
It is much more common to use \cfunction{PyObject_SetItem()} and
|
|
friends with items whose references you are only borrowing, like
|
|
arguments that were passed in to the function you are writing. In
|
|
that case, their behaviour regarding reference counts is much saner,
|
|
since you don't have to increment a reference count so you can give a
|
|
reference away (``have it be stolen''). For example, this function
|
|
sets all items of a list (actually, any mutable sequence) to a given
|
|
item:
|
|
|
|
\begin{verbatim}
|
|
int set_all(PyObject *target, PyObject *item)
|
|
{
|
|
int i, n;
|
|
n = PyObject_Length(target);
|
|
if (n < 0)
|
|
return -1;
|
|
for (i = 0; i < n; i++) {
|
|
if (PyObject_SetItem(target, i, item) < 0)
|
|
return -1;
|
|
}
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
The situation is slightly different for function return values.
|
|
While passing a reference to most functions does not change your
|
|
ownership responsibilities for that reference, many functions that
|
|
return a referece to an object give you ownership of the reference.
|
|
The reason is simple: in many cases, the returned object is created
|
|
on the fly, and the reference you get is the only reference to the
|
|
object. Therefore, the generic functions that return object
|
|
references, like \cfunction{PyObject_GetItem()} and
|
|
\cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
|
|
the caller becomes the owner of the reference).
|
|
|
|
It is important to realize that whether you own a reference returned
|
|
by a function depends on which function you call only --- \emph{the
|
|
plumage} (i.e., the type of the type of the object passed as an
|
|
argument to the function) \emph{doesn't enter into it!} Thus, if you
|
|
extract an item from a list using \cfunction{PyList_GetItem()}, you
|
|
don't own the reference --- but if you obtain the same item from the
|
|
same list using \cfunction{PySequence_GetItem()} (which happens to
|
|
take exactly the same arguments), you do own a reference to the
|
|
returned object.
|
|
|
|
Here is an example of how you could write a function that computes the
|
|
sum of the items in a list of integers; once using
|
|
\cfunction{PyList_GetItem()}, once using
|
|
\cfunction{PySequence_GetItem()}.
|
|
|
|
\begin{verbatim}
|
|
long sum_list(PyObject *list)
|
|
{
|
|
int i, n;
|
|
long total = 0;
|
|
PyObject *item;
|
|
n = PyList_Size(list);
|
|
if (n < 0)
|
|
return -1; /* Not a list */
|
|
for (i = 0; i < n; i++) {
|
|
item = PyList_GetItem(list, i); /* Can't fail */
|
|
if (!PyInt_Check(item)) continue; /* Skip non-integers */
|
|
total += PyInt_AsLong(item);
|
|
}
|
|
return total;
|
|
}
|
|
\end{verbatim}
|
|
|
|
\begin{verbatim}
|
|
long sum_sequence(PyObject *sequence)
|
|
{
|
|
int i, n;
|
|
long total = 0;
|
|
PyObject *item;
|
|
n = PyObject_Size(list);
|
|
if (n < 0)
|
|
return -1; /* Has no length */
|
|
for (i = 0; i < n; i++) {
|
|
item = PySequence_GetItem(list, i);
|
|
if (item == NULL)
|
|
return -1; /* Not a sequence, or other failure */
|
|
if (PyInt_Check(item))
|
|
total += PyInt_AsLong(item);
|
|
Py_DECREF(item); /* Discard reference ownership */
|
|
}
|
|
return total;
|
|
}
|
|
\end{verbatim}
|
|
|
|
\subsection{Types}
|
|
|
|
There are few other data types that play a significant role in
|
|
the Python/C API; most are simple \C{} types such as \code{int},
|
|
\code{long}, \code{double} and \code{char *}. A few structure types
|
|
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
|
|
be discussed together with the functions that use them.
|
|
|
|
\section{Exceptions}
|
|
|
|
The Python programmer only needs to deal with exceptions if specific
|
|
error handling is required; unhandled exceptions are automatically
|
|
propagated to the caller, then to the caller's caller, and so on, till
|
|
they reach the top-level interpreter, where they are reported to the
|
|
user accompanied by a stack traceback.
|
|
|
|
For \C{} programmers, however, error checking always has to be explicit.
|
|
All functions in the Python/C API can raise exceptions, unless an
|
|
explicit claim is made otherwise in a function's documentation. In
|
|
general, when a function encounters an error, it sets an exception,
|
|
discards any object references that it owns, and returns an
|
|
error indicator --- usually \NULL{} or \code{-1}. A few functions
|
|
return a Boolean true/false result, with false indicating an error.
|
|
Very few functions return no explicit error indicator or have an
|
|
ambiguous return value, and require explicit testing for errors with
|
|
\cfunction{PyErr_Occurred()}.
|
|
|
|
Exception state is maintained in per-thread storage (this is
|
|
equivalent to using global storage in an unthreaded application). A
|
|
thread can be on one of two states: an exception has occurred, or not.
|
|
The function \cfunction{PyErr_Occurred()} can be used to check for
|
|
this: it returns a borrowed reference to the exception type object
|
|
when an exception has occurred, and \NULL{} otherwise. There are a
|
|
number of functions to set the exception state:
|
|
\cfunction{PyErr_SetString()} is the most common (though not the most
|
|
general) function to set the exception state, and
|
|
\cfunction{PyErr_Clear()} clears the exception state.
|
|
|
|
The full exception state consists of three objects (all of which can
|
|
be \NULL{}): the exception type, the corresponding exception
|
|
value, and the traceback. These have the same meanings as the Python
|
|
object \code{sys.exc_type}, \code{sys.exc_value},
|
|
\code{sys.exc_traceback}; however, they are not the same: the Python
|
|
objects represent the last exception being handled by a Python
|
|
\keyword{try} \ldots\ \keyword{except} statement, while the \C{} level
|
|
exception state only exists while an exception is being passed on
|
|
between \C{} functions until it reaches the Python interpreter, which
|
|
takes care of transferring it to \code{sys.exc_type} and friends.
|
|
|
|
(Note that starting with Python 1.5, the preferred, thread-safe way to
|
|
access the exception state from Python code is to call the function
|
|
\function{sys.exc_info()}, which returns the per-thread exception state
|
|
for Python code. Also, the semantics of both ways to access the
|
|
exception state have changed so that a function which catches an
|
|
exception will save and restore its thread's exception state so as to
|
|
preserve the exception state of its caller. This prevents common bugs
|
|
in exception handling code caused by an innocent-looking function
|
|
overwriting the exception being handled; it also reduces the often
|
|
unwanted lifetime extension for objects that are referenced by the
|
|
stack frames in the traceback.)
|
|
|
|
As a general principle, a function that calls another function to
|
|
perform some task should check whether the called function raised an
|
|
exception, and if so, pass the exception state on to its caller. It
|
|
should discard any object references that it owns, and returns an
|
|
error indicator, but it should \emph{not} set another exception ---
|
|
that would overwrite the exception that was just raised, and lose
|
|
important information about the exact cause of the error.
|
|
|
|
A simple example of detecting exceptions and passing them on is shown
|
|
in the \cfunction{sum_sequence()} example above. It so happens that
|
|
that example doesn't need to clean up any owned references when it
|
|
detects an error. The following example function shows some error
|
|
cleanup. First, to remind you why you like Python, we show the
|
|
equivalent Python code:
|
|
|
|
\begin{verbatim}
|
|
def incr_item(dict, key):
|
|
try:
|
|
item = dict[key]
|
|
except KeyError:
|
|
item = 0
|
|
return item + 1
|
|
\end{verbatim}
|
|
|
|
Here is the corresponding \C{} code, in all its glory:
|
|
|
|
\begin{verbatim}
|
|
int incr_item(PyObject *dict, PyObject *key)
|
|
{
|
|
/* Objects all initialized to NULL for Py_XDECREF */
|
|
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
|
|
int rv = -1; /* Return value initialized to -1 (failure) */
|
|
|
|
item = PyObject_GetItem(dict, key);
|
|
if (item == NULL) {
|
|
/* Handle keyError only: */
|
|
if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
|
|
|
|
/* Clear the error and use zero: */
|
|
PyErr_Clear();
|
|
item = PyInt_FromLong(0L);
|
|
if (item == NULL) goto error;
|
|
}
|
|
|
|
const_one = PyInt_FromLong(1L);
|
|
if (const_one == NULL) goto error;
|
|
|
|
incremented_item = PyNumber_Add(item, const_one);
|
|
if (incremented_item == NULL) goto error;
|
|
|
|
if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
|
|
rv = 0; /* Success */
|
|
/* Continue with cleanup code */
|
|
|
|
error:
|
|
/* Cleanup code, shared by success and failure path */
|
|
|
|
/* Use Py_XDECREF() to ignore NULL references */
|
|
Py_XDECREF(item);
|
|
Py_XDECREF(const_one);
|
|
Py_XDECREF(incremented_item);
|
|
|
|
return rv; /* -1 for error, 0 for success */
|
|
}
|
|
\end{verbatim}
|
|
|
|
This example represents an endorsed use of the \code{goto} statement
|
|
in \C{}! It illustrates the use of
|
|
\cfunction{PyErr_ExceptionMatches()} and \cfunction{PyErr_Clear()} to
|
|
handle specific exceptions, and the use of \cfunction{Py_XDECREF()} to
|
|
dispose of owned references that may be \NULL{} (note the \samp{X} in
|
|
the name; \cfunction{Py_DECREF()} would crash when confronted with a
|
|
\NULL{} reference). It is important that the variables used to hold
|
|
owned references are initialized to \NULL{} for this to work;
|
|
likewise, the proposed return value is initialized to \code{-1}
|
|
(failure) and only set to success after the final call made is
|
|
successful.
|
|
|
|
|
|
\section{Embedding Python}
|
|
|
|
The one important task that only embedders (as opposed to extension
|
|
writers) of the Python interpreter have to worry about is the
|
|
initialization, and possibly the finalization, of the Python
|
|
interpreter. Most functionality of the interpreter can only be used
|
|
after the interpreter has been initialized.
|
|
|
|
The basic initialization function is \cfunction{Py_Initialize()}.
|
|
This initializes the table of loaded modules, and creates the
|
|
fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
|
|
\module{__main__}\refbimodindex{__main__} and
|
|
\module{sys}\refbimodindex{sys}. It also initializes the module
|
|
search path (\code{sys.path}).
|
|
|
|
\cfunction{Py_Initialize()} does not set the ``script argument list''
|
|
(\code{sys.argv}). If this variable is needed by Python code that
|
|
will be executed later, it must be set explicitly with a call to
|
|
\code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
|
|
to \cfunction{Py_Initialize()}.
|
|
|
|
On most systems (in particular, on \UNIX{} and Windows, although the
|
|
details are slightly different), \cfunction{Py_Initialize()}
|
|
calculates the module search path based upon its best guess for the
|
|
location of the standard Python interpreter executable, assuming that
|
|
the Python library is found in a fixed location relative to the Python
|
|
interpreter executable. In particular, it looks for a directory named
|
|
\file{lib/python\version} (replacing \file{\version} with the current
|
|
interpreter version) relative to the parent directory where the
|
|
executable named \file{python} is found on the shell command search
|
|
path (the environment variable \code{\$PATH}).
|
|
|
|
For instance, if the Python executable is found in
|
|
\file{/usr/local/bin/python}, it will assume that the libraries are in
|
|
\file{/usr/local/lib/python\version}. (In fact, this particular path
|
|
is also the ``fallback'' location, used when no executable file named
|
|
\file{python} is found along \code{\$PATH}.) The user can override
|
|
this behavior by setting the environment variable \code{\$PYTHONHOME},
|
|
or insert additional directories in front of the standard path by
|
|
setting \code{\$PYTHONPATH}.
|
|
|
|
The embedding application can steer the search by calling
|
|
\code{Py_SetProgramName(\var{file})} \emph{before} calling
|
|
\cfunction{Py_Initialize()}. Note that \code{\$PYTHONHOME} still
|
|
overrides this and \code{\$PYTHONPATH} is still inserted in front of
|
|
the standard path. An application that requires total control has to
|
|
provide its own implementation of \cfunction{Py_GetPath()},
|
|
\cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
|
|
\cfunction{Py_GetProgramFullPath()} (all defined in
|
|
\file{Modules/getpath.c}).
|
|
|
|
Sometimes, it is desirable to ``uninitialize'' Python. For instance,
|
|
the application may want to start over (make another call to
|
|
\cfunction{Py_Initialize()}) or the application is simply done with its
|
|
use of Python and wants to free all memory allocated by Python. This
|
|
can be accomplished by calling \cfunction{Py_Finalize()}. The function
|
|
\cfunction{Py_IsInitialized()} returns true iff Python is currently in the
|
|
initialized state. More information about these functions is given in
|
|
a later chapter.
|
|
|
|
|
|
\chapter{The Very High Level Layer}
|
|
|
|
The functions in this chapter will let you execute Python source code
|
|
given in a file or a buffer, but they will not let you interact in a
|
|
more detailed way with the interpreter.
|
|
|
|
\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\chapter{Reference Counting}
|
|
|
|
The macros in this section are used for managing reference counts
|
|
of Python objects.
|
|
|
|
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
|
|
Increment the reference count for object \code{o}. The object must
|
|
not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
|
|
\cfunction{Py_XINCREF()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
|
|
Increment the reference count for object \var{o}. The object may be
|
|
\NULL{}, in which case the macro has no effect.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
|
|
Decrement the reference count for object \var{o}. The object must
|
|
not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
|
|
\cfunction{Py_XDECREF()}. If the reference count reaches zero, the
|
|
object's type's deallocation function (which must not be \NULL{}) is
|
|
invoked.
|
|
|
|
\strong{Warning:} The deallocation function can cause arbitrary Python
|
|
code to be invoked (e.g. when a class instance with a \method{__del__()}
|
|
method is deallocated). While exceptions in such code are not
|
|
propagated, the executed code has free access to all Python global
|
|
variables. This means that any object that is reachable from a global
|
|
variable should be in a consistent state before \cfunction{Py_DECREF()} is
|
|
invoked. For example, code to delete an object from a list should
|
|
copy a reference to the deleted object in a temporary variable, update
|
|
the list data structure, and then call \cfunction{Py_DECREF()} for the
|
|
temporary variable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
|
|
Decrement the reference count for object \var{o}. The object may be
|
|
\NULL{}, in which case the macro has no effect; otherwise the effect
|
|
is the same as for \cfunction{Py_DECREF()}, and the same warning
|
|
applies.
|
|
\end{cfuncdesc}
|
|
|
|
The following functions or macros are only for internal use:
|
|
\cfunction{_Py_Dealloc()}, \cfunction{_Py_ForgetReference()},
|
|
\cfunction{_Py_NewReference()}, 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}
|
|
|
|
The functions in this chapter will let you handle and raise Python
|
|
exceptions. It is important to understand some of the basics of
|
|
Python exception handling. It works somewhat like the \UNIX{}
|
|
\code{errno} variable: there is a global indicator (per thread) of the
|
|
last error that occurred. Most functions don't clear this on success,
|
|
but will set it to indicate the cause of the error on failure. Most
|
|
functions also return an error indicator, usually \NULL{} if they are
|
|
supposed to return a pointer, or \code{-1} if they return an integer
|
|
(exception: the \code{PyArg_Parse*()} functions return \code{1} for
|
|
success and \code{0} for failure). When a function must fail because
|
|
some function it called failed, it generally doesn't set the error
|
|
indicator; the function it called already set it.
|
|
|
|
The error indicator consists of three Python objects corresponding to
|
|
the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
|
|
\code{sys.exc_traceback}. API functions exist to interact with the
|
|
error indicator in various ways. There is a separate error indicator
|
|
for each thread.
|
|
|
|
% XXX Order of these should be more thoughtful.
|
|
% Either alphabetical or some kind of structure.
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_Print}{}
|
|
Print a standard traceback to \code{sys.stderr} and clear the error
|
|
indicator. Call this function only when the error indicator is set.
|
|
(Otherwise it will cause a fatal error!)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyErr_Occurred}{}
|
|
Test whether the error indicator is set. If set, return the exception
|
|
\emph{type} (the first argument to the last call to one of the
|
|
\code{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If
|
|
not set, return \NULL{}. You do not own a reference to the return
|
|
value, so you do not need to \cfunction{Py_DECREF()} it.
|
|
\strong{Note:} do not compare the return value to a specific
|
|
exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
|
|
below.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
|
|
Equivalent to
|
|
\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
|
|
This should only be called when an exception is actually set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
|
|
Return true if the \var{given} exception matches the exception in
|
|
\var{exc}. If \var{exc} is a class object, this also returns true
|
|
when \var{given} is a subclass. If \var{exc} is a tuple, all
|
|
exceptions in the tuple (and recursively in subtuples) are searched
|
|
for a match. This should only be called when an exception is actually
|
|
set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
|
|
Under certain circumstances, the values returned by
|
|
\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
|
|
\code{*\var{exc}} is a class object but \code{*\var{val}} is not an
|
|
instance of the same class. This function can be used to instantiate
|
|
the class in that case. If the values are already normalized, nothing
|
|
happens.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_Clear}{}
|
|
Clear the error indicator. If the error indicator is not set, there
|
|
is no effect.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, PyObject **ptraceback}
|
|
Retrieve the error indicator into three variables whose addresses are
|
|
passed. If the error indicator is not set, set all three variables to
|
|
\NULL{}. If it is set, it will be cleared and you own a reference to
|
|
each object retrieved. The value and traceback object may be \NULL{}
|
|
even when the type object is not. \strong{Note:} this function is
|
|
normally only used by code that needs to handle exceptions or by code
|
|
that needs to save and restore the error indicator temporarily.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
|
|
Set the error indicator from the three objects. If the error
|
|
indicator is already set, it is cleared first. If the objects are
|
|
\NULL{}, the error indicator is cleared. Do not pass a \NULL{} type
|
|
and non-\NULL{} value or traceback. The exception type should be a
|
|
string or class; if it is a class, the value should be an instance of
|
|
that class. Do not pass an invalid exception type or value.
|
|
(Violating these rules will cause subtle problems later.) This call
|
|
takes away a reference to each object, i.e. you must own a reference
|
|
to each object before the call and after the call you no longer own
|
|
these references. (If you don't understand this, don't use this
|
|
function. I warned you.) \strong{Note:} this function is normally
|
|
only used by code that needs to save and restore the error indicator
|
|
temporarily.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
|
|
This is the most common way to set the error indicator. The first
|
|
argument specifies the exception type; it is normally one of the
|
|
standard exceptions, e.g. \code{PyExc_RuntimeError}. You need not
|
|
increment its reference count. The second argument is an error
|
|
message; it is converted to a string object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
|
|
This function is similar to \cfunction{PyErr_SetString()} but lets you
|
|
specify an arbitrary Python object for the ``value'' of the exception.
|
|
You need not increment its reference count.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
|
|
This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
|
|
This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
|
|
\var{message})}, where \var{message} indicates that a built-in operation
|
|
was invoked with an illegal argument. It is mostly for internal use.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyErr_NoMemory}{}
|
|
This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
|
|
returns \NULL{} so an object allocation function can write
|
|
\samp{return PyErr_NoMemory();} when it runs out of memory.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyErr_SetFromErrno}{PyObject *type}
|
|
This is a convenience function to raise an exception when a \C{} library
|
|
function has returned an error and set the \C{} variable \code{errno}.
|
|
It constructs a tuple object whose first item is the integer
|
|
\code{errno} value and whose second item is the corresponding error
|
|
message (gotten from \cfunction{strerror()}), and then calls
|
|
\samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
|
|
the \code{errno} value is \constant{EINTR}, indicating an interrupted
|
|
system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
|
|
the error indicator, leaves it set to that. The function always
|
|
returns \NULL{}, so a wrapper function around a system call can write
|
|
\samp{return PyErr_SetFromErrno();} when the system call returns an
|
|
error.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
|
|
This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
|
|
\var{message})}, where \var{message} indicates that an internal
|
|
operation (e.g. a Python/C API function) was invoked with an illegal
|
|
argument. It is mostly for internal use.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
|
|
This function interacts with Python's signal handling. It checks
|
|
whether a signal has been sent to the processes and if so, invokes the
|
|
corresponding signal handler. If the
|
|
\module{signal}\refbimodindex{signal} module is supported, this can
|
|
invoke a signal handler written in Python. In all cases, the default
|
|
effect for \constant{SIGINT} is to raise the
|
|
\exception{KeyboadInterrupt} exception. If an exception is raised the
|
|
error indicator is set and the function returns \code{1}; otherwise
|
|
the function returns \code{0}. The error indicator may or may not be
|
|
cleared if it was previously set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
|
|
This function is obsolete (XXX or platform dependent?). It simulates
|
|
the effect of a \constant{SIGINT} signal arriving --- the next time
|
|
\cfunction{PyErr_CheckSignals()} is called,
|
|
\exception{KeyboadInterrupt} will be raised.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
|
|
PyObject *base, PyObject *dict}
|
|
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
|
|
of the form \code{module.class}. The \var{base} and \var{dict}
|
|
arguments are normally \NULL{}. Normally, this creates a class
|
|
object derived from the root for all exceptions, the built-in name
|
|
\exception{Exception} (accessible in \C{} as \code{PyExc_Exception}).
|
|
In this case the \code{__module__} attribute of the new class is set to the
|
|
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
|
|
user has specified the \code{-X} command line option to use string
|
|
exceptions, for backward compatibility, or when the \var{base}
|
|
argument is not a class object (and not \NULL{}), a string object
|
|
created from the entire \var{name} argument is returned. The
|
|
\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
|
|
variables and methods.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Standard Exceptions}
|
|
|
|
All standard Python exceptions are available as global variables whose
|
|
names are \samp{PyExc_} followed by the Python exception name.
|
|
These have the type \code{PyObject *}; they are all either class
|
|
objects or string objects, depending on the use of the \code{-X}
|
|
option to the interpreter. For completeness, here are all the
|
|
variables:
|
|
\code{PyExc_Exception},
|
|
\code{PyExc_StandardError},
|
|
\code{PyExc_ArithmeticError},
|
|
\code{PyExc_LookupError},
|
|
\code{PyExc_AssertionError},
|
|
\code{PyExc_AttributeError},
|
|
\code{PyExc_EOFError},
|
|
\code{PyExc_FloatingPointError},
|
|
\code{PyExc_IOError},
|
|
\code{PyExc_ImportError},
|
|
\code{PyExc_IndexError},
|
|
\code{PyExc_KeyError},
|
|
\code{PyExc_KeyboardInterrupt},
|
|
\code{PyExc_MemoryError},
|
|
\code{PyExc_NameError},
|
|
\code{PyExc_OverflowError},
|
|
\code{PyExc_RuntimeError},
|
|
\code{PyExc_SyntaxError},
|
|
\code{PyExc_SystemError},
|
|
\code{PyExc_SystemExit},
|
|
\code{PyExc_TypeError},
|
|
\code{PyExc_ValueError},
|
|
\code{PyExc_ZeroDivisionError}.
|
|
|
|
|
|
\chapter{Utilities}
|
|
|
|
The functions in this chapter perform various utility tasks, such as
|
|
parsing function arguments and constructing Python values from \C{}
|
|
values.
|
|
|
|
\section{OS Utilities}
|
|
|
|
\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
|
|
Return true (nonzero) if the standard I/O file \var{fp} with name
|
|
\var{filename} is deemed interactive. This is the case for files for
|
|
which \samp{isatty(fileno(\var{fp}))} is true. If the global flag
|
|
\code{Py_InteractiveFlag} is true, this function also returns true if
|
|
the \var{name} pointer is \NULL{} or if the name is equal to one of
|
|
the strings \code{"<stdin>"} or \code{"???"}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
|
|
Return the time of last modification of the file \var{filename}.
|
|
The result is encoded in the same way as the timestamp returned by
|
|
the standard \C{} library function \cfunction{time()}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Process Control}
|
|
|
|
\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
|
|
\cfunction{abort()} is called which will attempt to produce a
|
|
\file{core} file.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_Exit}{int status}
|
|
Exit the current process. This calls \cfunction{Py_Finalize()} and
|
|
then calls the standard \C{} library function
|
|
\code{exit(\var{status})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
|
|
Register a cleanup function to be called by \cfunction{Py_Finalize()}.
|
|
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, \cfunction{Py_AtExit()} returns
|
|
\code{0}; on failure, it returns \code{-1}. The cleanup function
|
|
registered last is called first. Each cleanup function will be called
|
|
at most once. Since Python's internal finallization will have
|
|
completed before the cleanup function, no Python APIs should be called
|
|
by \var{func}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Importing Modules}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
|
|
This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
|
|
below, leaving the \var{globals} and \var{locals} arguments set to
|
|
\NULL{}. When the \var{name} argument contains a dot (i.e., when
|
|
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
|
|
module rather than the top-level package containing it as would
|
|
otherwise be the case. (Unfortunately, this has an additional side
|
|
effect when \var{name} in fact specifies a subpackage instead of a
|
|
submodule: the submodules specified in the package's \code{__all__}
|
|
variable are loaded.) Return a new reference to the imported module,
|
|
or \NULL{} with an exception set on failure (the module may still
|
|
be created in this case).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
|
|
Import a module. This is best described by referring to the built-in
|
|
Python function \function{__import__()}\bifuncindex{__import__}, as
|
|
the standard \function{__import__()} function calls this function
|
|
directly.
|
|
|
|
The return value is a new reference to the imported module or
|
|
top-level package, or \NULL{} with an exception set on failure
|
|
(the module may still be created in this case). Like for
|
|
\function{__import__()}, the return value when a submodule of a
|
|
package was requested is normally the top-level package, unless a
|
|
non-empty \var{fromlist} was given.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name}
|
|
This is a higher-level interface that calls the current ``import hook
|
|
function''. It invokes the \function{__import__()} function from the
|
|
\code{__builtins__} of the current globals. This means that the
|
|
import is done using whatever import hooks are installed in the
|
|
current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
|
|
\module{ihooks}\refstmodindex{ihooks}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
|
|
Reload a module. This is best described by referring to the built-in
|
|
Python function \function{reload()}\bifuncindex{reload}, as the standard
|
|
\function{reload()} function calls this function directly. Return a
|
|
new reference to the reloaded module, or \NULL{} with an exception set
|
|
on failure (the module still exists in this case).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name}
|
|
Return the module object corresponding to a module name. The
|
|
\var{name} argument may be of the form \code{package.module}). First
|
|
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
|
|
action is most common, this does not return a new reference, and you
|
|
do not own the returned reference. Return \NULL{} with an
|
|
exception set on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co}
|
|
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
|
|
built-in function \function{compile()}\bifuncindex{compile}, load the
|
|
module. Return a new reference to the module object, or \NULL{} with
|
|
an exception set if an error occurred (the module may still be created
|
|
in this case). (This function would reload the module if it was
|
|
already imported.)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
|
|
Return the magic number for Python bytecode files (a.k.a. \file{.pyc}
|
|
and \file{.pyo} files). The magic number should be present in the
|
|
first four bytes of the bytecode file, in little-endian byte order.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{}
|
|
Return the dictionary used for the module administration
|
|
(a.k.a. \code{sys.modules}). Note that this is a per-interpreter
|
|
variable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{_PyImport_Init}{}
|
|
Initialize the import mechanism. For internal use only.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
|
|
Empty the module table. For internal use only.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{_PyImport_Fini}{}
|
|
Finalize the import mechanism. For internal use only.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
|
|
For internal use only.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
|
|
For internal use only.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
|
|
Load a frozen module. Return \code{1} for success, \code{0} if the
|
|
module is not found, and \code{-1} with an exception set if the
|
|
initialization failed. To access the imported module on a successful
|
|
load, use \cfunction{PyImport_ImportModule()}.
|
|
(Note the misnomer --- this function would reload the module if it was
|
|
already imported.)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{ctypedesc}{struct _frozen}
|
|
This is the structure type definition for frozen module descriptors,
|
|
as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
|
|
the Python source distribution). Its definition is:
|
|
\begin{verbatim}
|
|
struct _frozen {
|
|
char *name;
|
|
unsigned char *code;
|
|
int size;
|
|
};
|
|
\end{verbatim}
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
|
|
This pointer is initialized to point to an array of \code{struct
|
|
_frozen} records, terminated by one whose members are all \NULL{}
|
|
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
|
|
dynamically created collection of frozen modules.
|
|
\end{cvardesc}
|
|
|
|
|
|
\chapter{Abstract Objects Layer}
|
|
|
|
The functions in this chapter interact with Python objects regardless
|
|
of their type, or with wide classes of object types (e.g. all
|
|
numerical types, or all sequence types). When used on object types
|
|
for which they do not apply, they will flag a Python exception.
|
|
|
|
\section{Object Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
|
|
Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error
|
|
The flags argument is used to enable certain printing
|
|
options. The only option currently supported is
|
|
\constant{Py_Print_RAW}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
|
|
Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
|
|
\code{0} otherwise. This is equivalent to the Python expression
|
|
\samp{hasattr(\var{o}, \var{attr_name})}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
|
|
Retrieve an attribute named \var{attr_name} from object \var{o}.
|
|
Returns the attribute value on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression
|
|
\samp{\var{o}.\var{attr_name}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
|
|
Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
|
|
\code{0} otherwise. This is equivalent to the Python expression
|
|
\samp{hasattr(\var{o}, \var{attr_name})}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
|
|
Retrieve an attribute named \var{attr_name} from object \var{o}.
|
|
Returns the attribute value on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression
|
|
\samp{\var{o}.\var{attr_name}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
|
|
Set the value of the attribute named \var{attr_name}, for object
|
|
\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
|
|
the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
|
|
\var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
|
|
Set the value of the attribute named \var{attr_name}, for
|
|
object \var{o},
|
|
to the value \var{v}. Returns \code{-1} on failure. This is
|
|
the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
|
|
\var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
|
|
Delete attribute named \var{attr_name}, for object \var{o}. Returns
|
|
\code{-1} on failure. This is the equivalent of the Python
|
|
statement: \samp{del \var{o}.\var{attr_name}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
|
|
Delete attribute named \var{attr_name}, for object \var{o}. Returns
|
|
\code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{del \var{o}.\var{attr_name}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
|
|
Compare the values of \var{o1} and \var{o2} using a routine provided
|
|
by \var{o1}, if one exists, otherwise with a routine provided by
|
|
\var{o2}. The result of the comparison is returned in \var{result}.
|
|
Returns \code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
|
|
Compare the values of \var{o1} and \var{o2} using a routine provided
|
|
by \var{o1}, if one exists, otherwise with a routine provided by
|
|
\var{o2}. Returns the result of the comparison on success. On error,
|
|
the value returned is undefined; use \cfunction{PyErr_Occurred()} to
|
|
detect an error. This is equivalent to the
|
|
Python expression \samp{cmp(\var{o1}, \var{o2})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
|
|
Compute the string representation of object, \var{o}. Returns the
|
|
string representation on success, \NULL{} on failure. This is
|
|
the equivalent of the Python expression \samp{repr(\var{o})}.
|
|
Called by the \function{repr()}\bifuncindex{repr} built-in function
|
|
and by reverse quotes.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
|
|
Compute the string representation of object \var{o}. Returns the
|
|
string representation on success, \NULL{} on failure. This is
|
|
the equivalent of the Python expression \samp{str(\var{o})}.
|
|
Called by the \function{str()}\bifuncindex{str} built-in function and
|
|
by the \keyword{print} statement.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
|
|
Determine if the object \var{o}, is callable. Return \code{1} if the
|
|
object is callable and \code{0} otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
|
|
Call a callable Python object \var{callable_object}, with
|
|
arguments given by the tuple \var{args}. If no arguments are
|
|
needed, then args may be \NULL{}. Returns the result of the
|
|
call on success, or \NULL{} on failure. This is the equivalent
|
|
of the Python expression \samp{apply(\var{o}, \var{args})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
|
|
Call a callable Python object \var{callable_object}, with a
|
|
variable number of \C{} arguments. The \C{} arguments are described
|
|
using a \cfunction{Py_BuildValue()} style format string. The format may
|
|
be \NULL{}, indicating that no arguments are provided. Returns the
|
|
result of the call on success, or \NULL{} on failure. This is
|
|
the equivalent of the Python expression \samp{apply(\var{o},
|
|
\var{args})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
|
|
Call the method named \var{m} of object \var{o} with a variable number
|
|
of C arguments. The \C{} arguments are described by a
|
|
\cfunction{Py_BuildValue()} format string. The format may be \NULL{},
|
|
indicating that no arguments are provided. Returns the result of the
|
|
call on success, or \NULL{} on failure. This is the equivalent of the
|
|
Python expression \samp{\var{o}.\var{method}(\var{args})}.
|
|
Note that Special method names, such as \method{__add__()},
|
|
\method{__getitem__()}, and so on are not supported. The specific
|
|
abstract-object routines for these must be used.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
|
|
Compute and return the hash value of an object \var{o}. On
|
|
failure, return \code{-1}. This is the equivalent of the Python
|
|
expression \samp{hash(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
|
|
Returns \code{1} if the object \var{o} is considered to be true, and
|
|
\code{0} otherwise. This is equivalent to the Python expression
|
|
\samp{not not \var{o}}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
|
|
On success, returns a type object corresponding to the object
|
|
type of object \var{o}. On failure, returns \NULL{}. This is
|
|
equivalent to the Python expression \samp{type(\var{o})}.
|
|
\bifuncindex{type}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
|
|
Return the length of object \var{o}. If the object \var{o} provides
|
|
both sequence and mapping protocols, the sequence length is
|
|
returned. On error, \code{-1} is returned. This is the equivalent
|
|
to the Python expression \samp{len(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
|
|
Return element of \var{o} corresponding to the object \var{key} or
|
|
\NULL{} on failure. This is the equivalent of the Python expression
|
|
\samp{\var{o}[\var{key}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
|
|
Map the object \var{key} to the value \var{v}.
|
|
Returns \code{-1} on failure. This is the equivalent
|
|
of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
|
|
Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
|
|
failure. This is the equivalent of the Python statement \samp{del
|
|
\var{o}[\var{key}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Number Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
|
|
Returns \code{1} if the object \var{o} provides numeric protocols, and
|
|
false otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
|
|
Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression
|
|
\samp{\var{o1} + \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
|
|
Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
|
|
on failure. This is the equivalent of the Python expression
|
|
\samp{\var{o1} - \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
|
|
Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression
|
|
\samp{\var{o1} * \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
|
|
Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
|
|
failure.
|
|
This is the equivalent of the Python expression \samp{\var{o1} /
|
|
\var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
|
|
Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression
|
|
\samp{\var{o1} \% \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
|
|
See the built-in function \function{divmod()}\bifuncindex{divmod}.
|
|
Returns \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{divmod(\var{o1}, \var{o2})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
|
|
See the built-in function \function{pow()}\bifuncindex{pow}. Returns
|
|
\NULL{} on failure. This is the equivalent of the Python expression
|
|
\samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional.
|
|
If \var{o3} is to be ignored, pass \code{Py_None} in its place.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
|
|
Returns the negation of \var{o} on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression \samp{-\var{o}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
|
|
Returns \var{o} on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression \samp{+\var{o}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
|
|
Returns the absolute value of \var{o}, or \NULL{} on failure. This is
|
|
the equivalent of the Python expression \samp{abs(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
|
|
Returns the bitwise negation of \var{o} on success, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression
|
|
\samp{\~\var{o}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
|
|
Returns the result of left shifting \var{o1} by \var{o2} on success,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o1} << \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
|
|
Returns the result of right shifting \var{o1} by \var{o2} on success,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o1} >> \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
|
|
Returns the result of ``anding'' \var{o2} and \var{o2} on success and
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o1} and \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
|
|
Returns the bitwise exclusive or of \var{o1} by \var{o2} on success,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o1} \^{ }\var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
|
|
Returns the result of \var{o1} and \var{o2} on success, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression
|
|
\samp{\var{o1} or \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
|
|
This function takes the addresses of two variables of type
|
|
\code{PyObject*}.
|
|
|
|
If the objects pointed to by \code{*\var{p1}} and \code{*\var{p2}}
|
|
have the same type, increment their reference count and return
|
|
\code{0} (success). If the objects can be converted to a common
|
|
numeric type, replace \code{*p1} and \code{*p2} by their converted
|
|
value (with 'new' reference counts), and return \code{0}.
|
|
If no conversion is possible, or if some other error occurs,
|
|
return \code{-1} (failure) and don't increment the reference counts.
|
|
The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the
|
|
Python statement \samp{\var{o1}, \var{o2} = coerce(\var{o1},
|
|
\var{o2})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
|
|
Returns the \var{o} converted to an integer object on success, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{int(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
|
|
Returns the \var{o} converted to a long integer object on success,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{long(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
|
|
Returns the \var{o} converted to a float object on success, or \NULL{}
|
|
on failure. This is the equivalent of the Python expression
|
|
\samp{float(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Sequence Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
|
|
Return \code{1} if the object provides sequence protocol, and \code{0}
|
|
otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
|
|
Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
|
|
failure. This is the equivalent of the Python
|
|
expression \samp{\var{o1} + \var{o2}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
|
|
Return the result of repeating sequence object \var{o} \var{count}
|
|
times, or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o} * \var{count}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
|
|
Return the \var{i}th element of \var{o}, or \NULL{} on failure. This
|
|
is the equivalent of the Python expression \samp{\var{o}[\var{i}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
|
|
Return the slice of sequence object \var{o} between \var{i1} and
|
|
\var{i2}, or \NULL{} on failure. This is the equivalent of the Python
|
|
expression \samp{\var{o}[\var{i1}:\var{i2}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
|
|
Assign object \var{v} to the \var{i}th element of \var{o}.
|
|
Returns \code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{\var{o}[\var{i}] = \var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
|
|
Delete the \var{i}th element of object \var{v}. Returns
|
|
\code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{del \var{o}[\var{i}]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
|
|
Assign the sequence object \var{v} to the slice in sequence
|
|
object \var{o} from \var{i1} to \var{i2}. This is the equivalent of
|
|
the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
|
|
Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}.
|
|
Returns \code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
|
|
Returns the \var{o} as a tuple on success, and \NULL{} on failure.
|
|
This is equivalent to the Python expression \code{tuple(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
|
|
Return the number of occurrences of \var{value} in \var{o}, that is,
|
|
return the number of keys for which \code{\var{o}[\var{key}] ==
|
|
\var{value}}. On failure, return \code{-1}. This is equivalent to
|
|
the Python expression \samp{\var{o}.count(\var{value})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
|
|
Determine if \var{o} contains \var{value}. If an item in \var{o} is
|
|
equal to \var{value}, return \code{1}, otherwise return \code{0}. On
|
|
error, return \code{-1}. This is equivalent to the Python expression
|
|
\samp{\var{value} in \var{o}}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
|
|
Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
|
|
\var{value}}. On error, return \code{-1}. This is equivalent to
|
|
the Python expression \samp{\var{o}.index(\var{value})}.
|
|
\end{cfuncdesc}
|
|
|
|
\section{Mapping Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
|
|
Return \code{1} if the object provides mapping protocol, and \code{0}
|
|
otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
|
|
Returns the number of keys in object \var{o} on success, and \code{-1}
|
|
on failure. For objects that do not provide sequence protocol,
|
|
this is equivalent to the Python expression \samp{len(\var{o})}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
|
|
Remove the mapping for object \var{key} from the object \var{o}.
|
|
Return \code{-1} on failure. This is equivalent to
|
|
the Python statement \samp{del \var{o}[\var{key}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
|
|
Remove the mapping for object \var{key} from the object \var{o}.
|
|
Return \code{-1} on failure. This is equivalent to
|
|
the Python statement \samp{del \var{o}[\var{key}]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
|
|
On success, return \code{1} if the mapping object has the key \var{key}
|
|
and \code{0} otherwise. This is equivalent to the Python expression
|
|
\samp{\var{o}.has_key(\var{key})}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
|
|
Return \code{1} if the mapping object has the key \var{key} and
|
|
\code{0} otherwise. This is equivalent to the Python expression
|
|
\samp{\var{o}.has_key(\var{key})}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
|
|
On success, return a list of the keys in object \var{o}. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression \samp{\var{o}.keys()}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
|
|
On success, return a list of the values in object \var{o}. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression \samp{\var{o}.values()}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
|
|
On success, return a list of the items in object \var{o}, where
|
|
each item is a tuple containing a key-value pair. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression \samp{\var{o}.items()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
|
|
Make object \var{o} empty. Returns \code{1} on success and \code{0}
|
|
on failure. This is equivalent to the Python statement
|
|
\samp{for key in \var{o}.keys(): del \var{o}[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
|
|
Return element of \var{o} corresponding to the object \var{key} or
|
|
\NULL{} on failure. This is the equivalent of the Python expression
|
|
\samp{\var{o}[\var{key}]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
|
|
Map the object \var{key} to the value \var{v} in object \var{o}.
|
|
Returns \code{-1} on failure. This is the equivalent of the Python
|
|
statement \samp{\var{o}[\var{key}] = \var{v}}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Constructors}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode}
|
|
On success, returns a new file object that is opened on the
|
|
file given by \var{file_name}, with a file mode given by \var{mode},
|
|
where \var{mode} has the same semantics as the standard \C{} routine
|
|
\cfunction{fopen()}. On failure, return \code{-1}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del}
|
|
Return a new file object for an already opened standard \C{} file
|
|
pointer, \var{fp}. A file name, \var{file_name}, and open mode,
|
|
\var{mode}, must be provided as well as a flag, \var{close_on_del},
|
|
that indicates whether the file is to be closed when the file object
|
|
is destroyed. On failure, return \code{-1}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
|
|
Returns a new float object with the value \var{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
|
|
Returns a new int object with the value \var{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
|
|
Returns a new list of length \var{len} on success, and \NULL{} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
|
|
Returns a new long object with the value \var{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
|
|
Returns a new long object with the value \var{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
|
|
Returns a new empty dictionary on success, and \NULL{} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v}
|
|
Returns a new string object with the value \var{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int len}
|
|
Returns a new string object with the value \var{v} and length
|
|
\var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{},
|
|
the contents of the string are uninitialized.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
|
|
Returns a new tuple of length \var{len} on success, and \NULL{} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\chapter{Concrete Objects Layer}
|
|
|
|
The functions in this chapter are specific to certain Python object
|
|
types. Passing them an object of the wrong type is not a good idea;
|
|
if you receive an object from a Python program and you are not sure
|
|
that it has the right type, you must perform a type check first;
|
|
e.g. to check that an object is a dictionary, use
|
|
\cfunction{PyDict_Check()}. The chapter is structured like the
|
|
``family tree'' of Python object types.
|
|
|
|
|
|
\section{Fundamental Objects}
|
|
|
|
This section describes Python type objects and the singleton object
|
|
\code{None}.
|
|
|
|
|
|
\subsection{Type Objects}
|
|
|
|
\begin{ctypedesc}{PyTypeObject}
|
|
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyObject *}{PyType_Type}
|
|
|
|
\end{cvardesc}
|
|
|
|
|
|
\subsection{The None Object}
|
|
|
|
\begin{cvardesc}{PyObject *}{Py_None}
|
|
XXX macro
|
|
\end{cvardesc}
|
|
|
|
|
|
\section{Sequence Objects}
|
|
|
|
Generic operations on sequence objects were discussed in the previous
|
|
chapter; this section deals with the specific kinds of sequence
|
|
objects that are intrinsic to the Python language.
|
|
|
|
|
|
\subsection{String Objects}
|
|
|
|
\begin{ctypedesc}{PyStringObject}
|
|
This subtype of \code{PyObject} represents a Python string object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyString_Type}
|
|
This instance of \code{PyTypeObject} represents the Python string type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Tuple Objects}
|
|
|
|
\begin{ctypedesc}{PyTupleObject}
|
|
This subtype of \code{PyObject} represents a Python tuple object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
|
|
This instance of \code{PyTypeObject} represents the Python tuple type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
|
|
Return true if the argument is a tuple object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
|
|
Return a new tuple object of size \var{s}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
|
|
Takes a pointer to a tuple object, and returns the size
|
|
of that tuple.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
|
|
Returns the object at position \var{pos} in the tuple pointed
|
|
to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
|
|
raises an \exception{IndexError} exception.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
|
|
Does the same, but does no checking of its arguments.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
|
|
int low,
|
|
int high}
|
|
Takes a slice of the tuple pointed to by \var{p} from
|
|
\var{low} to \var{high} and returns it as a new tuple.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
|
|
int pos,
|
|
PyObject *o}
|
|
Inserts a reference to object \var{o} at position \var{pos} of
|
|
the tuple pointed to by \var{p}. It returns \code{0} on success.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
|
|
int pos,
|
|
PyObject *o}
|
|
|
|
Does the same, but does no error checking, and
|
|
should \emph{only} be used to fill in brand new tuples.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
|
|
int new,
|
|
int last_is_sticky}
|
|
Can be used to resize a tuple. Because tuples are
|
|
\emph{supposed} to be immutable, this should only be used if there is only
|
|
one module referencing the object. Do \emph{not} use this if the tuple may
|
|
already be known to some other part of the code. \var{last_is_sticky} is
|
|
a flag --- if set, the tuple will grow or shrink at the front, otherwise
|
|
it will grow or shrink at the end. Think of this as destroying the old
|
|
tuple and creating a new one, only more efficiently.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{List Objects}
|
|
|
|
\begin{ctypedesc}{PyListObject}
|
|
This subtype of \code{PyObject} represents a Python list object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyList_Type}
|
|
This instance of \code{PyTypeObject} represents the Python list type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyListObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Mapping Objects}
|
|
|
|
\subsection{Dictionary Objects}
|
|
|
|
\begin{ctypedesc}{PyDictObject}
|
|
This subtype of \code{PyObject} represents a Python dictionary object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyDict_Type}
|
|
This instance of \code{PyTypeObject} represents the Python dictionary type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyDictObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
|
|
Returns a new empty dictionary.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
|
|
Empties an existing dictionary of all key/value pairs.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
|
|
PyObject *key,
|
|
PyObject *val}
|
|
Inserts \var{value} into the dictionary with a key of \var{key}. Both
|
|
\var{key} and \var{value} should be PyObjects, and \var{key} should be
|
|
hashable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
|
|
char *key,
|
|
PyObject *val}
|
|
Inserts \var{value} into the dictionary using \var{key}
|
|
as a key. \var{key} should be a \code{char *}. The key object is
|
|
created using \code{PyString_FromString(\var{key})}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
|
|
Removes the entry in dictionary \var{p} with key \var{key}.
|
|
\var{key} is a PyObject.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
|
|
Removes the entry in dictionary \var{p} which has a key
|
|
specified by the \code{char *}\var{key}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
|
|
Returns the object from dictionary \var{p} which has a key
|
|
\var{key}. Returns \NULL{} if the key \var{key} is not present.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
|
|
Does the same, but \var{key} is specified as a
|
|
\code{char *}, rather than a \code{PyObject *}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
|
|
Returns a \code{PyListObject} containing all the items
|
|
from the dictionary, as in the mapping method \method{items()} (see
|
|
the \emph{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
|
|
Returns a \code{PyListObject} containing all the keys
|
|
from the dictionary, as in the mapping method \method{keys()} (see the
|
|
\emph{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
|
|
Returns a \code{PyListObject} containing all the values
|
|
from the dictionary \var{p}, as in the mapping method
|
|
\method{values()} (see the \emph{Python Library Reference}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
|
|
Returns the number of items in the dictionary.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
|
|
int ppos,
|
|
PyObject **pkey,
|
|
PyObject **pvalue}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Numeric Objects}
|
|
|
|
\subsection{Plain Integer Objects}
|
|
|
|
\begin{ctypedesc}{PyIntObject}
|
|
This subtype of \code{PyObject} represents a Python integer object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyInt_Type}
|
|
This instance of \code{PyTypeObject} represents the Python plain
|
|
integer type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
|
|
Creates a new integer object with a value of \var{ival}.
|
|
|
|
The current implementation keeps an array of integer objects for all
|
|
integers between \code{-1} and \code{100}, when you create an int in
|
|
that range you actually just get back a reference to the existing
|
|
object. So it should be possible to change the value of \code{1}. I
|
|
suspect the behaviour of python in this case is undefined. :-)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
|
|
Returns the value of the object \var{io}. No error checking is
|
|
performed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
|
|
Will first attempt to cast the object to a \code{PyIntObject}, if
|
|
it is not already one, and then return its value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_GetMax}{}
|
|
Returns the systems idea of the largest integer it can handle
|
|
(\constant{LONG_MAX}, as defined in the system header files).
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Long Integer Objects}
|
|
|
|
\begin{ctypedesc}{PyLongObject}
|
|
This subtype of \code{PyObject} represents a Python long integer
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyLong_Type}
|
|
This instance of \code{PyTypeObject} represents the Python long
|
|
integer type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyLongObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Floating Point Objects}
|
|
|
|
\begin{ctypedesc}{PyFloatObject}
|
|
This subtype of \code{PyObject} represents a Python floating point
|
|
object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
|
|
This instance of \code{PyTypeObject} represents the Python floating
|
|
point type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyFloatObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{Complex Number Objects}
|
|
|
|
\begin{ctypedesc}{Py_complex}
|
|
The \C{} structure which corresponds to the value portion of a Python
|
|
complex number object. Most of the functions for dealing with complex
|
|
number objects use structures of this type as input or output values,
|
|
as appropriate. It is defined as:
|
|
|
|
\begin{verbatim}
|
|
typedef struct {
|
|
double real;
|
|
double imag;
|
|
} Py_complex;
|
|
\end{verbatim}
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{PyComplexObject}
|
|
This subtype of \code{PyObject} represents a Python complex number object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
|
|
This instance of \code{PyTypeObject} represents the Python complex
|
|
number type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyComplexObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
|
|
|
|
\end{cfuncdesc}
|
|
|
|
|
|
|
|
\section{Other Objects}
|
|
|
|
\subsection{File Objects}
|
|
|
|
\begin{ctypedesc}{PyFileObject}
|
|
This subtype of \code{PyObject} represents a Python file object.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cvardesc}{PyTypeObject}{PyFile_Type}
|
|
This instance of \code{PyTypeObject} represents the Python file type.
|
|
\end{cvardesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
|
|
Returns true if its argument is a \code{PyFileObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
|
|
Creates a new \code{PyFileObject} pointing to the file
|
|
specified in \var{name} with the mode specified in \var{mode}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
|
|
char *name, char *mode, int (*close)}
|
|
Creates a new \code{PyFileObject} from the already-open \var{fp}.
|
|
The function \var{close} will be called when the file should be
|
|
closed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
|
|
Returns the file object associated with \var{p} as a \code{FILE *}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
|
|
undocumented as yet
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
|
|
Returns the name of the file specified by \var{p} as a
|
|
\code{PyStringObject}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
|
|
Available on systems with \cfunction{setvbuf()} only. This should
|
|
only be called immediately after file object creation.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
|
|
Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
|
|
Returns the previosu value. This function clears any errors, and will
|
|
return \code{0} as the previous value if the attribute either does not
|
|
exist or if there were errors in retrieving it. There is no way to
|
|
detect errors from this function, but doing so should not be needed.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
|
|
Writes object \var{obj} to file object \var{p}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
|
|
Writes string \var{s} to file object \var{p}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\subsection{CObjects}
|
|
|
|
XXX
|
|
|
|
|
|
\chapter{Initialization, Finalization, and Threads}
|
|
|
|
\begin{cfuncdesc}{void}{Py_Initialize}{}
|
|
Initialize the Python interpreter. In an application embedding
|
|
Python, this should be called before using any other Python/C API
|
|
functions; with the exception of \cfunction{Py_SetProgramName()},
|
|
\cfunction{PyEval_InitThreads()}, \cfunction{PyEval_ReleaseLock()},
|
|
and \cfunction{PyEval_AcquireLock()}. This initializes the table of
|
|
loaded modules (\code{sys.modules}), and creates the fundamental
|
|
modules \module{__builtin__}\refbimodindex{__builtin__},
|
|
\module{__main__}\refbimodindex{__main__} and
|
|
\module{sys}\refbimodindex{sys}. It also initializes the module
|
|
search path (\code{sys.path}).%
|
|
\indexiii{module}{search}{path}
|
|
It does not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for
|
|
that. This is a no-op when called for a second time (without calling
|
|
\cfunction{Py_Finalize()} first). There is no return value; it is a
|
|
fatal error if the initialization fails.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_IsInitialized}{}
|
|
Return true (nonzero) when the Python interpreter has been
|
|
initialized, false (zero) if not. After \cfunction{Py_Finalize()} is
|
|
called, this returns false until \cfunction{Py_Initialize()} is called
|
|
again.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_Finalize}{}
|
|
Undo all initializations made by \cfunction{Py_Initialize()} and
|
|
subsequent use of Python/C API functions, and destroy all
|
|
sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
|
|
created and not yet destroyed since the last call to
|
|
\cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
|
|
by the Python interpreter. This is a no-op when called for a second
|
|
time (without calling \cfunction{Py_Initialize()} again first). There
|
|
is no return value; errors during finalization are ignored.
|
|
|
|
This function is provided for a number of reasons. An embedding
|
|
application might want to restart Python without having to restart the
|
|
application itself. An application that has loaded the Python
|
|
interpreter from a dynamically loadable library (or DLL) might want to
|
|
free all memory allocated by Python before unloading the DLL. During a
|
|
hunt for memory leaks in an application a developer might want to free
|
|
all memory allocated by Python before exiting from the application.
|
|
|
|
\strong{Bugs and caveats:} The destruction of modules and objects in
|
|
modules is done in random order; this may cause destructors
|
|
(\method{__del__()} methods) to fail when they depend on other objects
|
|
(even functions) or modules. Dynamically loaded extension modules
|
|
loaded by Python are not unloaded. Small amounts of memory allocated
|
|
by the Python interpreter may not be freed (if you find a leak, please
|
|
report it). Memory tied up in circular references between objects is
|
|
not freed. Some memory allocated by extension modules may not be
|
|
freed. Some extension may not work properly if their initialization
|
|
routine is called more than once; this can happen if an applcation
|
|
calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
|
|
than once.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
|
|
Create a new sub-interpreter. This is an (almost) totally separate
|
|
environment for the execution of Python code. In particular, the new
|
|
interpreter has separate, independent versions of all imported
|
|
modules, including the fundamental modules
|
|
\module{__builtin__}\refbimodindex{__builtin__},
|
|
\module{__main__}\refbimodindex{__main__} and
|
|
\module{sys}\refbimodindex{sys}. The table of loaded modules
|
|
(\code{sys.modules}) and the module search path (\code{sys.path}) are
|
|
also separate. The new environment has no \code{sys.argv} variable.
|
|
It has new standard I/O stream file objects \code{sys.stdin},
|
|
\code{sys.stdout} and \code{sys.stderr} (however these refer to the
|
|
same underlying \code{FILE} structures in the \C{} library).
|
|
|
|
The return value points to the first thread state created in the new
|
|
sub-interpreter. This thread state is made the current thread state.
|
|
Note that no actual thread is created; see the discussion of thread
|
|
states below. If creation of the new interpreter is unsuccessful,
|
|
\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
|
|
thread state. (Like all other Python/C API functions, the global
|
|
interpreter lock must be held before calling this function and is
|
|
still held when it returns; however, unlike most other Python/C API
|
|
functions, there needn't be a current thread state on entry.)
|
|
|
|
Extension modules are shared between (sub-)interpreters as follows:
|
|
the first time a particular extension is imported, it is initialized
|
|
normally, and a (shallow) copy of its module's dictionary is
|
|
squirreled away. When the same extension is imported by another
|
|
(sub-)interpreter, a new module is initialized and filled with the
|
|
contents of this copy; the extension's \code{init} function is not
|
|
called. Note that this is different from what happens when an
|
|
extension is imported after the interpreter has been completely
|
|
re-initialized by calling \cfunction{Py_Finalize()} and
|
|
\cfunction{Py_Initialize()}; in that case, the extension's \code{init}
|
|
function \emph{is} called again.
|
|
|
|
\strong{Bugs and caveats:} Because sub-interpreters (and the main
|
|
interpreter) are part of the same process, the insulation between them
|
|
isn't perfect --- for example, using low-level file operations like
|
|
\code{os.close()} they can (accidentally or maliciously) affect each
|
|
other's open files. Because of the way extensions are shared between
|
|
(sub-)interpreters, some extensions may not work properly; this is
|
|
especially likely when the extension makes use of (static) global
|
|
variables, or when the extension manipulates its module's dictionary
|
|
after its initialization. It is possible to insert objects created in
|
|
one sub-interpreter into a namespace of another sub-interpreter; this
|
|
should be done with great care to avoid sharing user-defined
|
|
functions, methods, instances or classes between sub-interpreters,
|
|
since import operations executed by such objects may affect the
|
|
wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
|
|
a hard-to-fix bug that will be addressed in a future release.)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
|
|
Destroy the (sub-)interpreter represented by the given thread state.
|
|
The given thread state must be the current thread state. See the
|
|
discussion of thread states below. When the call returns, the current
|
|
thread state is \NULL{}. All thread states associated with this
|
|
interpreted are destroyed. (The global interpreter lock must be held
|
|
before calling this function and is still held when it returns.)
|
|
\cfunction{Py_Finalize()} will destroy all sub-interpreters that haven't
|
|
been explicitly destroyed at that point.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
|
|
This function should be called before \cfunction{Py_Initialize()} is called
|
|
for the first time, if it is called at all. It tells the interpreter
|
|
the value of the \code{argv[0]} argument to the \cfunction{main()} function
|
|
of the program. This is used by \cfunction{Py_GetPath()} and some other
|
|
functions below to find the Python run-time libraries relative to the
|
|
interpreter executable. The default value is \code{"python"}. The
|
|
argument should point to a zero-terminated character string in static
|
|
storage whose contents will not change for the duration of the
|
|
program's execution. No code in the Python interpreter will change
|
|
the contents of this storage.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
|
|
Return the program name set with \cfunction{Py_SetProgramName()}, or the
|
|
default. The returned string points into static storage; the caller
|
|
should not modify its value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
|
|
Return the \emph{prefix} for installed platform-independent files. This
|
|
is derived through a number of complicated rules from the program name
|
|
set with \cfunction{Py_SetProgramName()} and some environment variables;
|
|
for example, if the program name is \code{"/usr/local/bin/python"},
|
|
the prefix is \code{"/usr/local"}. The returned string points into
|
|
static storage; the caller should not modify its value. This
|
|
corresponds to the \code{prefix} variable in the top-level
|
|
\file{Makefile} and the \code{--prefix} argument to the
|
|
\program{configure} script at build time. The value is available to
|
|
Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
|
|
also the next function.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
|
|
Return the \emph{exec-prefix} for installed platform-\emph{de}pendent
|
|
files. This is derived through a number of complicated rules from the
|
|
program name set with \cfunction{Py_SetProgramName()} and some environment
|
|
variables; for example, if the program name is
|
|
\code{"/usr/local/bin/python"}, the exec-prefix is
|
|
\code{"/usr/local"}. The returned string points into static storage;
|
|
the caller should not modify its value. This corresponds to the
|
|
\code{exec_prefix} variable in the top-level \file{Makefile} and the
|
|
\code{--exec_prefix} argument to the \program{configure} script at build
|
|
time. The value is available to Python code as
|
|
\code{sys.exec_prefix}. It is only useful on \UNIX{}.
|
|
|
|
Background: The exec-prefix differs from the prefix when platform
|
|
dependent files (such as executables and shared libraries) are
|
|
installed in a different directory tree. In a typical installation,
|
|
platform dependent files may be installed in the
|
|
\code{"/usr/local/plat"} subtree while platform independent may be
|
|
installed in \code{"/usr/local"}.
|
|
|
|
Generally speaking, a platform is a combination of hardware and
|
|
software families, e.g. Sparc machines running the Solaris 2.x
|
|
operating system are considered the same platform, but Intel machines
|
|
running Solaris 2.x are another platform, and Intel machines running
|
|
Linux are yet another platform. Different major revisions of the same
|
|
operating system generally also form different platforms. Non-\UNIX{}
|
|
operating systems are a different story; the installation strategies
|
|
on those systems are so different that the prefix and exec-prefix are
|
|
meaningless, and set to the empty string. Note that compiled Python
|
|
bytecode files are platform independent (but not independent from the
|
|
Python version by which they were compiled!).
|
|
|
|
System administrators will know how to configure the \program{mount} or
|
|
\program{automount} programs to share \code{"/usr/local"} between platforms
|
|
while having \code{"/usr/local/plat"} be a different filesystem for each
|
|
platform.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
|
|
Return the full program name of the Python executable; this is
|
|
computed as a side-effect of deriving the default module search path
|
|
from the program name (set by \cfunction{Py_SetProgramName()} above). The
|
|
returned string points into static storage; the caller should not
|
|
modify its value. The value is available to Python code as
|
|
\code{sys.executable}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{char *}{Py_GetPath}{}
|
|
\indexiii{module}{search}{path}
|
|
Return the default module search path; this is computed from the
|
|
program name (set by \cfunction{Py_SetProgramName()} above) and some
|
|
environment variables. The returned string consists of a series of
|
|
directory names separated by a platform dependent delimiter character.
|
|
The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
|
|
DOS/Windows, and \code{'\\n'} (the \ASCII{} newline character) on
|
|
Macintosh. The returned string points into static storage; the caller
|
|
should not modify its value. The value is available to Python code
|
|
as the list \code{sys.path}, which may be modified to change the
|
|
future search path for loaded modules.
|
|
|
|
% XXX should give the exact rules
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
|
|
Return the version of this Python interpreter. This is a string that
|
|
looks something like
|
|
|
|
\begin{verbatim}
|
|
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
|
|
\end{verbatim}
|
|
|
|
The first word (up to the first space character) is the current Python
|
|
version; the first three characters are the major and minor version
|
|
separated by a period. The returned string points into static storage;
|
|
the caller should not modify its value. The value is available to
|
|
Python code as the list \code{sys.version}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
|
|
Return the platform identifier for the current platform. On \UNIX{},
|
|
this is formed from the ``official'' name of the operating system,
|
|
converted to lower case, followed by the major revision number; e.g.,
|
|
for Solaris 2.x, which is also known as SunOS 5.x, the value is
|
|
\code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
|
|
is \code{"win"}. The returned string points into static storage;
|
|
the caller should not modify its value. The value is available to
|
|
Python code as \code{sys.platform}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
|
|
Return the official copyright string for the current Python version,
|
|
for example
|
|
|
|
\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
|
|
|
|
The returned string points into static storage; the caller should not
|
|
modify its value. The value is available to Python code as the list
|
|
\code{sys.copyright}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
|
|
Return an indication of the compiler used to build the current Python
|
|
version, in square brackets, for example:
|
|
|
|
\begin{verbatim}
|
|
"[GCC 2.7.2.2]"
|
|
\end{verbatim}
|
|
|
|
The returned string points into static storage; the caller should not
|
|
modify its value. The value is available to Python code as part of
|
|
the variable \code{sys.version}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
|
|
Return information about the sequence number and build date and time
|
|
of the current Python interpreter instance, for example
|
|
|
|
\begin{verbatim}
|
|
"#67, Aug 1 1997, 22:34:28"
|
|
\end{verbatim}
|
|
|
|
The returned string points into static storage; the caller should not
|
|
modify its value. The value is available to Python code as part of
|
|
the variable \code{sys.version}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
|
|
% XXX
|
|
\end{cfuncdesc}
|
|
|
|
% XXX Other PySys thingies (doesn't really belong in this chapter)
|
|
|
|
\section{Thread State and the Global Interpreter Lock}
|
|
|
|
The Python interpreter is not fully thread safe. In order to support
|
|
multi-threaded Python programs, there's a global lock that must be
|
|
held by the current thread before it can safely access Python objects.
|
|
Without the lock, even the simplest operations could cause problems in
|
|
a multi-threaded program: for example, when two threads simultaneously
|
|
increment the reference count of the same object, the reference count
|
|
could end up being incremented only once instead of twice.
|
|
|
|
Therefore, the rule exists that only the thread that has acquired the
|
|
global interpreter lock may operate on Python objects or call Python/C
|
|
API functions. In order to support multi-threaded Python programs,
|
|
the interpreter regularly release and reacquires the lock --- by
|
|
default, every ten bytecode instructions (this can be changed with
|
|
\function{sys.setcheckinterval()}). The lock is also released and
|
|
reacquired around potentially blocking I/O operations like reading or
|
|
writing a file, so that other threads can run while the thread that
|
|
requests the I/O is waiting for the I/O operation to complete.
|
|
|
|
The Python interpreter needs to keep some bookkeeping information
|
|
separate per thread --- for this it uses a data structure called
|
|
\code{PyThreadState}. This is new in Python 1.5; in earlier versions,
|
|
such state was stored in global variables, and switching threads could
|
|
cause problems. In particular, exception handling is now thread safe,
|
|
when the application uses \function{sys.exc_info()} to access the
|
|
exception last raised in the current thread.
|
|
|
|
There's one global variable left, however: the pointer to the current
|
|
\code{PyThreadState} structure. While most thread packages have a way
|
|
to store ``per-thread global data,'' Python's internal platform
|
|
independent thread abstraction doesn't support this yet. Therefore,
|
|
the current thread state must be manipulated explicitly.
|
|
|
|
This is easy enough in most cases. Most code manipulating the global
|
|
interpreter lock has the following simple structure:
|
|
|
|
\begin{verbatim}
|
|
Save the thread state in a local variable.
|
|
Release the interpreter lock.
|
|
...Do some blocking I/O operation...
|
|
Reacquire the interpreter lock.
|
|
Restore the thread state from the local variable.
|
|
\end{verbatim}
|
|
|
|
This is so common that a pair of macros exists to simplify it:
|
|
|
|
\begin{verbatim}
|
|
Py_BEGIN_ALLOW_THREADS
|
|
...Do some blocking I/O operation...
|
|
Py_END_ALLOW_THREADS
|
|
\end{verbatim}
|
|
|
|
The \code{Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares
|
|
a hidden local variable; the \code{Py_END_ALLOW_THREADS} macro closes
|
|
the block. Another advantage of using these two macros is that when
|
|
Python is compiled without thread support, they are defined empty,
|
|
thus saving the thread state and lock manipulations.
|
|
|
|
When thread support is enabled, the block above expands to the
|
|
following code:
|
|
|
|
\begin{verbatim}
|
|
{
|
|
PyThreadState *_save;
|
|
_save = PyEval_SaveThread();
|
|
...Do some blocking I/O operation...
|
|
PyEval_RestoreThread(_save);
|
|
}
|
|
\end{verbatim}
|
|
|
|
Using even lower level primitives, we can get roughly the same effect
|
|
as follows:
|
|
|
|
\begin{verbatim}
|
|
{
|
|
PyThreadState *_save;
|
|
_save = PyThreadState_Swap(NULL);
|
|
PyEval_ReleaseLock();
|
|
...Do some blocking I/O operation...
|
|
PyEval_AcquireLock();
|
|
PyThreadState_Swap(_save);
|
|
}
|
|
\end{verbatim}
|
|
|
|
There are some subtle differences; in particular,
|
|
\cfunction{PyEval_RestoreThread()} saves and restores the value of the
|
|
global variable \code{errno}, since the lock manipulation does not
|
|
guarantee that \code{errno} is left alone. Also, when thread support
|
|
is disabled, \cfunction{PyEval_SaveThread()} and
|
|
\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
|
|
case, \cfunction{PyEval_ReleaseLock()} and
|
|
\cfunction{PyEval_AcquireLock()} are not available. This is done so
|
|
that dynamically loaded extensions compiled with thread support
|
|
enabled can be loaded by an interpreter that was compiled with
|
|
disabled thread support.
|
|
|
|
The global interpreter lock is used to protect the pointer to the
|
|
current thread state. When releasing the lock and saving the thread
|
|
state, the current thread state pointer must be retrieved before the
|
|
lock is released (since another thread could immediately acquire the
|
|
lock and store its own thread state in the global variable).
|
|
Reversely, when acquiring the lock and restoring the thread state, the
|
|
lock must be acquired before storing the thread state pointer.
|
|
|
|
Why am I going on with so much detail about this? Because when
|
|
threads are created from \C{}, they don't have the global interpreter
|
|
lock, nor is there a thread state data structure for them. Such
|
|
threads must bootstrap themselves into existence, by first creating a
|
|
thread state data structure, then acquiring the lock, and finally
|
|
storing their thread state pointer, before they can start using the
|
|
Python/C API. When they are done, they should reset the thread state
|
|
pointer, release the lock, and finally free their thread state data
|
|
structure.
|
|
|
|
When creating a thread data structure, you need to provide an
|
|
interpreter state data structure. The interpreter state data
|
|
structure hold global data that is shared by all threads in an
|
|
interpreter, for example the module administration
|
|
(\code{sys.modules}). Depending on your needs, you can either create
|
|
a new interpreter state data structure, or share the interpreter state
|
|
data structure used by the Python main thread (to access the latter,
|
|
you must obtain the thread state and access its \code{interp} member;
|
|
this must be done by a thread that is created by Python or by the main
|
|
thread after Python is initialized).
|
|
|
|
XXX More?
|
|
|
|
\begin{ctypedesc}{PyInterpreterState}
|
|
This data structure represents the state shared by a number of
|
|
cooperating threads. Threads belonging to the same interpreter
|
|
share their module administration and a few other internal items.
|
|
There are no public members in this structure.
|
|
|
|
Threads belonging to different interpreters initially share nothing,
|
|
except process state like available memory, open file descriptors and
|
|
such. The global interpreter lock is also shared by all threads,
|
|
regardless of to which interpreter they belong.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{PyThreadState}
|
|
This data structure represents the state of a single thread. The only
|
|
public data member is \code{PyInterpreterState *interp}, which points
|
|
to this thread's interpreter state.
|
|
\end{ctypedesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
|
|
Initialize and acquire the global interpreter lock. It should be
|
|
called in the main thread before creating a second thread or engaging
|
|
in any other thread operations such as
|
|
\cfunction{PyEval_ReleaseLock()} or
|
|
\code{PyEval_ReleaseThread(\var{tstate})}. It is not needed before
|
|
calling \cfunction{PyEval_SaveThread()} or
|
|
\cfunction{PyEval_RestoreThread()}.
|
|
|
|
This is a no-op when called for a second time. It is safe to call
|
|
this function before calling \cfunction{Py_Initialize()}.
|
|
|
|
When only the main thread exists, no lock operations are needed. This
|
|
is a common situation (most Python programs do not use threads), and
|
|
the lock operations slow the interpreter down a bit. Therefore, the
|
|
lock is not created initially. This situation is equivalent to having
|
|
acquired the lock: when there is only a single thread, all object
|
|
accesses are safe. Therefore, when this function initializes the
|
|
lock, it also acquires it. Before the Python
|
|
\module{thread}\refbimodindex{thread} module creates a new thread,
|
|
knowing that either it has the lock or the lock hasn't been created
|
|
yet, it calls \cfunction{PyEval_InitThreads()}. When this call
|
|
returns, it is guaranteed that the lock has been created and that it
|
|
has acquired it.
|
|
|
|
It is \strong{not} safe to call this function when it is unknown which
|
|
thread (if any) currently has the global interpreter lock.
|
|
|
|
This function is not available when thread support is disabled at
|
|
compile time.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
|
|
Acquire the global interpreter lock. The lock must have been created
|
|
earlier. If this thread already has the lock, a deadlock ensues.
|
|
This function is not available when thread support is disabled at
|
|
compile time.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
|
|
Release the global interpreter lock. The lock must have been created
|
|
earlier. This function is not available when thread support is
|
|
disabled at compile time.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
|
|
Acquire the global interpreter lock and then set the current thread
|
|
state to \var{tstate}, which should not be \NULL{}. The lock must
|
|
have been created earlier. If this thread already has the lock,
|
|
deadlock ensues. This function is not available when thread support
|
|
is disabled at compile time.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
|
|
Reset the current thread state to \NULL{} and release the global
|
|
interpreter lock. The lock must have been created earlier and must be
|
|
held by the current thread. The \var{tstate} argument, which must not
|
|
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 is not available when thread support is disabled at compile
|
|
time.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
|
|
Release the interpreter lock (if it has been created and thread
|
|
support is enabled) and reset the thread state to \NULL{},
|
|
returning the previous thread state (which is not \NULL{}). If
|
|
the lock has been created, the current thread must have acquired it.
|
|
(This function is available even when thread support is disabled at
|
|
compile time.)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
|
|
Acquire the interpreter lock (if it has been created and thread
|
|
support is enabled) and set the thread state to \var{tstate}, which
|
|
must not be \NULL{}. If the lock has been created, the current
|
|
thread must not have acquired it, otherwise deadlock ensues. (This
|
|
function is available even when thread support is disabled at compile
|
|
time.)
|
|
\end{cfuncdesc}
|
|
|
|
% XXX These aren't really C types, but the ctypedesc macro is the simplest!
|
|
\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
|
|
This macro expands to
|
|
\samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
|
|
Note that it contains an opening brace; it must be matched with a
|
|
following \code{Py_END_ALLOW_THREADS} macro. See above for further
|
|
discussion of this macro. It is a no-op when thread support is
|
|
disabled at compile time.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{Py_END_ALLOW_THREADS}
|
|
This macro expands to
|
|
\samp{PyEval_RestoreThread(_save); \}}.
|
|
Note that it contains a closing brace; it must be matched with an
|
|
earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
|
|
discussion of this macro. It is a no-op when thread support is
|
|
disabled at compile time.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
|
|
This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
|
|
is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
|
|
brace. It is a no-op when thread support is disabled at compile
|
|
time.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
|
|
This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
|
|
equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
|
|
and variable declaration. It is a no-op when thread support is
|
|
disabled at compile time.
|
|
\end{ctypedesc}
|
|
|
|
All of the following functions are only available when thread support
|
|
is enabled at compile time, and must be called only when the
|
|
interpreter lock has been created.
|
|
|
|
\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
|
|
Create a new interpreter state object. The interpreter lock must be
|
|
held.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
|
|
Reset all information in an interpreter state object. The interpreter
|
|
lock must be held.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
|
|
Destroy an interpreter state object. The interpreter lock need not be
|
|
held. The interpreter state must have been reset with a previous
|
|
call to \cfunction{PyInterpreterState_Clear()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
|
|
Create a new thread state object belonging to the given interpreter
|
|
object. The interpreter lock must be held.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
|
|
Reset all information in a thread state object. The interpreter lock
|
|
must be held.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
|
|
Destroy a thread state object. The interpreter lock need not be
|
|
held. The thread state must have been reset with a previous
|
|
call to \cfunction{PyThreadState_Clear()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
|
|
Return the current thread state. The interpreter lock must be held.
|
|
When the current thread state is \NULL{}, this issues a fatal
|
|
error (so that the caller needn't check for \NULL{}).
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
|
|
Swap the current thread state with the thread state given by the
|
|
argument \var{tstate}, which may be \NULL{}. The interpreter lock
|
|
must be held.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\chapter{Defining New Object Types}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
PyObject, PyVarObject
|
|
|
|
PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
|
|
|
|
Typedefs:
|
|
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
|
|
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
|
|
getreadbufferproc, getwritebufferproc, getsegcountproc,
|
|
destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
|
|
setattrofunc, cmpfunc, reprfunc, hashfunc
|
|
|
|
PyNumberMethods
|
|
|
|
PySequenceMethods
|
|
|
|
PyMappingMethods
|
|
|
|
PyBufferProcs
|
|
|
|
PyTypeObject
|
|
|
|
DL_IMPORT
|
|
|
|
PyType_Type
|
|
|
|
Py*_Check
|
|
|
|
Py_None, _Py_NoneStruct
|
|
|
|
|
|
\chapter{Debugging}
|
|
|
|
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
|
|
|
|
|
|
\input{api.ind} % Index -- must be last
|
|
|
|
\end{document}
|