mirror of https://github.com/python/cpython
2830 lines
108 KiB
TeX
2830 lines
108 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}
|
|
|
|
\pagestyle{empty}
|
|
\pagenumbering{roman}
|
|
|
|
\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
|
|
``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
|
|
|
|
\pagenumbering{arabic}
|
|
|
|
% 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 ``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 ``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 1.5 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:
|
|
|
|
\code{\#include "Python.h"}
|
|
|
|
This implies inclusion of the following standard header files:
|
|
stdio.h, string.h, errno.h, and stdlib.h (if available).
|
|
|
|
All user visible names defined by Python.h (except those defined by
|
|
the included standard headers) have one of the prefixes \code{Py} or
|
|
\code{_Py}. Names beginning with \code{_Py} are for internal use
|
|
only. Structure member names do not have a reserved prefix.
|
|
|
|
Important: user code should never define names that begin with
|
|
\code{Py} or \code{_Py}. This confuses the reader, and jeopardizes
|
|
the portability of the user code to future Python versions, which may
|
|
define additional names beginning with one of these prefixes.
|
|
|
|
\section{Objects, Types and Reference Counts}
|
|
|
|
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
|
|
(obviously!) 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 ``type'' and a
|
|
``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 Python Language Reference Manual). For
|
|
each of the well-known types there is a macro to check whether an
|
|
object is of that type; for instance, \code{PyList_Check(a)} is true
|
|
iff the object pointed to by \code{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 \code{Py_INCREF(a)} to increment an object's
|
|
reference count by one, and \code{Py_DECREF(a)} 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
|
|
oject'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
|
|
holding 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 \code{Py_DECREF()}, so
|
|
almost any operation is potentially dangerous.
|
|
|
|
A safe approach is to always use the generic operations (functions
|
|
whose name begins with \code{PyObject_}, \code{PyNumber_},
|
|
\code{PySequence_} or \code{PyMapping_}). These operations always
|
|
increment the reference count of the object they return. This leaves
|
|
the caller with the responsibility to call \code{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 \code{Py_DECREF()} or \code{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 \code{PyList_SetItem()} and
|
|
\code{PyTuple_SetItem()}, which steal a reference to the item (but not to
|
|
the tuple or list into which the item it put!). These functions were
|
|
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, \code{PyTuple_SetItem()} is the \emph{only} way to set
|
|
tuple items; \code{PySequence_SetItem()} and \code{PyObject_SetItem()}
|
|
refuse to do this since tuples are an immutable data type. You should
|
|
only use \code{PyTuple_SetItem()} for tuples that you are creating
|
|
yourself.
|
|
|
|
Equivalent code for populating a list can be written using
|
|
\code{PyList_New()} and \code{PyList_SetItem()}. Such code can also
|
|
use \code{PySequence_SetItem()}; this illustrates the difference
|
|
between the two (the extra \code{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,
|
|
\code{Py_BuildValue()}, that can create most common objects from \C{}
|
|
values, directed by a ``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 \code{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 \code{PyObject_GetItem()} and
|
|
\code{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{don't enter into it!} Thus, if you
|
|
extract an item from a list using \code{PyList_GetItem()}, you don't
|
|
own the reference -- but if you obtain the same item from the same
|
|
list using \code{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
|
|
\code{PyList_GetItem()}, once using \code{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
|
|
\code{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 \code{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: \code{PyErr_SetString()} is
|
|
the most common (though not the most general) function to set the
|
|
exception state, and \code{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
|
|
\code{try...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
|
|
\code{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 discards 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 reason about the exact cause of the error.
|
|
|
|
A simple example of detecting exceptions and passing them on is shown
|
|
in the \code{sum_sequence()} example above. It so happens that that
|
|
example doesn't need to clean up any owned references when it detects
|
|
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 \code{PyErr_ExceptionMatches()} and
|
|
\code{PyErr_Clear()} to handle specific exceptions, and the use of
|
|
\code{Py_XDECREF()} to dispose of owned references that may be
|
|
\NULL{} (note the `X' in the name; \code{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 \code{Py_Initialize()}. This
|
|
initializes the table of loaded modules, and creates the fundamental
|
|
modules \code{__builtin__}, \code{__main__} and \code{sys}. It also
|
|
initializes the module search path (\code{sys.path}).
|
|
|
|
\code{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 \code{Py_Initialize()}.
|
|
|
|
On most systems (in particular, on \UNIX{} and Windows, although the
|
|
details are slightly different), \code{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
|
|
\code{lib/python1.5} (replacing \code{1.5} with the current
|
|
interpreter version) relative to the parent directory where the
|
|
executable named \code{python} is found on the shell command search
|
|
path (the environment variable \code{\$PATH}).
|
|
|
|
For instance, if the Python executable is found in
|
|
\code{/usr/local/bin/python}, it will assume that the libraries are in
|
|
\code{/usr/local/lib/python1.5}. (In fact, this particular path is
|
|
also the ``fallback'' location, used when no executable file named
|
|
\code{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
|
|
\code{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 \code{Py_GetPath()},
|
|
\code{Py_GetPrefix()}, \code{Py_GetExecPrefix()},
|
|
\code{Py_GetProgramFullPath()} (all defined in
|
|
\file{Modules/getpath.c}).
|
|
|
|
Sometimes, it is desirable to ``uninitialize'' Python. For instance,
|
|
the application may want to start over (make another call to
|
|
\code{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 \code{Py_Finalize()}. The function
|
|
\code{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
|
|
\code{Py_XINCREF()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
|
|
Increment the reference count for object \code{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 \code{o}. The object must
|
|
not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
|
|
\code{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 \code{__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 \code{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 \code{Py_DECREF()} for the
|
|
temporary variable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
|
|
Decrement the reference count for object \code{o}.The object may be
|
|
\NULL{}, in which case the macro has no effect; otherwise the
|
|
effect is the same as for \code{Py_DECREF()}, and the same warning
|
|
applies.
|
|
\end{cfuncdesc}
|
|
|
|
The following functions or macros are only for internal use:
|
|
\code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_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 -1 if they return an integer
|
|
(exception: the \code{PyArg_Parse*()} functions return 1 for success and
|
|
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
|
|
\code{type} (the first argument to the last call to one of the
|
|
\code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not
|
|
set, return \NULL{}. You do not own a reference to the return value,
|
|
so you do not need to \code{Py_DECREF()} it. Note: do not compare the
|
|
return value to a specific exception; use
|
|
\code{PyErr_ExceptionMatches} instead, shown below.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
|
|
\strong{(NEW in 1.5a4!)}
|
|
Equivalent to
|
|
\code{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}
|
|
\strong{(NEW in 1.5a4!)}
|
|
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}
|
|
\strong{(NEW in 1.5a4!)}
|
|
Under certain circumstances, the values returned by
|
|
\code{PyErr_Fetch()} below can be ``unnormalized'', meaning that
|
|
\var{*exc} is a class object but \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 \code{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 \code{PyErr_SetString(\var{type}, Py_None}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
|
|
This is a shorthand for \code{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 \code{PyErr_SetNone(PyExc_MemoryError)}; it
|
|
returns \NULL{} so an object allocation function can write
|
|
\code{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 \code{strerror()}), and then calls
|
|
\code{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
|
|
the \code{errno} value is \code{EINTR}, indicating an interrupted
|
|
system call, this calls \code{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
|
|
\code{return PyErr_NoMemory();} when the system call returns an error.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
|
|
This is a shorthand for \code{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 \code{signal} module is
|
|
supported, this can invoke a signal handler written in Python. In all
|
|
cases, the default effect for \code{SIGINT} is to raise the
|
|
\code{KeyboadInterrupt} exception. If an exception is raised the
|
|
error indicator is set and the function returns 1; otherwise the
|
|
function returns 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 \code{SIGINT} signal arriving -- the next time
|
|
\code{PyErr_CheckSignals()} is called, \code{KeyboadInterrupt} will be
|
|
raised.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
|
|
PyObject *base, PyObject *dict}
|
|
\strong{(NEW in 1.5a4!)}
|
|
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
|
|
\code{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 \code{PyExc_} followed by the Python exception name.
|
|
These have the type \code{PyObject *}; they are all string objects.
|
|
For completeness, here are all the variables (the first four are new
|
|
in Python 1.5a4):
|
|
\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 \code{fp} with name
|
|
\code{filename} is deemed interactive. This is the case for files for
|
|
which \code{isatty(fileno(fp))} is true. If the global flag
|
|
\code{Py_InteractiveFlag} is true, this function also returns true if
|
|
the \code{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 \code{filename}.
|
|
The result is encoded in the same way as the timestamp returned by
|
|
the standard \C{} library function \code{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 \code{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 \code{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 \code{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}
|
|
\strong{(NEW in 1.5a4!)}
|
|
Import a module. This is best described by referring to the built-in
|
|
Python function \code{__import()__}, as the standard
|
|
\code{__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
|
|
\code{__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 \code{__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 \code{rexec} or \code{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 \code{reload()}, as the standard \code{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 \code{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. \code{.pyc}
|
|
and \code{.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 \code{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 \code{o}, on file \code{fp}. Returns -1 on error
|
|
The flags argument is used to enable certain printing
|
|
options. The only option currently supported is \code{Py_Print_RAW}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
|
|
Returns 1 if o has the attribute attr_name, and 0 otherwise.
|
|
This is equivalent to the Python expression:
|
|
\code{hasattr(o,attr_name)}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
|
|
Retrieve an attribute named attr_name from object o.
|
|
Returns the attribute value on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression: \code{o.attr_name}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
|
|
Returns 1 if o has the attribute attr_name, and 0 otherwise.
|
|
This is equivalent to the Python expression:
|
|
\code{hasattr(o,attr_name)}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
|
|
Retrieve an attribute named attr_name from object o.
|
|
Returns the attribute value on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression: o.attr_name.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
|
|
Set the value of the attribute named \code{attr_name}, for object \code{o},
|
|
to the value \code{v}. Returns -1 on failure. This is
|
|
the equivalent of the Python statement: \code{o.attr_name=v}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
|
|
Set the value of the attribute named \code{attr_name}, for
|
|
object \code{o},
|
|
to the value \code{v}. Returns -1 on failure. This is
|
|
the equivalent of the Python statement: \code{o.attr_name=v}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
|
|
Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
|
|
failure. This is the equivalent of the Python
|
|
statement: \code{del o.attr_name}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
|
|
Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
|
|
failure. This is the equivalent of the Python
|
|
statement: \code{del o.attr_name}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
|
|
Compare the values of \code{o1} and \code{o2} using a routine provided by
|
|
\code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
|
|
The result of the comparison is returned in \code{result}. Returns
|
|
-1 on failure. This is the equivalent of the Python
|
|
statement: \code{result=cmp(o1,o2)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
|
|
Compare the values of \code{o1} and \code{o2} using a routine provided by
|
|
\code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
|
|
Returns the result of the comparison on success. On error,
|
|
the value returned is undefined. This is equivalent to the
|
|
Python expression: \code{cmp(o1,o2)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
|
|
Compute the string representation of object, \code{o}. Returns the
|
|
string representation on success, \NULL{} on failure. This is
|
|
the equivalent of the Python expression: \code{repr(o)}.
|
|
Called by the \code{repr()} built-in function and by reverse quotes.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
|
|
Compute the string representation of object, \code{o}. Returns the
|
|
string representation on success, \NULL{} on failure. This is
|
|
the equivalent of the Python expression: \code{str(o)}.
|
|
Called by the \code{str()} built-in function and by the \code{print}
|
|
statement.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
|
|
Determine if the object \code{o}, is callable. Return 1 if the
|
|
object is callable and 0 otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
|
|
Call a callable Python object \code{callable_object}, with
|
|
arguments given by the tuple \code{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: \code{apply(o, args)}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
|
|
Call a callable Python object \code{callable_object}, with a
|
|
variable number of \C{} arguments. The \C{} arguments are described
|
|
using a mkvalue-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: \code{apply(o,args)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
|
|
Call the method named \code{m} of object \code{o} with a variable number of
|
|
C arguments. The \C{} arguments are described by a mkvalue
|
|
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: \code{o.method(args)}.
|
|
Note that Special method names, such as "\code{__add__}",
|
|
"\code{__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 \code{o}. On
|
|
failure, return -1. This is the equivalent of the Python
|
|
expression: \code{hash(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
|
|
Returns 1 if the object \code{o} is considered to be true, and
|
|
0 otherwise. This is equivalent to the Python expression:
|
|
\code{not not 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 \code{o}. On failure, returns \NULL{}. This is
|
|
equivalent to the Python expression: \code{type(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
|
|
Return the length of object \code{o}. If the object \code{o} provides
|
|
both sequence and mapping protocols, the sequence length is
|
|
returned. On error, -1 is returned. This is the equivalent
|
|
to the Python expression: \code{len(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
|
|
Return element of \code{o} corresponding to the object \code{key} or \NULL{}
|
|
on failure. This is the equivalent of the Python expression:
|
|
\code{o[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
|
|
Map the object \code{key} to the value \code{v}.
|
|
Returns -1 on failure. This is the equivalent
|
|
of the Python statement: \code{o[key]=v}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
|
|
Delete the mapping for \code{key} from \code{*o}. Returns -1
|
|
on failure.
|
|
This is the equivalent of the Python statement: \code{del o[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Number Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
|
|
Returns 1 if the object \code{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 \code{o1} and \code{o2}, or null on failure.
|
|
This is the equivalent of the Python expression: \code{o1+o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
|
|
Returns the result of subtracting \code{o2} from \code{o1}, or null on
|
|
failure. This is the equivalent of the Python expression:
|
|
\code{o1-o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
|
|
Returns the result of multiplying \code{o1} and \code{o2}, or null on
|
|
failure. This is the equivalent of the Python expression:
|
|
\code{o1*o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
|
|
Returns the result of dividing \code{o1} by \code{o2}, or null on failure.
|
|
This is the equivalent of the Python expression: \code{o1/o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
|
|
Returns the remainder of dividing \code{o1} by \code{o2}, or null on
|
|
failure. This is the equivalent of the Python expression:
|
|
\code{o1\%o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
|
|
See the built-in function divmod. Returns \NULL{} on failure.
|
|
This is the equivalent of the Python expression:
|
|
\code{divmod(o1,o2)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
|
|
See the built-in function pow. Returns \NULL{} on failure.
|
|
This is the equivalent of the Python expression:
|
|
\code{pow(o1,o2,o3)}, where \code{o3} is optional.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
|
|
Returns the negation of \code{o} on success, or null on failure.
|
|
This is the equivalent of the Python expression: \code{-o}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
|
|
Returns \code{o} on success, or \NULL{} on failure.
|
|
This is the equivalent of the Python expression: \code{+o}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
|
|
Returns the absolute value of \code{o}, or null on failure. This is
|
|
the equivalent of the Python expression: \code{abs(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
|
|
Returns the bitwise negation of \code{o} on success, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression:
|
|
\code{\~o}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
|
|
Returns the result of left shifting \code{o1} by \code{o2} on success, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{o1 << o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
|
|
Returns the result of right shifting \code{o1} by \code{o2} on success, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{o1 >> o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
|
|
Returns the result of "anding" \code{o2} and \code{o2} on success and \NULL{}
|
|
on failure. This is the equivalent of the Python
|
|
expression: \code{o1 and o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
|
|
Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{o1\^{ }o2}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
|
|
Returns the result of \code{o1} and \code{o2} on success, or \NULL{} on
|
|
failure. This is the equivalent of the Python expression:
|
|
\code{o1 or o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2}
|
|
This function takes the addresses of two variables of type
|
|
\code{PyObject*}.
|
|
|
|
If the objects pointed to by \code{*p1} and \code{*p2} have the same type,
|
|
increment their reference count and return 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 0.
|
|
If no conversion is possible, or if some other error occurs,
|
|
return -1 (failure) and don't increment the reference counts.
|
|
The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
|
|
statement \code{o1, o2 = coerce(o1, o2)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
|
|
Returns the \code{o} converted to an integer object on success, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{int(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
|
|
Returns the \code{o} converted to a long integer object on success,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{long(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
|
|
Returns the \code{o} converted to a float object on success, or \NULL{}
|
|
on failure. This is the equivalent of the Python expression:
|
|
\code{float(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Sequence Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
|
|
Return 1 if the object provides sequence protocol, and 0
|
|
otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
|
|
Return the concatenation of \code{o1} and \code{o2} on success, and \NULL{} on
|
|
failure. This is the equivalent of the Python
|
|
expression: \code{o1+o2}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
|
|
Return the result of repeating sequence object \code{o} \code{count} times,
|
|
or \NULL{} on failure. This is the equivalent of the Python
|
|
expression: \code{o*count}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
|
|
Return the ith element of \code{o}, or \NULL{} on failure. This is the
|
|
equivalent of the Python expression: \code{o[i]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
|
|
Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or
|
|
\NULL{} on failure. This is the equivalent of the Python
|
|
expression, \code{o[i1:i2]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
|
|
Assign object \code{v} to the \code{i}th element of \code{o}.
|
|
Returns -1 on failure. This is the equivalent of the Python
|
|
statement, \code{o[i]=v}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
|
|
Delete the \code{i}th element of object \code{v}. Returns
|
|
-1 on failure. This is the equivalent of the Python
|
|
statement: \code{del o[i]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
|
|
Assign the sequence object \code{v} to the slice in sequence
|
|
object \code{o} from \code{i1} to \code{i2}. This is the equivalent of the Python
|
|
statement, \code{o[i1:i2]=v}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
|
|
Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}.
|
|
Returns -1 on failure. This is the equivalent of the Python
|
|
statement: \code{del o[i1:i2]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
|
|
Returns the \code{o} as a tuple on success, and \NULL{} on failure.
|
|
This is equivalent to the Python expression: \code{tuple(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
|
|
Return the number of occurrences of \code{value} on \code{o}, that is,
|
|
return the number of keys for which \code{o[key]==value}. On
|
|
failure, return -1. This is equivalent to the Python
|
|
expression: \code{o.count(value)}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
|
|
Determine if \code{o} contains \code{value}. If an item in \code{o} is equal to
|
|
\code{value}, return 1, otherwise return 0. On error, return -1. This
|
|
is equivalent to the Python expression: \code{value in o}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
|
|
Return the first index for which \code{o[i]==value}. On error,
|
|
return -1. This is equivalent to the Python
|
|
expression: \code{o.index(value)}.
|
|
\end{cfuncdesc}
|
|
|
|
\section{Mapping Protocol}
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
|
|
Return 1 if the object provides mapping protocol, and 0
|
|
otherwise.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
|
|
Returns the number of keys in object \code{o} on success, and -1 on
|
|
failure. For objects that do not provide sequence protocol,
|
|
this is equivalent to the Python expression: \code{len(o)}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
|
|
Remove the mapping for object \code{key} from the object \code{o}.
|
|
Return -1 on failure. This is equivalent to
|
|
the Python statement: \code{del o[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
|
|
Remove the mapping for object \code{key} from the object \code{o}.
|
|
Return -1 on failure. This is equivalent to
|
|
the Python statement: \code{del o[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
|
|
On success, return 1 if the mapping object has the key \code{key}
|
|
and 0 otherwise. This is equivalent to the Python expression:
|
|
\code{o.has_key(key)}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
|
|
Return 1 if the mapping object has the key \code{key}
|
|
and 0 otherwise. This is equivalent to the Python expression:
|
|
\code{o.has_key(key)}.
|
|
This function always succeeds.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
|
|
On success, return a list of the keys in object \code{o}. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression: \code{o.keys()}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
|
|
On success, return a list of the values in object \code{o}. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression: \code{o.values()}.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
|
|
On success, return a list of the items in object \code{o}, where
|
|
each item is a tuple containing a key-value pair. On
|
|
failure, return \NULL{}. This is equivalent to the Python
|
|
expression: \code{o.items()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
|
|
Make object \code{o} empty. Returns 1 on success and 0 on failure.
|
|
This is equivalent to the Python statement:
|
|
\code{for key in o.keys(): del o[key]}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
|
|
Return element of \code{o} corresponding to the object \code{key} or \NULL{}
|
|
on failure. This is the equivalent of the Python expression:
|
|
\code{o[key]}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
|
|
Map the object \code{key} to the value \code{v} in object \code{o}. Returns
|
|
-1 on failure. This is the equivalent of the Python
|
|
statement: \code{o[key]=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 \code{file_name}, with a file mode given by \code{mode},
|
|
where \code{mode} has the same semantics as the standard \C{} routine,
|
|
fopen. On failure, return -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, \code{fp}. A file name, \code{file_name}, and open mode,
|
|
\code{mode}, must be provided as well as a flag, \code{close_on_del}, that
|
|
indicates whether the file is to be closed when the file
|
|
object is destroyed. On failure, return -1.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
|
|
Returns a new float object with the value \code{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
|
|
Returns a new int object with the value \code{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyList_New}{int l}
|
|
Returns a new list of length \code{l} on success, and \NULL{} on
|
|
failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
|
|
Returns a new long object with the value \code{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
|
|
Returns a new long object with the value \code{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 \code{v} on success, and
|
|
\NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l}
|
|
Returns a new string object with the value \code{v} and length \code{l}
|
|
on success, and \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l}
|
|
Returns a new tuple of length \code{l} 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 \code{s}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
|
|
akes 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 \code{pos} in the tuple pointed
|
|
to by \code{p}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
|
|
does the same, but does no checking of it's
|
|
arguments.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
|
|
int low,
|
|
int high}
|
|
takes a slice of the tuple pointed to by \code{p} from
|
|
\code{low} to \code{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 \code{o} at position \code{pos} of
|
|
the tuple pointed to by \code{p}. It returns 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. \code{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 it's 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 it's argument is a 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 and deletes it.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
|
|
PyObject *key,
|
|
PyObject *val}
|
|
inserts \code{value} into the dictionary with a key of
|
|
\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
|
|
be hashable.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
|
|
char *key,
|
|
PyObject *val}
|
|
inserts \code{value} into the dictionary using \code{key}
|
|
as a key. \code{key} should be a char *
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
|
|
removes the entry in dictionary \code{p} with key \code{key}.
|
|
\code{key} is a PyObject.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
|
|
removes the entry in dictionary \code{p} which has a key
|
|
specified by the \code{char *}\code{key}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
|
|
returns the object from dictionary \code{p} which has a key
|
|
\code{key}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
|
|
does the same, but \code{key} is specified as a
|
|
\code{char *}, rather than a \code{PyObject *}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
|
|
returns a PyListObject containing all the items
|
|
from the dictionary, as in the mapping method \code{items()} (see the Reference
|
|
Guide)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
|
|
returns a PyListObject containing all the keys
|
|
from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
|
|
returns a PyListObject containing all the values
|
|
from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
|
|
\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 \code{ival}.
|
|
|
|
The current implementation keeps an array of integer objects for all
|
|
integers between -1 and 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 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 \code{io}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
|
|
will first attempt to cast the object to a PyIntObject, if
|
|
it is not already one, and the return it's value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{long}{PyInt_GetMax}{}
|
|
returns the systems idea of the largest int it can handle
|
|
(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 it's 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 it's 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}
|
|
typedef struct {
|
|
double real;
|
|
double imag;
|
|
}
|
|
\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 it's 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 it's argument is a \code{PyFileObject}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
|
|
creates a new PyFileObject pointing to the file
|
|
specified in \code{name} with the mode specified in \code{mode}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
|
|
char *name, char *mode, int (*close})
|
|
creates a new PyFileObject from the already-open \code{fp}.
|
|
The function \code{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 \code{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 \code{p} as a
|
|
PyStringObject
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
|
|
on systems with \code{setvbuf} only
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
|
|
same as the file object method \code{softspace}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
|
|
writes object \code{obj} to file object \code{p}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
|
|
writes string \code{s} to file object \code{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 \code{Py_SetProgramName()},
|
|
\code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
|
|
\code{PyEval_AcquireLock()}. This initializes the table of loaded
|
|
modules (\code{sys.modules}), and creates the fundamental modules
|
|
\code{__builtin__}, \code{__main__} and \code{sys}. It also
|
|
initializes the module search path (\code{sys.path}). It does not set
|
|
\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
|
|
when called for a second time (without calling \code{Py_Finalize()}
|
|
first). There is no return value; it is a fatal error if the
|
|
initialization fails.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{int}{Py_IsInitialized}{}
|
|
\strong{(NEW in 1.5a4!)}
|
|
Return true (nonzero) when the Python interpreter has been
|
|
initialized, false (zero) if not. After \code{Py_Finalize()} is
|
|
called, this returns false until \code{Py_Initialize()} is called
|
|
again.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{Py_Finalize}{}
|
|
\strong{(NEW in 1.5a3!)}
|
|
Undo all initializations made by \code{Py_Initialize()} and subsequent
|
|
use of Python/C API functions, and destroy all sub-interpreters (see
|
|
\code{Py_NewInterpreter()} below) that were created and not yet
|
|
destroyed since the last call to \code{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
|
|
\code{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.
|
|
|
|
\emph{Bugs and caveats:} The destruction of modules and objects in
|
|
modules is done in random order; this may cause destructors
|
|
(\code{__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 \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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 \code{__builtin__},
|
|
\code{__main__} and \code{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 as
|
|
extension is imported after the interpreter has been completely
|
|
re-initialized by calling \code{Py_Finalize()} and
|
|
\code{Py_Initialize()}; in that case, the extension's \code{init}
|
|
function \emph{is} called again.
|
|
|
|
\emph{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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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.)
|
|
\code{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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
This function should be called before \code{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 \code{main()} function
|
|
of the program. This is used by \code{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 \code{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 ``prefix'' for installed platform-independent files. This
|
|
is derived through a number of complicated rules from the program name
|
|
set with \code{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
|
|
\code{Makefile} and the \code{--prefix} argument to the
|
|
\code{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 ``exec-prefix'' for installed platform-\emph{de}pendent
|
|
files. This is derived through a number of complicated rules from the
|
|
program name set with \code{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 \code{Makefile} and the
|
|
\code{--exec_prefix} argument to the \code{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 \code{mount} or
|
|
\code{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}{}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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 \code{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}{}
|
|
Return the default module search path; this is computed from the
|
|
program name (set by \code{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.5a3 (#67, Aug 1 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
|
|
|
|
\code{"[GCC 2.7.2.2]"}
|
|
|
|
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 proram: 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
|
|
\code{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
|
|
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 \code{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
|
|
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 BEGIN macro opens a new block and declares a hidden local
|
|
variable; the END 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,
|
|
\code{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, \code{PyEval_SaveThread()} and
|
|
\code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
|
|
\code{PyEval_ReleaseLock()} and \code{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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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 \code{PyEval_ReleaseLock()} or
|
|
\code{PyEval_ReleaseThread(tstate)}. It is not needed before
|
|
calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
|
|
|
|
This is a no-op when called for a second time. It is safe to call
|
|
this function before calling \code{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 \code{thread} module
|
|
creates a new thread, knowing that either it has the lock or the lock
|
|
hasn't been created yet, it calls \code{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}{}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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}{}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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}
|
|
\strong{(NEW in 1.5a3!)}
|
|
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}{}
|
|
\strong{(Different return type in 1.5a3!)}
|
|
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}
|
|
\strong{(Different argument type in 1.5a3!)}
|
|
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
|
|
\code{\{ 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
|
|
\code{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 \code{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 \code{_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. They are all new in 1.5a3.
|
|
|
|
\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 \code{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 \code{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}
|
|
|
|
|
|
\section{Defining New Object Types}
|
|
|
|
XXX To be done:
|
|
|
|
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
|
|
|
|
_PyObject_New, _PyObject_NewVar
|
|
|
|
PyObject_NEW, PyObject_NEW_VAR
|
|
|
|
|
|
\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}
|
|
|
|
|
|
\chapter{Debugging}
|
|
|
|
XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
|
|
|
|
|
|
\input{api.ind} % Index -- must be last
|
|
|
|
\end{document}
|