blob: e5464463750ba49c4827876fe57e920ae23a9e51 [file] [log] [blame]
Fred Drakedca87921998-01-13 16:53:23 +00001\documentclass[twoside,openright]{report}
Fred Drake1f8449a1998-01-09 05:36:43 +00002\usepackage{myformat}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00003
Guido van Rossum9faf4c51997-10-07 14:38:54 +00004\title{Python/C API Reference Manual}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00005
6\input{boilerplate}
7
8\makeindex % tell \index to actually write the .idx file
9
10
11\begin{document}
12
Guido van Rossum9231c8f1997-05-15 21:43:21 +000013\maketitle
14
15\input{copyright}
16
17\begin{abstract}
18
19\noindent
Fred Drakee058b4f1998-02-16 06:15:35 +000020This manual documents the API used by \C{} (or \Cpp{}) programmers who
21want to write extension modules or embed Python. It is a companion to
22\emph{Extending and Embedding the Python Interpreter}, which describes
Guido van Rossum9231c8f1997-05-15 21:43:21 +000023the general principles of extension writing but does not document the
24API functions in detail.
25
Guido van Rossum5b8a5231997-12-30 04:38:44 +000026\strong{Warning:} The current version of this document is incomplete.
27I hope that it is nevertheless useful. I will continue to work on it,
28and release new versions from time to time, independent from Python
29source code releases.
30
Guido van Rossum9231c8f1997-05-15 21:43:21 +000031\end{abstract}
32
Fred Drake4d4f9e71998-01-13 22:25:02 +000033\tableofcontents
Guido van Rossum9231c8f1997-05-15 21:43:21 +000034
Guido van Rossum5060b3b1997-08-17 18:02:23 +000035% XXX Consider moving all this back to ext.tex and giving api.tex
36% XXX a *really* short intro only.
Guido van Rossum9231c8f1997-05-15 21:43:21 +000037
38\chapter{Introduction}
39
Fred Drakeb0a78731998-01-13 18:51:10 +000040The Application Programmer's Interface to Python gives \C{} and \Cpp{}
Guido van Rossum59a61351997-08-14 20:34:33 +000041programmers access to the Python interpreter at a variety of levels.
Fred Drakeb0a78731998-01-13 18:51:10 +000042The API is equally usable from \Cpp{}, but for brevity it is generally
43referred to as the Python/\C{} API. There are two fundamentally
Fred Drakee058b4f1998-02-16 06:15:35 +000044different reasons for using the Python/\C{} API. The first reason is
45to write \emph{extension modules} for specific purposes; these are
46\C{} modules that extend the Python interpreter. This is probably the
47most common use. The second reason is to use Python as a component in
48a larger application; this technique is generally referred to as
49\dfn{embedding} Python in an application.
Guido van Rossum59a61351997-08-14 20:34:33 +000050
Guido van Rossum4a944d71997-08-14 20:35:38 +000051Writing an extension module is a relatively well-understood process,
52where a ``cookbook'' approach works well. There are several tools
53that automate the process to some extent. While people have embedded
54Python in other applications since its early existence, the process of
55embedding Python is less straightforward that writing an extension.
56Python 1.5 introduces a number of new API functions as well as some
57changes to the build process that make embedding much simpler.
Fred Drakee058b4f1998-02-16 06:15:35 +000058This manual describes the \version\ state of affair.
Guido van Rossum59a61351997-08-14 20:34:33 +000059% XXX Eventually, take the historical notes out
60
Guido van Rossum4a944d71997-08-14 20:35:38 +000061Many API functions are useful independent of whether you're embedding
62or extending Python; moreover, most applications that embed Python
63will need to provide a custom extension as well, so it's probably a
64good idea to become familiar with writing an extension before
Guido van Rossum59a61351997-08-14 20:34:33 +000065attempting to embed Python in a real application.
66
Guido van Rossum580aa8d1997-11-25 15:34:51 +000067\section{Include Files}
68
69All function, type and macro definitions needed to use the Python/C
70API are included in your code by the following line:
71
Fred Drakee058b4f1998-02-16 06:15:35 +000072\begin{verbatim}
73#include "Python.h"
74\end{verbatim}
Guido van Rossum580aa8d1997-11-25 15:34:51 +000075
Fred Drakee058b4f1998-02-16 06:15:35 +000076This implies inclusion of the following standard headers:
77\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
78\code{<stdlib.h>} (if available).
Guido van Rossum580aa8d1997-11-25 15:34:51 +000079
80All user visible names defined by Python.h (except those defined by
Fred Drakee058b4f1998-02-16 06:15:35 +000081the included standard headers) have one of the prefixes \samp{Py} or
82\samp{_Py}. Names beginning with \samp{_Py} are for internal use
Guido van Rossum580aa8d1997-11-25 15:34:51 +000083only. Structure member names do not have a reserved prefix.
84
Fred Drakee058b4f1998-02-16 06:15:35 +000085\strong{Important:} user code should never define names that begin
86with \samp{Py} or \samp{_Py}. This confuses the reader, and
87jeopardizes the portability of the user code to future Python
88versions, which may define additional names beginning with one of
89these prefixes.
Guido van Rossum580aa8d1997-11-25 15:34:51 +000090
Guido van Rossum59a61351997-08-14 20:34:33 +000091\section{Objects, Types and Reference Counts}
92
Guido van Rossum580aa8d1997-11-25 15:34:51 +000093Most Python/C API functions have one or more arguments as well as a
94return value of type \code{PyObject *}. This type is a pointer
Fred Drakee058b4f1998-02-16 06:15:35 +000095to an opaque data type representing an arbitrary Python
Guido van Rossum580aa8d1997-11-25 15:34:51 +000096object. Since all Python object types are treated the same way by the
97Python language in most situations (e.g., assignments, scope rules,
98and argument passing), it is only fitting that they should be
Fred Drakeb0a78731998-01-13 18:51:10 +000099represented by a single \C{} type. All Python objects live on the heap:
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000100you never declare an automatic or static variable of type
Guido van Rossum4a944d71997-08-14 20:35:38 +0000101\code{PyObject}, only pointer variables of type \code{PyObject *} can
Guido van Rossum59a61351997-08-14 20:34:33 +0000102be declared.
103
Fred Drakee058b4f1998-02-16 06:15:35 +0000104All Python objects (even Python integers) have a \dfn{type} and a
105\dfn{reference count}. An object's type determines what kind of object
Guido van Rossum4a944d71997-08-14 20:35:38 +0000106it is (e.g., an integer, a list, or a user-defined function; there are
Fred Drakee058b4f1998-02-16 06:15:35 +0000107many more as explained in the \emph{Python Reference Manual}). For
Guido van Rossum4a944d71997-08-14 20:35:38 +0000108each of the well-known types there is a macro to check whether an
Fred Drakee058b4f1998-02-16 06:15:35 +0000109object is of that type; for instance, \samp{PyList_Check(\var{a})} is
110true iff the object pointed to by \var{a} is a Python list.
Guido van Rossum59a61351997-08-14 20:34:33 +0000111
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000112\subsection{Reference Counts}
113
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000114The reference count is important because today's computers have a
Guido van Rossum4a944d71997-08-14 20:35:38 +0000115finite (and often severly limited) memory size; it counts how many
116different places there are that have a reference to an object. Such a
Fred Drakeb0a78731998-01-13 18:51:10 +0000117place could be another object, or a global (or static) \C{} variable, or
118a local variable in some \C{} function. When an object's reference count
Guido van Rossum4a944d71997-08-14 20:35:38 +0000119becomes zero, the object is deallocated. If it contains references to
120other objects, their reference count is decremented. Those other
121objects may be deallocated in turn, if this decrement makes their
122reference count become zero, and so on. (There's an obvious problem
123with objects that reference each other here; for now, the solution is
Guido van Rossum59a61351997-08-14 20:34:33 +0000124``don't do that''.)
125
Guido van Rossum4a944d71997-08-14 20:35:38 +0000126Reference counts are always manipulated explicitly. The normal way is
Fred Drakee058b4f1998-02-16 06:15:35 +0000127to use the macro \cfunction{Py_INCREF()} to increment an object's
128reference count by one, and \cfunction{Py_DECREF()} to decrement it by
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000129one. The decref macro is considerably more complex than the incref one,
Guido van Rossum4a944d71997-08-14 20:35:38 +0000130since it must check whether the reference count becomes zero and then
131cause the object's deallocator, which is a function pointer contained
132in the object's type structure. The type-specific deallocator takes
133care of decrementing the reference counts for other objects contained
134in the object, and so on, if this is a compound object type such as a
135list. There's no chance that the reference count can overflow; at
136least as many bits are used to hold the reference count as there are
137distinct memory locations in virtual memory (assuming
138\code{sizeof(long) >= sizeof(char *)}). Thus, the reference count
Guido van Rossum59a61351997-08-14 20:34:33 +0000139increment is a simple operation.
140
Guido van Rossum4a944d71997-08-14 20:35:38 +0000141It is not necessary to increment an object's reference count for every
142local variable that contains a pointer to an object. In theory, the
Fred Drakee058b4f1998-02-16 06:15:35 +0000143object's reference count goes up by one when the variable is made to
Guido van Rossum4a944d71997-08-14 20:35:38 +0000144point to it and it goes down by one when the variable goes out of
145scope. However, these two cancel each other out, so at the end the
146reference count hasn't changed. The only real reason to use the
147reference count is to prevent the object from being deallocated as
148long as our variable is pointing to it. If we know that there is at
149least one other reference to the object that lives at least as long as
150our variable, there is no need to increment the reference count
151temporarily. An important situation where this arises is in objects
Fred Drakeb0a78731998-01-13 18:51:10 +0000152that are passed as arguments to \C{} functions in an extension module
Guido van Rossum4a944d71997-08-14 20:35:38 +0000153that are called from Python; the call mechanism guarantees to hold a
Guido van Rossum59a61351997-08-14 20:34:33 +0000154reference to every argument for the duration of the call.
155
Fred Drakee058b4f1998-02-16 06:15:35 +0000156However, a common pitfall is to extract an object from a list and
157hold on to it for a while without incrementing its reference count.
158Some other operation might conceivably remove the object from the
159list, decrementing its reference count and possible deallocating it.
160The real danger is that innocent-looking operations may invoke
161arbitrary Python code which could do this; there is a code path which
162allows control to flow back to the user from a \cfunction{Py_DECREF()},
163so almost any operation is potentially dangerous.
Guido van Rossum59a61351997-08-14 20:34:33 +0000164
Guido van Rossum4a944d71997-08-14 20:35:38 +0000165A safe approach is to always use the generic operations (functions
Fred Drakee058b4f1998-02-16 06:15:35 +0000166whose name begins with \samp{PyObject_}, \samp{PyNumber_},
167\samp{PySequence_} or \samp{PyMapping_}). These operations always
Guido van Rossum4a944d71997-08-14 20:35:38 +0000168increment the reference count of the object they return. This leaves
Fred Drakee058b4f1998-02-16 06:15:35 +0000169the caller with the responsibility to call \cfunction{Py_DECREF()}
170when they are done with the result; this soon becomes second nature.
Guido van Rossum59a61351997-08-14 20:34:33 +0000171
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000172\subsubsection{Reference Count Details}
173
174The reference count behavior of functions in the Python/C API is best
175expelained in terms of \emph{ownership of references}. Note that we
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000176talk of owning references, never of owning objects; objects are always
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000177shared! When a function owns a reference, it has to dispose of it
Fred Drakee058b4f1998-02-16 06:15:35 +0000178properly --- either by passing ownership on (usually to its caller) or
179by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
180a function passes ownership of a reference on to its caller, the
181caller is said to receive a \emph{new} reference. When no ownership
182is transferred, the caller is said to \emph{borrow} the reference.
183Nothing needs to be done for a borrowed reference.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000184
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000185Conversely, when calling a function passes it a reference to an
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000186object, there are two possibilities: the function \emph{steals} a
187reference to the object, or it does not. Few functions steal
Fred Drakee058b4f1998-02-16 06:15:35 +0000188references; the two notable exceptions are
189\cfunction{PyList_SetItem()} and \cfunction{PyTuple_SetItem()}, which
190steal a reference to the item (but not to the tuple or list into which
191the item it put!). These functions were designed to steal a reference
192because of a common idiom for populating a tuple or list with newly
193created objects; for example, the code to create the tuple \code{(1,
1942, "three")} could look like this (forgetting about error handling for
195the moment; a better way to code this is shown below anyway):
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000196
197\begin{verbatim}
198PyObject *t;
199t = PyTuple_New(3);
200PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
201PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
202PyTuple_SetItem(t, 2, PyString_FromString("three"));
203\end{verbatim}
204
Fred Drakee058b4f1998-02-16 06:15:35 +0000205Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
206set tuple items; \cfunction{PySequence_SetItem()} and
207\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
208immutable data type. You should only use
209\cfunction{PyTuple_SetItem()} for tuples that you are creating
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000210yourself.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000211
212Equivalent code for populating a list can be written using
Fred Drakee058b4f1998-02-16 06:15:35 +0000213\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
214can also use \cfunction{PySequence_SetItem()}; this illustrates the
215difference between the two (the extra \cfunction{Py_DECREF()} calls):
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000216
217\begin{verbatim}
218PyObject *l, *x;
219l = PyList_New(3);
220x = PyInt_FromLong(1L);
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000221PySequence_SetItem(l, 0, x); Py_DECREF(x);
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000222x = PyInt_FromLong(2L);
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000223PySequence_SetItem(l, 1, x); Py_DECREF(x);
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000224x = PyString_FromString("three");
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000225PySequence_SetItem(l, 2, x); Py_DECREF(x);
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000226\end{verbatim}
227
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000228You might find it strange that the ``recommended'' approach takes more
229code. However, in practice, you will rarely use these ways of
230creating and populating a tuple or list. There's a generic function,
Fred Drakee058b4f1998-02-16 06:15:35 +0000231\cfunction{Py_BuildValue()}, that can create most common objects from
232\C{} values, directed by a \dfn{format string}. For example, the
233above two blocks of code could be replaced by the following (which
234also takes care of the error checking):
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000235
236\begin{verbatim}
237PyObject *t, *l;
238t = Py_BuildValue("(iis)", 1, 2, "three");
239l = Py_BuildValue("[iis]", 1, 2, "three");
240\end{verbatim}
241
Fred Drakee058b4f1998-02-16 06:15:35 +0000242It is much more common to use \cfunction{PyObject_SetItem()} and
243friends with items whose references you are only borrowing, like
244arguments that were passed in to the function you are writing. In
245that case, their behaviour regarding reference counts is much saner,
246since you don't have to increment a reference count so you can give a
247reference away (``have it be stolen''). For example, this function
248sets all items of a list (actually, any mutable sequence) to a given
249item:
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000250
251\begin{verbatim}
252int set_all(PyObject *target, PyObject *item)
253{
254 int i, n;
255 n = PyObject_Length(target);
256 if (n < 0)
257 return -1;
258 for (i = 0; i < n; i++) {
259 if (PyObject_SetItem(target, i, item) < 0)
260 return -1;
261 }
262 return 0;
263}
264\end{verbatim}
265
266The situation is slightly different for function return values.
267While passing a reference to most functions does not change your
268ownership responsibilities for that reference, many functions that
269return a referece to an object give you ownership of the reference.
270The reason is simple: in many cases, the returned object is created
271on the fly, and the reference you get is the only reference to the
Fred Drakee058b4f1998-02-16 06:15:35 +0000272object. Therefore, the generic functions that return object
273references, like \cfunction{PyObject_GetItem()} and
274\cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
275the caller becomes the owner of the reference).
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000276
277It is important to realize that whether you own a reference returned
Fred Drakee058b4f1998-02-16 06:15:35 +0000278by a function depends on which function you call only --- \emph{the
279plumage} (i.e., the type of the type of the object passed as an
280argument to the function) \emph{doesn't enter into it!} Thus, if you
281extract an item from a list using \cfunction{PyList_GetItem()}, you
282don't own the reference --- but if you obtain the same item from the
283same list using \cfunction{PySequence_GetItem()} (which happens to
284take exactly the same arguments), you do own a reference to the
285returned object.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000286
Fred Drakee058b4f1998-02-16 06:15:35 +0000287Here is an example of how you could write a function that computes the
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000288sum of the items in a list of integers; once using
Fred Drakee058b4f1998-02-16 06:15:35 +0000289\cfunction{PyList_GetItem()}, once using
290\cfunction{PySequence_GetItem()}.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000291
292\begin{verbatim}
293long sum_list(PyObject *list)
294{
295 int i, n;
296 long total = 0;
297 PyObject *item;
298 n = PyList_Size(list);
299 if (n < 0)
300 return -1; /* Not a list */
301 for (i = 0; i < n; i++) {
302 item = PyList_GetItem(list, i); /* Can't fail */
303 if (!PyInt_Check(item)) continue; /* Skip non-integers */
304 total += PyInt_AsLong(item);
305 }
306 return total;
307}
308\end{verbatim}
309
310\begin{verbatim}
311long sum_sequence(PyObject *sequence)
312{
313 int i, n;
314 long total = 0;
315 PyObject *item;
316 n = PyObject_Size(list);
317 if (n < 0)
318 return -1; /* Has no length */
319 for (i = 0; i < n; i++) {
320 item = PySequence_GetItem(list, i);
321 if (item == NULL)
322 return -1; /* Not a sequence, or other failure */
323 if (PyInt_Check(item))
324 total += PyInt_AsLong(item);
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000325 Py_DECREF(item); /* Discard reference ownership */
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000326 }
327 return total;
328}
329\end{verbatim}
330
331\subsection{Types}
332
333There are few other data types that play a significant role in
Fred Drakeb0a78731998-01-13 18:51:10 +0000334the Python/C API; most are simple \C{} types such as \code{int},
Guido van Rossum4a944d71997-08-14 20:35:38 +0000335\code{long}, \code{double} and \code{char *}. A few structure types
336are used to describe static tables used to list the functions exported
337by a module or the data attributes of a new object type. These will
Guido van Rossum59a61351997-08-14 20:34:33 +0000338be discussed together with the functions that use them.
339
340\section{Exceptions}
341
Guido van Rossum4a944d71997-08-14 20:35:38 +0000342The Python programmer only needs to deal with exceptions if specific
343error handling is required; unhandled exceptions are automatically
344propagated to the caller, then to the caller's caller, and so on, till
345they reach the top-level interpreter, where they are reported to the
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000346user accompanied by a stack traceback.
Guido van Rossum59a61351997-08-14 20:34:33 +0000347
Fred Drakeb0a78731998-01-13 18:51:10 +0000348For \C{} programmers, however, error checking always has to be explicit.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000349All functions in the Python/C API can raise exceptions, unless an
350explicit claim is made otherwise in a function's documentation. In
351general, when a function encounters an error, it sets an exception,
352discards any object references that it owns, and returns an
Fred Drakee058b4f1998-02-16 06:15:35 +0000353error indicator --- usually \NULL{} or \code{-1}. A few functions
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000354return a Boolean true/false result, with false indicating an error.
355Very few functions return no explicit error indicator or have an
356ambiguous return value, and require explicit testing for errors with
Fred Drakee058b4f1998-02-16 06:15:35 +0000357\cfunction{PyErr_Occurred()}.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000358
359Exception state is maintained in per-thread storage (this is
360equivalent to using global storage in an unthreaded application). A
Fred Drakee058b4f1998-02-16 06:15:35 +0000361thread can be on one of two states: an exception has occurred, or not.
362The function \cfunction{PyErr_Occurred()} can be used to check for
363this: it returns a borrowed reference to the exception type object
364when an exception has occurred, and \NULL{} otherwise. There are a
365number of functions to set the exception state:
366\cfunction{PyErr_SetString()} is the most common (though not the most
367general) function to set the exception state, and
368\cfunction{PyErr_Clear()} clears the exception state.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000369
370The full exception state consists of three objects (all of which can
Fred Drakee058b4f1998-02-16 06:15:35 +0000371be \NULL{}): the exception type, the corresponding exception
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000372value, and the traceback. These have the same meanings as the Python
373object \code{sys.exc_type}, \code{sys.exc_value},
374\code{sys.exc_traceback}; however, they are not the same: the Python
375objects represent the last exception being handled by a Python
Fred Drakee058b4f1998-02-16 06:15:35 +0000376\keyword{try} \ldots\ \keyword{except} statement, while the \C{} level
377exception state only exists while an exception is being passed on
378between \C{} functions until it reaches the Python interpreter, which
379takes care of transferring it to \code{sys.exc_type} and friends.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000380
381(Note that starting with Python 1.5, the preferred, thread-safe way to
382access the exception state from Python code is to call the function
Fred Drakee058b4f1998-02-16 06:15:35 +0000383\function{sys.exc_info()}, which returns the per-thread exception state
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000384for Python code. Also, the semantics of both ways to access the
385exception state have changed so that a function which catches an
386exception will save and restore its thread's exception state so as to
387preserve the exception state of its caller. This prevents common bugs
388in exception handling code caused by an innocent-looking function
389overwriting the exception being handled; it also reduces the often
390unwanted lifetime extension for objects that are referenced by the
391stack frames in the traceback.)
392
393As a general principle, a function that calls another function to
394perform some task should check whether the called function raised an
395exception, and if so, pass the exception state on to its caller. It
Fred Drakee058b4f1998-02-16 06:15:35 +0000396should discard any object references that it owns, and returns an
397error indicator, but it should \emph{not} set another exception ---
398that would overwrite the exception that was just raised, and lose
399important information about the exact cause of the error.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000400
401A simple example of detecting exceptions and passing them on is shown
Fred Drakee058b4f1998-02-16 06:15:35 +0000402in the \cfunction{sum_sequence()} example above. It so happens that
403that example doesn't need to clean up any owned references when it
404detects an error. The following example function shows some error
405cleanup. First, to remind you why you like Python, we show the
406equivalent Python code:
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000407
408\begin{verbatim}
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000409def incr_item(dict, key):
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000410 try:
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000411 item = dict[key]
412 except KeyError:
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000413 item = 0
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000414 return item + 1
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000415\end{verbatim}
416
Fred Drakeb0a78731998-01-13 18:51:10 +0000417Here is the corresponding \C{} code, in all its glory:
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000418
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000419\begin{verbatim}
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000420int incr_item(PyObject *dict, PyObject *key)
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000421{
422 /* Objects all initialized to NULL for Py_XDECREF */
423 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000424 int rv = -1; /* Return value initialized to -1 (failure) */
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000425
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000426 item = PyObject_GetItem(dict, key);
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000427 if (item == NULL) {
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000428 /* Handle keyError only: */
429 if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000430
431 /* Clear the error and use zero: */
432 PyErr_Clear();
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000433 item = PyInt_FromLong(0L);
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000434 if (item == NULL) goto error;
435 }
436
437 const_one = PyInt_FromLong(1L);
438 if (const_one == NULL) goto error;
439
440 incremented_item = PyNumber_Add(item, const_one);
441 if (incremented_item == NULL) goto error;
442
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000443 if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000444 rv = 0; /* Success */
445 /* Continue with cleanup code */
446
447 error:
448 /* Cleanup code, shared by success and failure path */
449
450 /* Use Py_XDECREF() to ignore NULL references */
451 Py_XDECREF(item);
452 Py_XDECREF(const_one);
453 Py_XDECREF(incremented_item);
454
455 return rv; /* -1 for error, 0 for success */
456}
457\end{verbatim}
458
459This example represents an endorsed use of the \code{goto} statement
Fred Drakee058b4f1998-02-16 06:15:35 +0000460in \C{}! It illustrates the use of
461\cfunction{PyErr_ExceptionMatches()} and \cfunction{PyErr_Clear()} to
462handle specific exceptions, and the use of \cfunction{Py_XDECREF()} to
463dispose of owned references that may be \NULL{} (note the \samp{X} in
464the name; \cfunction{Py_DECREF()} would crash when confronted with a
465\NULL{} reference). It is important that the variables used to hold
466owned references are initialized to \NULL{} for this to work;
467likewise, the proposed return value is initialized to \code{-1}
468(failure) and only set to success after the final call made is
469successful.
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000470
Guido van Rossum59a61351997-08-14 20:34:33 +0000471
472\section{Embedding Python}
473
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000474The one important task that only embedders (as opposed to extension
475writers) of the Python interpreter have to worry about is the
476initialization, and possibly the finalization, of the Python
477interpreter. Most functionality of the interpreter can only be used
478after the interpreter has been initialized.
Guido van Rossum59a61351997-08-14 20:34:33 +0000479
Fred Drakee058b4f1998-02-16 06:15:35 +0000480The basic initialization function is \cfunction{Py_Initialize()}.
481This initializes the table of loaded modules, and creates the
482fundamental modules \module{__builtin__}, \module{__main__} and
483\module{sys}. It also initializes the module search path
484(\code{sys.path}).
Guido van Rossum59a61351997-08-14 20:34:33 +0000485
Fred Drakee058b4f1998-02-16 06:15:35 +0000486\cfunction{Py_Initialize()} does not set the ``script argument list''
Guido van Rossum4a944d71997-08-14 20:35:38 +0000487(\code{sys.argv}). If this variable is needed by Python code that
488will be executed later, it must be set explicitly with a call to
489\code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
Fred Drakee058b4f1998-02-16 06:15:35 +0000490to \cfunction{Py_Initialize()}.
Guido van Rossum59a61351997-08-14 20:34:33 +0000491
Fred Drakeb0a78731998-01-13 18:51:10 +0000492On most systems (in particular, on \UNIX{} and Windows, although the
Fred Drakee058b4f1998-02-16 06:15:35 +0000493details are slightly different), \cfunction{Py_Initialize()}
494calculates the module search path based upon its best guess for the
495location of the standard Python interpreter executable, assuming that
496the Python library is found in a fixed location relative to the Python
Guido van Rossum42cefd01997-10-05 15:27:29 +0000497interpreter executable. In particular, it looks for a directory named
Fred Drakee058b4f1998-02-16 06:15:35 +0000498\file{lib/python\version} (replacing \file{\version} with the current
Guido van Rossum42cefd01997-10-05 15:27:29 +0000499interpreter version) relative to the parent directory where the
Fred Drakee058b4f1998-02-16 06:15:35 +0000500executable named \file{python} is found on the shell command search
Guido van Rossum42cefd01997-10-05 15:27:29 +0000501path (the environment variable \code{\$PATH}).
502
503For instance, if the Python executable is found in
Fred Drakee058b4f1998-02-16 06:15:35 +0000504\file{/usr/local/bin/python}, it will assume that the libraries are in
505\file{/usr/local/lib/python\version}. (In fact, this particular path
506is also the ``fallback'' location, used when no executable file named
507\file{python} is found along \code{\$PATH}.) The user can override
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000508this behavior by setting the environment variable \code{\$PYTHONHOME},
509or insert additional directories in front of the standard path by
510setting \code{\$PYTHONPATH}.
Guido van Rossum59a61351997-08-14 20:34:33 +0000511
Guido van Rossum4a944d71997-08-14 20:35:38 +0000512The embedding application can steer the search by calling
513\code{Py_SetProgramName(\var{file})} \emph{before} calling
Fred Drakee058b4f1998-02-16 06:15:35 +0000514\cfunction{Py_Initialize()}. Note that \code{\$PYTHONHOME} still
515overrides this and \code{\$PYTHONPATH} is still inserted in front of
516the standard path. An application that requires total control has to
517provide its own implementation of \cfunction{Py_GetPath()},
518\cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
519\cfunction{Py_GetProgramFullPath()} (all defined in
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000520\file{Modules/getpath.c}).
Guido van Rossum59a61351997-08-14 20:34:33 +0000521
Guido van Rossum4a944d71997-08-14 20:35:38 +0000522Sometimes, it is desirable to ``uninitialize'' Python. For instance,
523the application may want to start over (make another call to
Fred Drakee058b4f1998-02-16 06:15:35 +0000524\cfunction{Py_Initialize()}) or the application is simply done with its
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000525use of Python and wants to free all memory allocated by Python. This
Fred Drakee058b4f1998-02-16 06:15:35 +0000526can be accomplished by calling \cfunction{Py_Finalize()}. The function
527\cfunction{Py_IsInitialized()} returns true iff Python is currently in the
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000528initialized state. More information about these functions is given in
529a later chapter.
Guido van Rossum59a61351997-08-14 20:34:33 +0000530
Guido van Rossum4a944d71997-08-14 20:35:38 +0000531
Fred Drakee5bf8b21998-02-12 21:22:28 +0000532\chapter{The Very High Level Layer}
Guido van Rossum4a944d71997-08-14 20:35:38 +0000533
Fred Drakee5bf8b21998-02-12 21:22:28 +0000534The functions in this chapter will let you execute Python source code
535given in a file or a buffer, but they will not let you interact in a
536more detailed way with the interpreter.
Guido van Rossum4a944d71997-08-14 20:35:38 +0000537
Fred Drakee5bf8b21998-02-12 21:22:28 +0000538\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000539\end{cfuncdesc}
540
Fred Drakee5bf8b21998-02-12 21:22:28 +0000541\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000542\end{cfuncdesc}
543
Fred Drakee5bf8b21998-02-12 21:22:28 +0000544\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
545\end{cfuncdesc}
546
547\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
548\end{cfuncdesc}
549
550\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
551\end{cfuncdesc}
552
553\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
554\end{cfuncdesc}
555
556\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
557\end{cfuncdesc}
558
559\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
560\end{cfuncdesc}
561
562\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
563\end{cfuncdesc}
564
565\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000566\end{cfuncdesc}
567
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000568
569\chapter{Reference Counting}
570
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000571The macros in this section are used for managing reference counts
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000572of Python objects.
573
574\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
575Increment the reference count for object \code{o}. The object must
576not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
Fred Drakee058b4f1998-02-16 06:15:35 +0000577\cfunction{Py_XINCREF()}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000578\end{cfuncdesc}
579
580\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +0000581Increment the reference count for object \var{o}. The object may be
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000582\NULL{}, in which case the macro has no effect.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000583\end{cfuncdesc}
584
585\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +0000586Decrement the reference count for object \var{o}. The object must
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000587not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
Fred Drakee058b4f1998-02-16 06:15:35 +0000588\cfunction{Py_XDECREF()}. If the reference count reaches zero, the
589object's type's deallocation function (which must not be \NULL{}) is
590invoked.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000591
592\strong{Warning:} The deallocation function can cause arbitrary Python
Fred Drakee058b4f1998-02-16 06:15:35 +0000593code to be invoked (e.g. when a class instance with a \method{__del__()}
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000594method is deallocated). While exceptions in such code are not
595propagated, the executed code has free access to all Python global
596variables. This means that any object that is reachable from a global
Fred Drakee058b4f1998-02-16 06:15:35 +0000597variable should be in a consistent state before \cfunction{Py_DECREF()} is
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000598invoked. For example, code to delete an object from a list should
599copy a reference to the deleted object in a temporary variable, update
Fred Drakee058b4f1998-02-16 06:15:35 +0000600the list data structure, and then call \cfunction{Py_DECREF()} for the
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000601temporary variable.
602\end{cfuncdesc}
603
604\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +0000605Decrement the reference count for object \var{o}. The object may be
606\NULL{}, in which case the macro has no effect; otherwise the effect
607is the same as for \cfunction{Py_DECREF()}, and the same warning
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000608applies.
609\end{cfuncdesc}
610
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000611The following functions or macros are only for internal use:
Fred Drakee058b4f1998-02-16 06:15:35 +0000612\cfunction{_Py_Dealloc()}, \cfunction{_Py_ForgetReference()},
613\cfunction{_Py_NewReference()}, as well as the global variable
614\code{_Py_RefTotal}.
Guido van Rossumae110af1997-05-22 20:11:52 +0000615
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000616XXX Should mention Py_Malloc(), Py_Realloc(), Py_Free(),
617PyMem_Malloc(), PyMem_Realloc(), PyMem_Free(), PyMem_NEW(),
618PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
619
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000620
621\chapter{Exception Handling}
622
623The functions in this chapter will let you handle and raise Python
Guido van Rossumae110af1997-05-22 20:11:52 +0000624exceptions. It is important to understand some of the basics of
Fred Drakeb0a78731998-01-13 18:51:10 +0000625Python exception handling. It works somewhat like the \UNIX{}
Guido van Rossumae110af1997-05-22 20:11:52 +0000626\code{errno} variable: there is a global indicator (per thread) of the
627last error that occurred. Most functions don't clear this on success,
628but will set it to indicate the cause of the error on failure. Most
629functions also return an error indicator, usually \NULL{} if they are
Fred Drakee058b4f1998-02-16 06:15:35 +0000630supposed to return a pointer, or \code{-1} if they return an integer
631(exception: the \code{PyArg_Parse*()} functions return \code{1} for
632success and \code{0} for failure). When a function must fail because
633some function it called failed, it generally doesn't set the error
634indicator; the function it called already set it.
Guido van Rossumae110af1997-05-22 20:11:52 +0000635
636The error indicator consists of three Python objects corresponding to
637the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
638\code{sys.exc_traceback}. API functions exist to interact with the
639error indicator in various ways. There is a separate error indicator
640for each thread.
641
642% XXX Order of these should be more thoughtful.
643% Either alphabetical or some kind of structure.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000644
645\begin{cfuncdesc}{void}{PyErr_Print}{}
Guido van Rossumae110af1997-05-22 20:11:52 +0000646Print a standard traceback to \code{sys.stderr} and clear the error
647indicator. Call this function only when the error indicator is set.
648(Otherwise it will cause a fatal error!)
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000649\end{cfuncdesc}
650
Guido van Rossumae110af1997-05-22 20:11:52 +0000651\begin{cfuncdesc}{PyObject *}{PyErr_Occurred}{}
652Test whether the error indicator is set. If set, return the exception
Fred Drakee058b4f1998-02-16 06:15:35 +0000653\emph{type} (the first argument to the last call to one of the
654\code{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If
655not set, return \NULL{}. You do not own a reference to the return
656value, so you do not need to \cfunction{Py_DECREF()} it.
657\strong{Note:} do not compare the return value to a specific
658exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
659below.
Guido van Rossum42cefd01997-10-05 15:27:29 +0000660\end{cfuncdesc}
661
662\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000663\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000664Equivalent to
Fred Drakee058b4f1998-02-16 06:15:35 +0000665\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
Guido van Rossum42cefd01997-10-05 15:27:29 +0000666This should only be called when an exception is actually set.
667\end{cfuncdesc}
668
669\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000670\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000671Return true if the \var{given} exception matches the exception in
672\var{exc}. If \var{exc} is a class object, this also returns true
673when \var{given} is a subclass. If \var{exc} is a tuple, all
674exceptions in the tuple (and recursively in subtuples) are searched
675for a match. This should only be called when an exception is actually
676set.
677\end{cfuncdesc}
678
679\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000680\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000681Under certain circumstances, the values returned by
Fred Drakee058b4f1998-02-16 06:15:35 +0000682\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
683\code{*\var{exc}} is a class object but \code{*\var{val}} is not an
684instance of the same class. This function can be used to instantiate
685the class in that case. If the values are already normalized, nothing
686happens.
Guido van Rossumae110af1997-05-22 20:11:52 +0000687\end{cfuncdesc}
688
689\begin{cfuncdesc}{void}{PyErr_Clear}{}
690Clear the error indicator. If the error indicator is not set, there
691is no effect.
692\end{cfuncdesc}
693
694\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, PyObject **ptraceback}
695Retrieve the error indicator into three variables whose addresses are
696passed. If the error indicator is not set, set all three variables to
697\NULL{}. If it is set, it will be cleared and you own a reference to
698each object retrieved. The value and traceback object may be \NULL{}
699even when the type object is not. \strong{Note:} this function is
700normally only used by code that needs to handle exceptions or by code
701that needs to save and restore the error indicator temporarily.
702\end{cfuncdesc}
703
704\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
705Set the error indicator from the three objects. If the error
706indicator is already set, it is cleared first. If the objects are
707\NULL{}, the error indicator is cleared. Do not pass a \NULL{} type
708and non-\NULL{} value or traceback. The exception type should be a
709string or class; if it is a class, the value should be an instance of
710that class. Do not pass an invalid exception type or value.
711(Violating these rules will cause subtle problems later.) This call
712takes away a reference to each object, i.e. you must own a reference
713to each object before the call and after the call you no longer own
714these references. (If you don't understand this, don't use this
715function. I warned you.) \strong{Note:} this function is normally
716only used by code that needs to save and restore the error indicator
717temporarily.
718\end{cfuncdesc}
719
720\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
721This is the most common way to set the error indicator. The first
722argument specifies the exception type; it is normally one of the
723standard exceptions, e.g. \code{PyExc_RuntimeError}. You need not
724increment its reference count. The second argument is an error
725message; it is converted to a string object.
726\end{cfuncdesc}
727
728\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
Fred Drakee058b4f1998-02-16 06:15:35 +0000729This function is similar to \cfunction{PyErr_SetString()} but lets you
Guido van Rossumae110af1997-05-22 20:11:52 +0000730specify an arbitrary Python object for the ``value'' of the exception.
731You need not increment its reference count.
732\end{cfuncdesc}
733
734\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
Fred Drakee058b4f1998-02-16 06:15:35 +0000735This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
Guido van Rossumae110af1997-05-22 20:11:52 +0000736\end{cfuncdesc}
737
738\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
Fred Drakee058b4f1998-02-16 06:15:35 +0000739This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
Guido van Rossumae110af1997-05-22 20:11:52 +0000740\var{message})}, where \var{message} indicates that a built-in operation
741was invoked with an illegal argument. It is mostly for internal use.
742\end{cfuncdesc}
743
744\begin{cfuncdesc}{PyObject *}{PyErr_NoMemory}{}
Fred Drakee058b4f1998-02-16 06:15:35 +0000745This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
Guido van Rossumae110af1997-05-22 20:11:52 +0000746returns \NULL{} so an object allocation function can write
Fred Drakee058b4f1998-02-16 06:15:35 +0000747\samp{return PyErr_NoMemory();} when it runs out of memory.
Guido van Rossumae110af1997-05-22 20:11:52 +0000748\end{cfuncdesc}
749
750\begin{cfuncdesc}{PyObject *}{PyErr_SetFromErrno}{PyObject *type}
Fred Drakeb0a78731998-01-13 18:51:10 +0000751This is a convenience function to raise an exception when a \C{} library
752function has returned an error and set the \C{} variable \code{errno}.
Guido van Rossumae110af1997-05-22 20:11:52 +0000753It constructs a tuple object whose first item is the integer
754\code{errno} value and whose second item is the corresponding error
Fred Drakee058b4f1998-02-16 06:15:35 +0000755message (gotten from \cfunction{strerror()}), and then calls
756\samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
757the \code{errno} value is \constant{EINTR}, indicating an interrupted
758system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
Guido van Rossumae110af1997-05-22 20:11:52 +0000759the error indicator, leaves it set to that. The function always
760returns \NULL{}, so a wrapper function around a system call can write
Fred Drakee058b4f1998-02-16 06:15:35 +0000761\samp{return PyErr_SetFromErrno();} when the system call returns an
762error.
Guido van Rossumae110af1997-05-22 20:11:52 +0000763\end{cfuncdesc}
764
765\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
Fred Drakee058b4f1998-02-16 06:15:35 +0000766This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
Guido van Rossumae110af1997-05-22 20:11:52 +0000767\var{message})}, where \var{message} indicates that an internal
Guido van Rossum5060b3b1997-08-17 18:02:23 +0000768operation (e.g. a Python/C API function) was invoked with an illegal
Guido van Rossumae110af1997-05-22 20:11:52 +0000769argument. It is mostly for internal use.
770\end{cfuncdesc}
771
772\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
773This function interacts with Python's signal handling. It checks
774whether a signal has been sent to the processes and if so, invokes the
Fred Drakee058b4f1998-02-16 06:15:35 +0000775corresponding signal handler. If the \module{signal} module is
Guido van Rossumae110af1997-05-22 20:11:52 +0000776supported, this can invoke a signal handler written in Python. In all
Fred Drakee058b4f1998-02-16 06:15:35 +0000777cases, the default effect for \constant{SIGINT} is to raise the
778\exception{KeyboadInterrupt} exception. If an exception is raised the
779error indicator is set and the function returns \code{1}; otherwise
780the function returns \code{0}. The error indicator may or may not be
781cleared if it was previously set.
Guido van Rossumae110af1997-05-22 20:11:52 +0000782\end{cfuncdesc}
783
784\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
785This function is obsolete (XXX or platform dependent?). It simulates
Fred Drakee058b4f1998-02-16 06:15:35 +0000786the effect of a \constant{SIGINT} signal arriving --- the next time
787\cfunction{PyErr_CheckSignals()} is called,
788\exception{KeyboadInterrupt} will be raised.
Guido van Rossumae110af1997-05-22 20:11:52 +0000789\end{cfuncdesc}
790
Guido van Rossum42cefd01997-10-05 15:27:29 +0000791\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
792PyObject *base, PyObject *dict}
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000793\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000794This utility function creates and returns a new exception object. The
Fred Drakeb0a78731998-01-13 18:51:10 +0000795\var{name} argument must be the name of the new exception, a \C{} string
Guido van Rossum42cefd01997-10-05 15:27:29 +0000796of the form \code{module.class}. The \var{base} and \var{dict}
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000797arguments are normally \NULL{}. Normally, this creates a class
Guido van Rossum42cefd01997-10-05 15:27:29 +0000798object derived from the root for all exceptions, the built-in name
Fred Drakee058b4f1998-02-16 06:15:35 +0000799\exception{Exception} (accessible in \C{} as \code{PyExc_Exception}).
800In this case the \code{__module__} attribute of the new class is set to the
Guido van Rossum42cefd01997-10-05 15:27:29 +0000801first part (up to the last dot) of the \var{name} argument, and the
802class name is set to the last part (after the last dot). When the
803user has specified the \code{-X} command line option to use string
804exceptions, for backward compatibility, or when the \var{base}
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000805argument is not a class object (and not \NULL{}), a string object
Guido van Rossum42cefd01997-10-05 15:27:29 +0000806created from the entire \var{name} argument is returned. The
807\var{base} argument can be used to specify an alternate base class.
808The \var{dict} argument can be used to specify a dictionary of class
809variables and methods.
810\end{cfuncdesc}
811
812
Guido van Rossumae110af1997-05-22 20:11:52 +0000813\section{Standard Exceptions}
814
815All standard Python exceptions are available as global variables whose
Fred Drakee058b4f1998-02-16 06:15:35 +0000816names are \samp{PyExc_} followed by the Python exception name.
817These have the type \code{PyObject *}; they are all either class
818objects or string objects, depending on the use of the \code{-X}
819option to the interpreter. For completeness, here are all the
820variables (the first four are new in Python 1.5a4):
Guido van Rossum42cefd01997-10-05 15:27:29 +0000821\code{PyExc_Exception},
822\code{PyExc_StandardError},
823\code{PyExc_ArithmeticError},
824\code{PyExc_LookupError},
Guido van Rossumae110af1997-05-22 20:11:52 +0000825\code{PyExc_AssertionError},
826\code{PyExc_AttributeError},
827\code{PyExc_EOFError},
828\code{PyExc_FloatingPointError},
829\code{PyExc_IOError},
830\code{PyExc_ImportError},
831\code{PyExc_IndexError},
832\code{PyExc_KeyError},
833\code{PyExc_KeyboardInterrupt},
834\code{PyExc_MemoryError},
835\code{PyExc_NameError},
836\code{PyExc_OverflowError},
837\code{PyExc_RuntimeError},
838\code{PyExc_SyntaxError},
839\code{PyExc_SystemError},
840\code{PyExc_SystemExit},
841\code{PyExc_TypeError},
842\code{PyExc_ValueError},
843\code{PyExc_ZeroDivisionError}.
844
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000845
846\chapter{Utilities}
847
848The functions in this chapter perform various utility tasks, such as
Fred Drakeb0a78731998-01-13 18:51:10 +0000849parsing function arguments and constructing Python values from \C{}
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000850values.
851
Guido van Rossum42cefd01997-10-05 15:27:29 +0000852\section{OS Utilities}
853
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000854\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
Fred Drakee058b4f1998-02-16 06:15:35 +0000855Return true (nonzero) if the standard I/O file \var{fp} with name
856\var{filename} is deemed interactive. This is the case for files for
857which \samp{isatty(fileno(\var{fp}))} is true. If the global flag
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000858\code{Py_InteractiveFlag} is true, this function also returns true if
Fred Drakee058b4f1998-02-16 06:15:35 +0000859the \var{name} pointer is \NULL{} or if the name is equal to one of
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000860the strings \code{"<stdin>"} or \code{"???"}.
861\end{cfuncdesc}
862
863\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
Fred Drakee058b4f1998-02-16 06:15:35 +0000864Return the time of last modification of the file \var{filename}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000865The result is encoded in the same way as the timestamp returned by
Fred Drakee058b4f1998-02-16 06:15:35 +0000866the standard \C{} library function \cfunction{time()}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +0000867\end{cfuncdesc}
868
869
Fred Drakee5bf8b21998-02-12 21:22:28 +0000870\section{Process Control}
871
872\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
873Print a fatal error message and kill the process. No cleanup is
874performed. This function should only be invoked when a condition is
875detected that would make it dangerous to continue using the Python
876interpreter; e.g., when the object administration appears to be
Fred Drakee058b4f1998-02-16 06:15:35 +0000877corrupted. On \UNIX{}, the standard \C{} library function
878\cfunction{abort()} is called which will attempt to produce a
879\file{core} file.
Fred Drakee5bf8b21998-02-12 21:22:28 +0000880\end{cfuncdesc}
881
882\begin{cfuncdesc}{void}{Py_Exit}{int status}
Fred Drakee058b4f1998-02-16 06:15:35 +0000883Exit the current process. This calls \cfunction{Py_Finalize()} and
884then calls the standard \C{} library function
885\code{exit(\var{status})}.
Fred Drakee5bf8b21998-02-12 21:22:28 +0000886\end{cfuncdesc}
887
888\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
889Register a cleanup function to be called by \cfunction{Py_Finalize()}.
890The cleanup function will be called with no arguments and should
891return no value. At most 32 cleanup functions can be registered.
892When the registration is successful, \cfunction{Py_AtExit()} returns
893\code{0}; on failure, it returns \code{-1}. The cleanup function
894registered last is called first. Each cleanup function will be called
895at most once. Since Python's internal finallization will have
896completed before the cleanup function, no Python APIs should be called
897by \var{func}.
898\end{cfuncdesc}
899
900
901\section{Importing Modules}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000902
903\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
Fred Drakee058b4f1998-02-16 06:15:35 +0000904This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000905below, leaving the \var{globals} and \var{locals} arguments set to
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000906\NULL{}. When the \var{name} argument contains a dot (i.e., when
Guido van Rossum42cefd01997-10-05 15:27:29 +0000907it specifies a submodule of a package), the \var{fromlist} argument is
908set to the list \code{['*']} so that the return value is the named
909module rather than the top-level package containing it as would
910otherwise be the case. (Unfortunately, this has an additional side
911effect when \var{name} in fact specifies a subpackage instead of a
912submodule: the submodules specified in the package's \code{__all__}
913variable are loaded.) Return a new reference to the imported module,
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000914or \NULL{} with an exception set on failure (the module may still
Guido van Rossum42cefd01997-10-05 15:27:29 +0000915be created in this case).
916\end{cfuncdesc}
917
918\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000919\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000920Import a module. This is best described by referring to the built-in
Fred Drake53fb7721998-02-16 06:23:20 +0000921Python function \function{__import__()}\bifuncindex{__import__}, as
922the standard \function{__import__()} function calls this function
923directly.
Guido van Rossum42cefd01997-10-05 15:27:29 +0000924
Guido van Rossum42cefd01997-10-05 15:27:29 +0000925The return value is a new reference to the imported module or
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000926top-level package, or \NULL{} with an exception set on failure
Guido van Rossumc44d3d61997-10-06 05:10:47 +0000927(the module may still be created in this case). Like for
Fred Drakee058b4f1998-02-16 06:15:35 +0000928\function{__import__()}, the return value when a submodule of a
929package was requested is normally the top-level package, unless a
930non-empty \var{fromlist} was given.
Guido van Rossum42cefd01997-10-05 15:27:29 +0000931\end{cfuncdesc}
932
933\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name}
934This is a higher-level interface that calls the current ``import hook
Fred Drakee058b4f1998-02-16 06:15:35 +0000935function''. It invokes the \function{__import__()} function from the
Guido van Rossum42cefd01997-10-05 15:27:29 +0000936\code{__builtins__} of the current globals. This means that the
937import is done using whatever import hooks are installed in the
Fred Drakee058b4f1998-02-16 06:15:35 +0000938current environment, e.g. by \module{rexec} or \module{ihooks}.
Guido van Rossum42cefd01997-10-05 15:27:29 +0000939\end{cfuncdesc}
940
941\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
942Reload a module. This is best described by referring to the built-in
Fred Drake53fb7721998-02-16 06:23:20 +0000943Python function \function{reload()}\bifuncindex{reload}, as the standard
Fred Drakee058b4f1998-02-16 06:15:35 +0000944\function{reload()} function calls this function directly. Return a
945new reference to the reloaded module, or \NULL{} with an exception set
946on failure (the module still exists in this case).
Guido van Rossum42cefd01997-10-05 15:27:29 +0000947\end{cfuncdesc}
948
949\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name}
950Return the module object corresponding to a module name. The
951\var{name} argument may be of the form \code{package.module}). First
952check the modules dictionary if there's one there, and if not, create
953a new one and insert in in the modules dictionary. Because the former
954action is most common, this does not return a new reference, and you
Guido van Rossum580aa8d1997-11-25 15:34:51 +0000955do not own the returned reference. Return \NULL{} with an
Guido van Rossum42cefd01997-10-05 15:27:29 +0000956exception set on failure.
957\end{cfuncdesc}
958
959\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co}
960Given a module name (possibly of the form \code{package.module}) and a
961code object read from a Python bytecode file or obtained from the
Fred Drake53fb7721998-02-16 06:23:20 +0000962built-in function \function{compile()}\bifuncindex{compile}, load the
963module. Return a new reference to the module object, or \NULL{} with
964an exception set if an error occurred (the module may still be created
965in this case). (This function would reload the module if it was
966already imported.)
Guido van Rossum42cefd01997-10-05 15:27:29 +0000967\end{cfuncdesc}
968
969\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
Fred Drakee058b4f1998-02-16 06:15:35 +0000970Return the magic number for Python bytecode files (a.k.a. \file{.pyc}
971and \file{.pyo} files). The magic number should be present in the
Guido van Rossum42cefd01997-10-05 15:27:29 +0000972first four bytes of the bytecode file, in little-endian byte order.
973\end{cfuncdesc}
974
975\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{}
976Return the dictionary used for the module administration
977(a.k.a. \code{sys.modules}). Note that this is a per-interpreter
978variable.
979\end{cfuncdesc}
980
981\begin{cfuncdesc}{void}{_PyImport_Init}{}
982Initialize the import mechanism. For internal use only.
983\end{cfuncdesc}
984
985\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
986Empty the module table. For internal use only.
987\end{cfuncdesc}
988
989\begin{cfuncdesc}{void}{_PyImport_Fini}{}
990Finalize the import mechanism. For internal use only.
991\end{cfuncdesc}
992
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000993\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000994For internal use only.
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000995\end{cfuncdesc}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000996
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000997\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
Guido van Rossum42cefd01997-10-05 15:27:29 +0000998For internal use only.
Guido van Rossum5b8a5231997-12-30 04:38:44 +0000999\end{cfuncdesc}
Guido van Rossum42cefd01997-10-05 15:27:29 +00001000
1001\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
1002Load a frozen module. Return \code{1} for success, \code{0} if the
1003module is not found, and \code{-1} with an exception set if the
1004initialization failed. To access the imported module on a successful
Fred Drakee058b4f1998-02-16 06:15:35 +00001005load, use \cfunction{PyImport_ImportModule()}.
1006(Note the misnomer --- this function would reload the module if it was
Guido van Rossum42cefd01997-10-05 15:27:29 +00001007already imported.)
1008\end{cfuncdesc}
1009
1010\begin{ctypedesc}{struct _frozen}
1011This is the structure type definition for frozen module descriptors,
1012as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
1013the Python source distribution). Its definition is:
Guido van Rossum9faf4c51997-10-07 14:38:54 +00001014\begin{verbatim}
Guido van Rossum42cefd01997-10-05 15:27:29 +00001015struct _frozen {
Fred Drake36fbe761997-10-13 18:18:33 +00001016 char *name;
1017 unsigned char *code;
1018 int size;
Guido van Rossum42cefd01997-10-05 15:27:29 +00001019};
Guido van Rossum9faf4c51997-10-07 14:38:54 +00001020\end{verbatim}
Guido van Rossum42cefd01997-10-05 15:27:29 +00001021\end{ctypedesc}
1022
1023\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
1024This pointer is initialized to point to an array of \code{struct
Guido van Rossum580aa8d1997-11-25 15:34:51 +00001025_frozen} records, terminated by one whose members are all \NULL{}
Guido van Rossum42cefd01997-10-05 15:27:29 +00001026or zero. When a frozen module is imported, it is searched in this
1027table. Third party code could play tricks with this to provide a
1028dynamically created collection of frozen modules.
1029\end{cvardesc}
1030
1031
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001032\chapter{Abstract Objects Layer}
1033
1034The functions in this chapter interact with Python objects regardless
1035of their type, or with wide classes of object types (e.g. all
1036numerical types, or all sequence types). When used on object types
1037for which they do not apply, they will flag a Python exception.
1038
1039\section{Object Protocol}
1040
1041\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
Fred Drakee058b4f1998-02-16 06:15:35 +00001042Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001043The flags argument is used to enable certain printing
Fred Drakee058b4f1998-02-16 06:15:35 +00001044options. The only option currently supported is
1045\constant{Py_Print_RAW}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001046\end{cfuncdesc}
1047
1048\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001049Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
1050\code{0} otherwise. This is equivalent to the Python expression
1051\samp{hasattr(\var{o}, \var{attr_name})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001052This function always succeeds.
1053\end{cfuncdesc}
1054
1055\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001056Retrieve an attribute named \var{attr_name} from object \var{o}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001057Returns the attribute value on success, or \NULL{} on failure.
Fred Drakee058b4f1998-02-16 06:15:35 +00001058This is the equivalent of the Python expression
1059\samp{\var{o}.\var{attr_name}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001060\end{cfuncdesc}
1061
1062
1063\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001064Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
1065\code{0} otherwise. This is equivalent to the Python expression
1066\samp{hasattr(\var{o}, \var{attr_name})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001067This function always succeeds.
1068\end{cfuncdesc}
1069
1070
1071\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001072Retrieve an attribute named \var{attr_name} from object \var{o}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001073Returns the attribute value on success, or \NULL{} on failure.
Fred Drakee058b4f1998-02-16 06:15:35 +00001074This is the equivalent of the Python expression
1075\samp{\var{o}.\var{attr_name}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001076\end{cfuncdesc}
1077
1078
1079\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001080Set the value of the attribute named \var{attr_name}, for object
1081\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
1082the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
1083\var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001084\end{cfuncdesc}
1085
1086
1087\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001088Set the value of the attribute named \var{attr_name}, for
1089object \var{o},
1090to the value \var{v}. Returns \code{-1} on failure. This is
1091the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
1092\var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001093\end{cfuncdesc}
1094
1095
1096\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001097Delete attribute named \var{attr_name}, for object \var{o}. Returns
1098\code{-1} on failure. This is the equivalent of the Python
1099statement: \samp{del \var{o}.\var{attr_name}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001100\end{cfuncdesc}
1101
1102
1103\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
Fred Drakee058b4f1998-02-16 06:15:35 +00001104Delete attribute named \var{attr_name}, for object \var{o}. Returns
1105\code{-1} on failure. This is the equivalent of the Python
1106statement \samp{del \var{o}.\var{attr_name}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001107\end{cfuncdesc}
1108
1109
1110\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
Fred Drakee058b4f1998-02-16 06:15:35 +00001111Compare the values of \var{o1} and \var{o2} using a routine provided
1112by \var{o1}, if one exists, otherwise with a routine provided by
1113\var{o2}. The result of the comparison is returned in \var{result}.
1114Returns \code{-1} on failure. This is the equivalent of the Python
1115statement \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001116\end{cfuncdesc}
1117
1118
1119\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001120Compare the values of \var{o1} and \var{o2} using a routine provided
1121by \var{o1}, if one exists, otherwise with a routine provided by
1122\var{o2}. Returns the result of the comparison on success. On error,
1123the value returned is undefined; use \cfunction{PyErr_Occurred()} to
1124detect an error. This is equivalent to the
1125Python expression \samp{cmp(\var{o1}, \var{o2})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001126\end{cfuncdesc}
1127
1128
1129\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001130Compute the string representation of object, \var{o}. Returns the
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001131string representation on success, \NULL{} on failure. This is
Fred Drakee058b4f1998-02-16 06:15:35 +00001132the equivalent of the Python expression \samp{repr(\var{o})}.
1133Called by the \function{repr()}\bifuncindex{repr} built-in function
1134and by reverse quotes.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001135\end{cfuncdesc}
1136
1137
1138\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001139Compute the string representation of object \var{o}. Returns the
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001140string representation on success, \NULL{} on failure. This is
Fred Drakee058b4f1998-02-16 06:15:35 +00001141the equivalent of the Python expression \samp{str(\var{o})}.
1142Called by the \function{str()}\bifuncindex{str} built-in function and
1143by the \keyword{print} statement.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001144\end{cfuncdesc}
1145
1146
1147\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001148Determine if the object \var{o}, is callable. Return \code{1} if the
1149object is callable and \code{0} otherwise.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001150This function always succeeds.
1151\end{cfuncdesc}
1152
1153
1154\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
Fred Drakee058b4f1998-02-16 06:15:35 +00001155Call a callable Python object \var{callable_object}, with
1156arguments given by the tuple \var{args}. If no arguments are
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001157needed, then args may be \NULL{}. Returns the result of the
1158call on success, or \NULL{} on failure. This is the equivalent
Fred Drakee058b4f1998-02-16 06:15:35 +00001159of the Python expression \samp{apply(\var{o}, \var{args})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001160\end{cfuncdesc}
1161
1162\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
Fred Drakee058b4f1998-02-16 06:15:35 +00001163Call a callable Python object \var{callable_object}, with a
Fred Drakeb0a78731998-01-13 18:51:10 +00001164variable number of \C{} arguments. The \C{} arguments are described
Fred Drakee058b4f1998-02-16 06:15:35 +00001165using a \cfunction{Py_BuildValue()} style format string. The format may
1166be \NULL{}, indicating that no arguments are provided. Returns the
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001167result of the call on success, or \NULL{} on failure. This is
Fred Drakee058b4f1998-02-16 06:15:35 +00001168the equivalent of the Python expression \samp{apply(\var{o},
1169\var{args})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001170\end{cfuncdesc}
1171
1172
1173\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
Fred Drakee058b4f1998-02-16 06:15:35 +00001174Call the method named \var{m} of object \var{o} with a variable number
1175of C arguments. The \C{} arguments are described by a
1176\cfunction{Py_BuildValue()} format string. The format may be \NULL{},
1177indicating that no arguments are provided. Returns the result of the
1178call on success, or \NULL{} on failure. This is the equivalent of the
1179Python expression \samp{\var{o}.\var{method}(\var{args})}.
1180Note that Special method names, such as \method{__add__()},
1181\method{__getitem__()}, and so on are not supported. The specific
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001182abstract-object routines for these must be used.
1183\end{cfuncdesc}
1184
1185
1186\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001187Compute and return the hash value of an object \var{o}. On
1188failure, return \code{-1}. This is the equivalent of the Python
1189expression \samp{hash(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001190\end{cfuncdesc}
1191
1192
1193\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001194Returns \code{1} if the object \var{o} is considered to be true, and
1195\code{0} otherwise. This is equivalent to the Python expression
1196\samp{not not \var{o}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001197This function always succeeds.
1198\end{cfuncdesc}
1199
1200
1201\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
1202On success, returns a type object corresponding to the object
Fred Drakee058b4f1998-02-16 06:15:35 +00001203type of object \var{o}. On failure, returns \NULL{}. This is
1204equivalent to the Python expression \samp{type(\var{o})}.
Fred Drake53fb7721998-02-16 06:23:20 +00001205\bifuncindex{type}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001206\end{cfuncdesc}
1207
1208\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001209Return the length of object \var{o}. If the object \var{o} provides
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001210both sequence and mapping protocols, the sequence length is
Fred Drakee058b4f1998-02-16 06:15:35 +00001211returned. On error, \code{-1} is returned. This is the equivalent
1212to the Python expression \samp{len(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001213\end{cfuncdesc}
1214
1215
1216\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001217Return element of \var{o} corresponding to the object \var{key} or
1218\NULL{} on failure. This is the equivalent of the Python expression
1219\samp{\var{o}[\var{key}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001220\end{cfuncdesc}
1221
1222
1223\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001224Map the object \var{key} to the value \var{v}.
1225Returns \code{-1} on failure. This is the equivalent
1226of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001227\end{cfuncdesc}
1228
1229
1230\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001231Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
1232failure. This is the equivalent of the Python statement \samp{del
1233\var{o}[\var{key}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001234\end{cfuncdesc}
1235
1236
1237\section{Number Protocol}
1238
1239\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001240Returns \code{1} if the object \var{o} provides numeric protocols, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001241false otherwise.
1242This function always succeeds.
1243\end{cfuncdesc}
1244
1245
1246\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001247Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
1248failure. This is the equivalent of the Python expression
1249\samp{\var{o1} + \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001250\end{cfuncdesc}
1251
1252
1253\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001254Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
1255on failure. This is the equivalent of the Python expression
1256\samp{\var{o1} - \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001257\end{cfuncdesc}
1258
1259
1260\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001261Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
1262failure. This is the equivalent of the Python expression
1263\samp{\var{o1} * \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001264\end{cfuncdesc}
1265
1266
1267\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001268Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
1269failure.
1270This is the equivalent of the Python expression \samp{\var{o1} /
1271\var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001272\end{cfuncdesc}
1273
1274
1275\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001276Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
1277failure. This is the equivalent of the Python expression
1278\samp{\var{o1} \% \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001279\end{cfuncdesc}
1280
1281
1282\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
Fred Drake53fb7721998-02-16 06:23:20 +00001283See the built-in function \function{divmod()}\bifuncindex{divmod}.
1284Returns \NULL{} on failure. This is the equivalent of the Python
1285expression \samp{divmod(\var{o1}, \var{o2})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001286\end{cfuncdesc}
1287
1288
1289\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
Fred Drake53fb7721998-02-16 06:23:20 +00001290See the built-in function \function{pow()}\bifuncindex{pow}. Returns
1291\NULL{} on failure. This is the equivalent of the Python expression
Fred Drakee058b4f1998-02-16 06:15:35 +00001292\samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional.
1293If \var{o3} is to be ignored, pass \code{Py_None} in its place.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001294\end{cfuncdesc}
1295
1296
1297\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001298Returns the negation of \var{o} on success, or \NULL{} on failure.
1299This is the equivalent of the Python expression \samp{-\var{o}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001300\end{cfuncdesc}
1301
1302
1303\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001304Returns \var{o} on success, or \NULL{} on failure.
1305This is the equivalent of the Python expression \samp{+\var{o}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001306\end{cfuncdesc}
1307
1308
1309\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001310Returns the absolute value of \var{o}, or \NULL{} on failure. This is
1311the equivalent of the Python expression \samp{abs(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001312\end{cfuncdesc}
1313
1314
1315\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001316Returns the bitwise negation of \var{o} on success, or \NULL{} on
1317failure. This is the equivalent of the Python expression
1318\samp{\~\var{o}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001319\end{cfuncdesc}
1320
1321
1322\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001323Returns the result of left shifting \var{o1} by \var{o2} on success,
1324or \NULL{} on failure. This is the equivalent of the Python
1325expression \samp{\var{o1} << \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001326\end{cfuncdesc}
1327
1328
1329\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001330Returns the result of right shifting \var{o1} by \var{o2} on success,
1331or \NULL{} on failure. This is the equivalent of the Python
1332expression \samp{\var{o1} >> \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001333\end{cfuncdesc}
1334
1335
1336\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001337Returns the result of ``anding'' \var{o2} and \var{o2} on success and
1338\NULL{} on failure. This is the equivalent of the Python
1339expression \samp{\var{o1} and \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001340\end{cfuncdesc}
1341
1342
1343\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001344Returns the bitwise exclusive or of \var{o1} by \var{o2} on success,
1345or \NULL{} on failure. This is the equivalent of the Python
1346expression \samp{\var{o1} \^{ }\var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001347\end{cfuncdesc}
1348
1349\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001350Returns the result of \var{o1} and \var{o2} on success, or \NULL{} on
1351failure. This is the equivalent of the Python expression
1352\samp{\var{o1} or \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001353\end{cfuncdesc}
1354
1355
Fred Drakee058b4f1998-02-16 06:15:35 +00001356\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001357This function takes the addresses of two variables of type
1358\code{PyObject*}.
1359
Fred Drakee058b4f1998-02-16 06:15:35 +00001360If the objects pointed to by \code{*\var{p1}} and \code{*\var{p2}}
1361have the same type, increment their reference count and return
1362\code{0} (success). If the objects can be converted to a common
1363numeric type, replace \code{*p1} and \code{*p2} by their converted
1364value (with 'new' reference counts), and return \code{0}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001365If no conversion is possible, or if some other error occurs,
Fred Drakee058b4f1998-02-16 06:15:35 +00001366return \code{-1} (failure) and don't increment the reference counts.
1367The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the
1368Python statement \samp{\var{o1}, \var{o2} = coerce(\var{o1},
1369\var{o2})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001370\end{cfuncdesc}
1371
1372
1373\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001374Returns the \var{o} converted to an integer object on success, or
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001375\NULL{} on failure. This is the equivalent of the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001376expression \samp{int(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001377\end{cfuncdesc}
1378
1379
1380\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001381Returns the \var{o} converted to a long integer object on success,
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001382or \NULL{} on failure. This is the equivalent of the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001383expression \samp{long(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001384\end{cfuncdesc}
1385
1386
1387\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001388Returns the \var{o} converted to a float object on success, or \NULL{}
1389on failure. This is the equivalent of the Python expression
1390\samp{float(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001391\end{cfuncdesc}
1392
1393
Fred Drakef44617d1998-02-12 20:57:15 +00001394\section{Sequence Protocol}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001395
1396\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001397Return \code{1} if the object provides sequence protocol, and \code{0}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001398otherwise.
1399This function always succeeds.
1400\end{cfuncdesc}
1401
1402
1403\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001404Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001405failure. This is the equivalent of the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001406expression \samp{\var{o1} + \var{o2}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001407\end{cfuncdesc}
1408
1409
1410\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
Fred Drakee058b4f1998-02-16 06:15:35 +00001411Return the result of repeating sequence object \var{o} \var{count}
1412times, or \NULL{} on failure. This is the equivalent of the Python
1413expression \samp{\var{o} * \var{count}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001414\end{cfuncdesc}
1415
1416
1417\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
Fred Drakee058b4f1998-02-16 06:15:35 +00001418Return the \var{i}th element of \var{o}, or \NULL{} on failure. This
1419is the equivalent of the Python expression \samp{\var{o}[\var{i}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001420\end{cfuncdesc}
1421
1422
1423\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001424Return the slice of sequence object \var{o} between \var{i1} and
1425\var{i2}, or \NULL{} on failure. This is the equivalent of the Python
1426expression \samp{\var{o}[\var{i1}:\var{i2}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001427\end{cfuncdesc}
1428
1429
1430\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001431Assign object \var{v} to the \var{i}th element of \var{o}.
1432Returns \code{-1} on failure. This is the equivalent of the Python
1433statement \samp{\var{o}[\var{i}] = \var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001434\end{cfuncdesc}
1435
1436\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
Fred Drakee058b4f1998-02-16 06:15:35 +00001437Delete the \var{i}th element of object \var{v}. Returns
1438\code{-1} on failure. This is the equivalent of the Python
1439statement \samp{del \var{o}[\var{i}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001440\end{cfuncdesc}
1441
1442\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001443Assign the sequence object \var{v} to the slice in sequence
1444object \var{o} from \var{i1} to \var{i2}. This is the equivalent of
1445the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001446\end{cfuncdesc}
1447
1448\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
Fred Drakee058b4f1998-02-16 06:15:35 +00001449Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}.
1450Returns \code{-1} on failure. This is the equivalent of the Python
1451statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001452\end{cfuncdesc}
1453
1454\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001455Returns the \var{o} as a tuple on success, and \NULL{} on failure.
1456This is equivalent to the Python expression \code{tuple(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001457\end{cfuncdesc}
1458
1459\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
Fred Drakee058b4f1998-02-16 06:15:35 +00001460Return the number of occurrences of \var{value} in \var{o}, that is,
1461return the number of keys for which \code{\var{o}[\var{key}] ==
1462\var{value}}. On failure, return \code{-1}. This is equivalent to
1463the Python expression \samp{\var{o}.count(\var{value})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001464\end{cfuncdesc}
1465
1466\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
Fred Drakee058b4f1998-02-16 06:15:35 +00001467Determine if \var{o} contains \var{value}. If an item in \var{o} is
1468equal to \var{value}, return \code{1}, otherwise return \code{0}. On
1469error, return \code{-1}. This is equivalent to the Python expression
1470\samp{\var{value} in \var{o}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001471\end{cfuncdesc}
1472
1473\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
Fred Drakee058b4f1998-02-16 06:15:35 +00001474Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
1475\var{value}}. On error, return \code{-1}. This is equivalent to
1476the Python expression \samp{\var{o}.index(\var{value})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001477\end{cfuncdesc}
1478
Fred Drakef44617d1998-02-12 20:57:15 +00001479\section{Mapping Protocol}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001480
1481\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001482Return \code{1} if the object provides mapping protocol, and \code{0}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001483otherwise.
1484This function always succeeds.
1485\end{cfuncdesc}
1486
1487
1488\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001489Returns the number of keys in object \var{o} on success, and \code{-1}
1490on failure. For objects that do not provide sequence protocol,
1491this is equivalent to the Python expression \samp{len(\var{o})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001492\end{cfuncdesc}
1493
1494
1495\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001496Remove the mapping for object \var{key} from the object \var{o}.
1497Return \code{-1} on failure. This is equivalent to
1498the Python statement \samp{del \var{o}[\var{key}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001499\end{cfuncdesc}
1500
1501
1502\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001503Remove the mapping for object \var{key} from the object \var{o}.
1504Return \code{-1} on failure. This is equivalent to
1505the Python statement \samp{del \var{o}[\var{key}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001506\end{cfuncdesc}
1507
1508
1509\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001510On success, return \code{1} if the mapping object has the key \var{key}
1511and \code{0} otherwise. This is equivalent to the Python expression
1512\samp{\var{o}.has_key(\var{key})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001513This function always succeeds.
1514\end{cfuncdesc}
1515
1516
1517\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001518Return \code{1} if the mapping object has the key \var{key} and
1519\code{0} otherwise. This is equivalent to the Python expression
1520\samp{\var{o}.has_key(\var{key})}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001521This function always succeeds.
1522\end{cfuncdesc}
1523
1524
1525\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001526On success, return a list of the keys in object \var{o}. On
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001527failure, return \NULL{}. This is equivalent to the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001528expression \samp{\var{o}.keys()}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001529\end{cfuncdesc}
1530
1531
1532\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001533On success, return a list of the values in object \var{o}. On
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001534failure, return \NULL{}. This is equivalent to the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001535expression \samp{\var{o}.values()}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001536\end{cfuncdesc}
1537
1538
1539\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001540On success, return a list of the items in object \var{o}, where
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001541each item is a tuple containing a key-value pair. On
1542failure, return \NULL{}. This is equivalent to the Python
Fred Drakee058b4f1998-02-16 06:15:35 +00001543expression \samp{\var{o}.items()}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001544\end{cfuncdesc}
1545
1546\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001547Make object \var{o} empty. Returns \code{1} on success and \code{0}
1548on failure. This is equivalent to the Python statement
1549\samp{for key in \var{o}.keys(): del \var{o}[key]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001550\end{cfuncdesc}
1551
1552
1553\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001554Return element of \var{o} corresponding to the object \var{key} or
1555\NULL{} on failure. This is the equivalent of the Python expression
1556\samp{\var{o}[\var{key}]}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001557\end{cfuncdesc}
1558
1559\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001560Map the object \var{key} to the value \var{v} in object \var{o}.
1561Returns \code{-1} on failure. This is the equivalent of the Python
1562statement \samp{\var{o}[\var{key}] = \var{v}}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001563\end{cfuncdesc}
1564
1565
1566\section{Constructors}
1567
1568\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode}
1569On success, returns a new file object that is opened on the
Fred Drakee058b4f1998-02-16 06:15:35 +00001570file given by \var{file_name}, with a file mode given by \var{mode},
1571where \var{mode} has the same semantics as the standard \C{} routine
1572\cfunction{fopen()}. On failure, return \code{-1}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001573\end{cfuncdesc}
1574
1575\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del}
Fred Drakee058b4f1998-02-16 06:15:35 +00001576Return a new file object for an already opened standard \C{} file
1577pointer, \var{fp}. A file name, \var{file_name}, and open mode,
1578\var{mode}, must be provided as well as a flag, \var{close_on_del},
1579that indicates whether the file is to be closed when the file object
1580is destroyed. On failure, return \code{-1}.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001581\end{cfuncdesc}
1582
1583\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001584Returns a new float object with the value \var{v} on success, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001585\NULL{} on failure.
1586\end{cfuncdesc}
1587
1588\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001589Returns a new int object with the value \var{v} on success, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001590\NULL{} on failure.
1591\end{cfuncdesc}
1592
Fred Drakee058b4f1998-02-16 06:15:35 +00001593\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
1594Returns a new list of length \var{len} on success, and \NULL{} on
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001595failure.
1596\end{cfuncdesc}
1597
1598\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001599Returns a new long object with the value \var{v} on success, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001600\NULL{} on failure.
1601\end{cfuncdesc}
1602
1603\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001604Returns a new long object with the value \var{v} on success, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001605\NULL{} on failure.
1606\end{cfuncdesc}
1607
1608\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
1609Returns a new empty dictionary on success, and \NULL{} on
1610failure.
1611\end{cfuncdesc}
1612
1613\begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v}
Fred Drakee058b4f1998-02-16 06:15:35 +00001614Returns a new string object with the value \var{v} on success, and
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001615\NULL{} on failure.
1616\end{cfuncdesc}
1617
Fred Drakee058b4f1998-02-16 06:15:35 +00001618\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int len}
1619Returns a new string object with the value \var{v} and length
1620\var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{},
1621the contents of the string are uninitialized.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001622\end{cfuncdesc}
1623
Fred Drakee058b4f1998-02-16 06:15:35 +00001624\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
1625Returns a new tuple of length \var{len} on success, and \NULL{} on
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001626failure.
1627\end{cfuncdesc}
1628
1629
1630\chapter{Concrete Objects Layer}
1631
1632The functions in this chapter are specific to certain Python object
1633types. Passing them an object of the wrong type is not a good idea;
1634if you receive an object from a Python program and you are not sure
1635that it has the right type, you must perform a type check first;
1636e.g. to check that an object is a dictionary, use
Fred Drakee5bf8b21998-02-12 21:22:28 +00001637\cfunction{PyDict_Check()}. The chapter is structured like the
1638``family tree'' of Python object types.
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001639
1640
Fred Drakee5bf8b21998-02-12 21:22:28 +00001641\section{Fundamental Objects}
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001642
Fred Drakee5bf8b21998-02-12 21:22:28 +00001643This section describes Python type objects and the singleton object
1644\code{None}.
1645
1646
1647\subsection{Type Objects}
1648
1649\begin{ctypedesc}{PyTypeObject}
1650
1651\end{ctypedesc}
1652
1653\begin{cvardesc}{PyObject *}{PyType_Type}
1654
1655\end{cvardesc}
1656
1657
1658\subsection{The None Object}
1659
1660\begin{cvardesc}{PyObject *}{Py_None}
1661XXX macro
1662\end{cvardesc}
1663
1664
1665\section{Sequence Objects}
1666
1667Generic operations on sequence objects were discussed in the previous
1668chapter; this section deals with the specific kinds of sequence
1669objects that are intrinsic to the Python language.
1670
1671
1672\subsection{String Objects}
1673
1674\begin{ctypedesc}{PyStringObject}
1675This subtype of \code{PyObject} represents a Python string object.
1676\end{ctypedesc}
1677
1678\begin{cvardesc}{PyTypeObject}{PyString_Type}
1679This instance of \code{PyTypeObject} represents the Python string type.
1680\end{cvardesc}
1681
1682\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
1683
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001684\end{cfuncdesc}
1685
Fred Drakee5bf8b21998-02-12 21:22:28 +00001686\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
1687
Guido van Rossum9231c8f1997-05-15 21:43:21 +00001688\end{cfuncdesc}
1689
Fred Drakee5bf8b21998-02-12 21:22:28 +00001690\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
1691
Guido van Rossumae110af1997-05-22 20:11:52 +00001692\end{cfuncdesc}
1693
Fred Drakee5bf8b21998-02-12 21:22:28 +00001694\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
1695
Guido van Rossumae110af1997-05-22 20:11:52 +00001696\end{cfuncdesc}
1697
Fred Drakee5bf8b21998-02-12 21:22:28 +00001698\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
1699
1700\end{cfuncdesc}
1701
1702\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
1703
1704\end{cfuncdesc}
1705
1706\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
1707
1708\end{cfuncdesc}
1709
1710\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
1711
1712\end{cfuncdesc}
1713
1714\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
1715
1716\end{cfuncdesc}
1717
1718\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
1719
1720\end{cfuncdesc}
1721
1722\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
1723
1724\end{cfuncdesc}
1725
1726\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
1727
1728\end{cfuncdesc}
1729
1730\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
1731
1732\end{cfuncdesc}
1733
1734
1735\subsection{Tuple Objects}
1736
1737\begin{ctypedesc}{PyTupleObject}
1738This subtype of \code{PyObject} represents a Python tuple object.
1739\end{ctypedesc}
1740
1741\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
1742This instance of \code{PyTypeObject} represents the Python tuple type.
1743\end{cvardesc}
1744
1745\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
1746Return true if the argument is a tuple object.
1747\end{cfuncdesc}
1748
1749\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
Fred Drakee058b4f1998-02-16 06:15:35 +00001750Return a new tuple object of size \var{s}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001751\end{cfuncdesc}
1752
1753\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001754Takes a pointer to a tuple object, and returns the size
Fred Drakee5bf8b21998-02-12 21:22:28 +00001755of that tuple.
1756\end{cfuncdesc}
1757
1758\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
Fred Drakee058b4f1998-02-16 06:15:35 +00001759Returns the object at position \var{pos} in the tuple pointed
1760to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
1761raises an \exception{IndexError} exception.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001762\end{cfuncdesc}
1763
1764\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
Fred Drakee058b4f1998-02-16 06:15:35 +00001765Does the same, but does no checking of its arguments.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001766\end{cfuncdesc}
1767
1768\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
1769 int low,
1770 int high}
Fred Drakee058b4f1998-02-16 06:15:35 +00001771Takes a slice of the tuple pointed to by \var{p} from
1772\var{low} to \var{high} and returns it as a new tuple.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001773\end{cfuncdesc}
1774
1775\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
1776 int pos,
1777 PyObject *o}
Fred Drakee058b4f1998-02-16 06:15:35 +00001778Inserts a reference to object \var{o} at position \var{pos} of
1779the tuple pointed to by \var{p}. It returns \code{0} on success.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001780\end{cfuncdesc}
1781
1782\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
1783 int pos,
1784 PyObject *o}
1785
Fred Drakee058b4f1998-02-16 06:15:35 +00001786Does the same, but does no error checking, and
Fred Drakee5bf8b21998-02-12 21:22:28 +00001787should \emph{only} be used to fill in brand new tuples.
1788\end{cfuncdesc}
1789
1790\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
1791 int new,
1792 int last_is_sticky}
Fred Drakee058b4f1998-02-16 06:15:35 +00001793Can be used to resize a tuple. Because tuples are
Fred Drakee5bf8b21998-02-12 21:22:28 +00001794\emph{supposed} to be immutable, this should only be used if there is only
1795one module referencing the object. Do \emph{not} use this if the tuple may
Fred Drakee058b4f1998-02-16 06:15:35 +00001796already be known to some other part of the code. \var{last_is_sticky} is
1797a flag --- if set, the tuple will grow or shrink at the front, otherwise
Fred Drakee5bf8b21998-02-12 21:22:28 +00001798it will grow or shrink at the end. Think of this as destroying the old
1799tuple and creating a new one, only more efficiently.
1800\end{cfuncdesc}
1801
1802
1803\subsection{List Objects}
1804
1805\begin{ctypedesc}{PyListObject}
1806This subtype of \code{PyObject} represents a Python list object.
1807\end{ctypedesc}
1808
1809\begin{cvardesc}{PyTypeObject}{PyList_Type}
1810This instance of \code{PyTypeObject} represents the Python list type.
1811\end{cvardesc}
1812
1813\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001814Returns true if its argument is a \code{PyListObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001815\end{cfuncdesc}
1816
1817\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
1818
1819\end{cfuncdesc}
1820
1821\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
1822
1823\end{cfuncdesc}
1824
1825\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
1826
1827\end{cfuncdesc}
1828
1829\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
1830
1831\end{cfuncdesc}
1832
1833\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
1834
1835\end{cfuncdesc}
1836
1837\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
1838
1839\end{cfuncdesc}
1840
1841\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
1842
1843\end{cfuncdesc}
1844
1845\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
1846
1847\end{cfuncdesc}
1848
1849\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
1850
1851\end{cfuncdesc}
1852
1853\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
1854
1855\end{cfuncdesc}
1856
1857\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
1858
1859\end{cfuncdesc}
1860
1861\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
1862
1863\end{cfuncdesc}
1864
1865\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
1866
1867\end{cfuncdesc}
1868
1869
1870\section{Mapping Objects}
1871
1872\subsection{Dictionary Objects}
1873
1874\begin{ctypedesc}{PyDictObject}
1875This subtype of \code{PyObject} represents a Python dictionary object.
1876\end{ctypedesc}
1877
1878\begin{cvardesc}{PyTypeObject}{PyDict_Type}
1879This instance of \code{PyTypeObject} represents the Python dictionary type.
1880\end{cvardesc}
1881
1882\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001883Returns true if its argument is a \code{PyDictObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001884\end{cfuncdesc}
1885
1886\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
Fred Drakee058b4f1998-02-16 06:15:35 +00001887Returns a new empty dictionary.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001888\end{cfuncdesc}
1889
1890\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001891Empties an existing dictionary of all key/value pairs.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001892\end{cfuncdesc}
1893
1894\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
1895 PyObject *key,
1896 PyObject *val}
Fred Drakee058b4f1998-02-16 06:15:35 +00001897Inserts \var{value} into the dictionary with a key of \var{key}. Both
1898\var{key} and \var{value} should be PyObjects, and \var{key} should be
1899hashable.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001900\end{cfuncdesc}
1901
1902\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
1903 char *key,
1904 PyObject *val}
Fred Drakee058b4f1998-02-16 06:15:35 +00001905Inserts \var{value} into the dictionary using \var{key}
1906as a key. \var{key} should be a \code{char *}. The key object is
1907created using \code{PyString_FromString(\var{key})}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001908\end{cfuncdesc}
1909
1910\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001911Removes the entry in dictionary \var{p} with key \var{key}.
1912\var{key} is a PyObject.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001913\end{cfuncdesc}
1914
1915\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001916Removes the entry in dictionary \var{p} which has a key
1917specified by the \code{char *}\var{key}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001918\end{cfuncdesc}
1919
1920\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001921Returns the object from dictionary \var{p} which has a key
1922\var{key}. Returns \NULL{} if the key \var{key} is not present.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001923\end{cfuncdesc}
1924
1925\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
Fred Drakee058b4f1998-02-16 06:15:35 +00001926Does the same, but \var{key} is specified as a
Fred Drakee5bf8b21998-02-12 21:22:28 +00001927\code{char *}, rather than a \code{PyObject *}.
1928\end{cfuncdesc}
1929
1930\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001931Returns a \code{PyListObject} containing all the items
1932from the dictionary, as in the mapping method \method{items()} (see
1933the \emph{Python Library Reference}).
Fred Drakee5bf8b21998-02-12 21:22:28 +00001934\end{cfuncdesc}
1935
1936\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001937Returns a \code{PyListObject} containing all the keys
1938from the dictionary, as in the mapping method \method{keys()} (see the
1939\emph{Python Library Reference}).
Fred Drakee5bf8b21998-02-12 21:22:28 +00001940\end{cfuncdesc}
1941
1942\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001943Returns a \code{PyListObject} containing all the values
1944from the dictionary \var{p}, as in the mapping method
1945\method{values()} (see the \emph{Python Library Reference}).
Fred Drakee5bf8b21998-02-12 21:22:28 +00001946\end{cfuncdesc}
1947
1948\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00001949Returns the number of items in the dictionary.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001950\end{cfuncdesc}
1951
1952\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
1953 int ppos,
1954 PyObject **pkey,
1955 PyObject **pvalue}
1956
1957\end{cfuncdesc}
1958
1959
1960\section{Numeric Objects}
1961
1962\subsection{Plain Integer Objects}
1963
1964\begin{ctypedesc}{PyIntObject}
1965This subtype of \code{PyObject} represents a Python integer object.
1966\end{ctypedesc}
1967
1968\begin{cvardesc}{PyTypeObject}{PyInt_Type}
1969This instance of \code{PyTypeObject} represents the Python plain
1970integer type.
1971\end{cvardesc}
1972
1973\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
1974
1975\end{cfuncdesc}
1976
1977\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
Fred Drakee058b4f1998-02-16 06:15:35 +00001978Creates a new integer object with a value of \var{ival}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001979
1980The current implementation keeps an array of integer objects for all
Fred Drakee058b4f1998-02-16 06:15:35 +00001981integers between \code{-1} and \code{100}, when you create an int in
1982that range you actually just get back a reference to the existing
1983object. So it should be possible to change the value of \code{1}. I
1984suspect the behaviour of python in this case is undefined. :-)
Fred Drakee5bf8b21998-02-12 21:22:28 +00001985\end{cfuncdesc}
1986
1987\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
Fred Drakee058b4f1998-02-16 06:15:35 +00001988Returns the value of the object \var{io}. No error checking is
1989performed.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001990\end{cfuncdesc}
1991
1992\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
Fred Drakee058b4f1998-02-16 06:15:35 +00001993Will first attempt to cast the object to a \code{PyIntObject}, if
1994it is not already one, and then return its value.
Fred Drakee5bf8b21998-02-12 21:22:28 +00001995\end{cfuncdesc}
1996
1997\begin{cfuncdesc}{long}{PyInt_GetMax}{}
Fred Drakee058b4f1998-02-16 06:15:35 +00001998Returns the systems idea of the largest integer it can handle
1999(\constant{LONG_MAX}, as defined in the system header files).
Fred Drakee5bf8b21998-02-12 21:22:28 +00002000\end{cfuncdesc}
2001
2002
2003\subsection{Long Integer Objects}
2004
2005\begin{ctypedesc}{PyLongObject}
Fred Drakee058b4f1998-02-16 06:15:35 +00002006This subtype of \code{PyObject} represents a Python long integer
2007object.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002008\end{ctypedesc}
2009
2010\begin{cvardesc}{PyTypeObject}{PyLong_Type}
Fred Drakee058b4f1998-02-16 06:15:35 +00002011This instance of \code{PyTypeObject} represents the Python long
2012integer type.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002013\end{cvardesc}
2014
2015\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002016Returns true if its argument is a \code{PyLongObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002017\end{cfuncdesc}
2018
2019\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
2020
2021\end{cfuncdesc}
2022
2023\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
2024
2025\end{cfuncdesc}
2026
2027\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
2028
2029\end{cfuncdesc}
2030
2031\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
2032
2033\end{cfuncdesc}
2034
2035\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
2036
2037\end{cfuncdesc}
2038
2039\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
2040
2041\end{cfuncdesc}
2042
2043\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
2044
2045\end{cfuncdesc}
2046
2047
2048\subsection{Floating Point Objects}
2049
2050\begin{ctypedesc}{PyFloatObject}
Fred Drakee058b4f1998-02-16 06:15:35 +00002051This subtype of \code{PyObject} represents a Python floating point
2052object.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002053\end{ctypedesc}
2054
2055\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
Fred Drakee058b4f1998-02-16 06:15:35 +00002056This instance of \code{PyTypeObject} represents the Python floating
Fred Drakee5bf8b21998-02-12 21:22:28 +00002057point type.
2058\end{cvardesc}
2059
2060\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002061Returns true if its argument is a \code{PyFloatObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002062\end{cfuncdesc}
2063
2064\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
2065
2066\end{cfuncdesc}
2067
2068\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
2069
2070\end{cfuncdesc}
2071
2072\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
2073
2074\end{cfuncdesc}
2075
2076
2077\subsection{Complex Number Objects}
2078
2079\begin{ctypedesc}{Py_complex}
Fred Drakee058b4f1998-02-16 06:15:35 +00002080\begin{verbatim}
Fred Drakee5bf8b21998-02-12 21:22:28 +00002081typedef struct {
2082 double real;
2083 double imag;
2084}
Fred Drakee058b4f1998-02-16 06:15:35 +00002085\end{verbatim}
2086
2087The \C{} structure which corresponds to the value portion of a Python
2088complex number object. Most of the functions for dealing with complex
2089number objects use structures of this type as input or output values,
2090as appropriate.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002091\end{ctypedesc}
2092
2093\begin{ctypedesc}{PyComplexObject}
2094This subtype of \code{PyObject} represents a Python complex number object.
2095\end{ctypedesc}
2096
2097\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
2098This instance of \code{PyTypeObject} represents the Python complex
2099number type.
2100\end{cvardesc}
2101
2102\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002103Returns true if its argument is a \code{PyComplexObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002104\end{cfuncdesc}
2105
2106\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
2107
2108\end{cfuncdesc}
2109
2110\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
2111
2112\end{cfuncdesc}
2113
2114\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
2115
2116\end{cfuncdesc}
2117
2118\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
2119
2120\end{cfuncdesc}
2121
2122\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
2123
2124\end{cfuncdesc}
2125
2126\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
2127
2128\end{cfuncdesc}
2129
2130\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
2131
2132\end{cfuncdesc}
2133
2134\begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
2135
2136\end{cfuncdesc}
2137
2138\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
2139
2140\end{cfuncdesc}
2141
2142\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
2143
2144\end{cfuncdesc}
2145
2146\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
2147
2148\end{cfuncdesc}
2149
2150
2151
2152\section{Other Objects}
2153
2154\subsection{File Objects}
2155
2156\begin{ctypedesc}{PyFileObject}
2157This subtype of \code{PyObject} represents a Python file object.
2158\end{ctypedesc}
2159
2160\begin{cvardesc}{PyTypeObject}{PyFile_Type}
2161This instance of \code{PyTypeObject} represents the Python file type.
2162\end{cvardesc}
2163
2164\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002165Returns true if its argument is a \code{PyFileObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002166\end{cfuncdesc}
2167
2168\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
Fred Drakee058b4f1998-02-16 06:15:35 +00002169Creates a new \code{PyFileObject} pointing to the file
2170specified in \var{name} with the mode specified in \var{mode}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002171\end{cfuncdesc}
2172
2173\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
2174 char *name, char *mode, int (*close})
Fred Drakee058b4f1998-02-16 06:15:35 +00002175Creates a new \code{PyFileObject} from the already-open \var{fp}.
2176The function \var{close} will be called when the file should be
2177closed.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002178\end{cfuncdesc}
2179
2180\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002181Returns the file object associated with \var{p} as a \code{FILE *}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002182\end{cfuncdesc}
2183
2184\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
2185undocumented as yet
2186\end{cfuncdesc}
2187
2188\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002189Returns the name of the file specified by \var{p} as a
2190\code{PyStringObject}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002191\end{cfuncdesc}
2192
2193\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
Fred Drakee058b4f1998-02-16 06:15:35 +00002194Available on systems with \cfunction{setvbuf()} only. This should
2195only be called immediately after file object creation.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002196\end{cfuncdesc}
2197
2198\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
Fred Drakee058b4f1998-02-16 06:15:35 +00002199Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
2200Returns the previosu value. This function clears any errors, and will
2201return \code{0} as the previous value if the attribute either does not
2202exist or if there were errors in retrieving it. There is no way to
2203detect errors from this function, but doing so should not be needed.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002204\end{cfuncdesc}
2205
2206\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002207Writes object \var{obj} to file object \var{p}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002208\end{cfuncdesc}
2209
2210\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
Fred Drakee058b4f1998-02-16 06:15:35 +00002211Writes string \var{s} to file object \var{p}.
Fred Drakee5bf8b21998-02-12 21:22:28 +00002212\end{cfuncdesc}
2213
2214
2215\subsection{CObjects}
2216
2217XXX
2218
2219
Guido van Rossum4a944d71997-08-14 20:35:38 +00002220\chapter{Initialization, Finalization, and Threads}
2221
Guido van Rossum4a944d71997-08-14 20:35:38 +00002222\begin{cfuncdesc}{void}{Py_Initialize}{}
2223Initialize the Python interpreter. In an application embedding
2224Python, this should be called before using any other Python/C API
Fred Drakee058b4f1998-02-16 06:15:35 +00002225functions; with the exception of \cfunction{Py_SetProgramName()},
2226\cfunction{PyEval_InitThreads()}, \cfunction{PyEval_ReleaseLock()},
2227and \cfunction{PyEval_AcquireLock()}. This initializes the table of
2228loaded modules (\code{sys.modules}), and creates the fundamental
2229modules \module{__builtin__}, \module{__main__} and \module{sys}. It
2230also initializes the module search path (\code{sys.path}). It does
2231not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for that.
2232This is a no-op when called for a second time (without calling
2233\cfunction{Py_Finalize()} first). There is no return value; it is a
2234fatal error if the initialization fails.
Guido van Rossum42cefd01997-10-05 15:27:29 +00002235\end{cfuncdesc}
2236
2237\begin{cfuncdesc}{int}{Py_IsInitialized}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002238\strong{(NEW in 1.5a4!)}
Guido van Rossum42cefd01997-10-05 15:27:29 +00002239Return true (nonzero) when the Python interpreter has been
Fred Drakee058b4f1998-02-16 06:15:35 +00002240initialized, false (zero) if not. After \cfunction{Py_Finalize()} is
2241called, this returns false until \cfunction{Py_Initialize()} is called
Guido van Rossum42cefd01997-10-05 15:27:29 +00002242again.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002243\end{cfuncdesc}
2244
2245\begin{cfuncdesc}{void}{Py_Finalize}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002246\strong{(NEW in 1.5a3!)}
Fred Drakee058b4f1998-02-16 06:15:35 +00002247Undo all initializations made by \cfunction{Py_Initialize()} and
2248subsequent use of Python/C API functions, and destroy all
2249sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
2250created and not yet destroyed since the last call to
2251\cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
2252by the Python interpreter. This is a no-op when called for a second
2253time (without calling \cfunction{Py_Initialize()} again first). There
2254is no return value; errors during finalization are ignored.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002255
2256This function is provided for a number of reasons. An embedding
2257application might want to restart Python without having to restart the
2258application itself. An application that has loaded the Python
2259interpreter from a dynamically loadable library (or DLL) might want to
2260free all memory allocated by Python before unloading the DLL. During a
2261hunt for memory leaks in an application a developer might want to free
2262all memory allocated by Python before exiting from the application.
2263
Fred Drakee058b4f1998-02-16 06:15:35 +00002264\strong{Bugs and caveats:} The destruction of modules and objects in
Guido van Rossum4a944d71997-08-14 20:35:38 +00002265modules is done in random order; this may cause destructors
Fred Drakee058b4f1998-02-16 06:15:35 +00002266(\method{__del__()} methods) to fail when they depend on other objects
Guido van Rossum4a944d71997-08-14 20:35:38 +00002267(even functions) or modules. Dynamically loaded extension modules
2268loaded by Python are not unloaded. Small amounts of memory allocated
2269by the Python interpreter may not be freed (if you find a leak, please
2270report it). Memory tied up in circular references between objects is
2271not freed. Some memory allocated by extension modules may not be
2272freed. Some extension may not work properly if their initialization
2273routine is called more than once; this can happen if an applcation
Fred Drakee058b4f1998-02-16 06:15:35 +00002274calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
2275than once.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002276\end{cfuncdesc}
2277
2278\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002279\strong{(NEW in 1.5a3!)}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002280Create a new sub-interpreter. This is an (almost) totally separate
2281environment for the execution of Python code. In particular, the new
2282interpreter has separate, independent versions of all imported
Fred Drakee058b4f1998-02-16 06:15:35 +00002283modules, including the fundamental modules \module{__builtin__},
2284\module{__main__} and \module{sys}. The table of loaded modules
Guido van Rossum4a944d71997-08-14 20:35:38 +00002285(\code{sys.modules}) and the module search path (\code{sys.path}) are
2286also separate. The new environment has no \code{sys.argv} variable.
2287It has new standard I/O stream file objects \code{sys.stdin},
2288\code{sys.stdout} and \code{sys.stderr} (however these refer to the
Fred Drakeb0a78731998-01-13 18:51:10 +00002289same underlying \code{FILE} structures in the \C{} library).
Guido van Rossum4a944d71997-08-14 20:35:38 +00002290
2291The return value points to the first thread state created in the new
2292sub-interpreter. This thread state is made the current thread state.
2293Note that no actual thread is created; see the discussion of thread
2294states below. If creation of the new interpreter is unsuccessful,
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002295\NULL{} is returned; no exception is set since the exception state
Guido van Rossum4a944d71997-08-14 20:35:38 +00002296is stored in the current thread state and there may not be a current
2297thread state. (Like all other Python/C API functions, the global
2298interpreter lock must be held before calling this function and is
2299still held when it returns; however, unlike most other Python/C API
2300functions, there needn't be a current thread state on entry.)
2301
2302Extension modules are shared between (sub-)interpreters as follows:
2303the first time a particular extension is imported, it is initialized
2304normally, and a (shallow) copy of its module's dictionary is
2305squirreled away. When the same extension is imported by another
2306(sub-)interpreter, a new module is initialized and filled with the
Fred Drakee058b4f1998-02-16 06:15:35 +00002307contents of this copy; the extension's \code{init} function is not
2308called. Note that this is different from what happens when an
2309extension is imported after the interpreter has been completely
2310re-initialized by calling \cfunction{Py_Finalize()} and
2311\cfunction{Py_Initialize()}; in that case, the extension's \code{init}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002312function \emph{is} called again.
2313
Fred Drakee058b4f1998-02-16 06:15:35 +00002314\strong{Bugs and caveats:} Because sub-interpreters (and the main
Guido van Rossum4a944d71997-08-14 20:35:38 +00002315interpreter) are part of the same process, the insulation between them
Fred Drakee058b4f1998-02-16 06:15:35 +00002316isn't perfect --- for example, using low-level file operations like
Guido van Rossum4a944d71997-08-14 20:35:38 +00002317\code{os.close()} they can (accidentally or maliciously) affect each
2318other's open files. Because of the way extensions are shared between
2319(sub-)interpreters, some extensions may not work properly; this is
2320especially likely when the extension makes use of (static) global
2321variables, or when the extension manipulates its module's dictionary
2322after its initialization. It is possible to insert objects created in
2323one sub-interpreter into a namespace of another sub-interpreter; this
2324should be done with great care to avoid sharing user-defined
2325functions, methods, instances or classes between sub-interpreters,
2326since import operations executed by such objects may affect the
2327wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
2328a hard-to-fix bug that will be addressed in a future release.)
2329\end{cfuncdesc}
2330
2331\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002332\strong{(NEW in 1.5a3!)}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002333Destroy the (sub-)interpreter represented by the given thread state.
2334The given thread state must be the current thread state. See the
2335discussion of thread states below. When the call returns, the current
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002336thread state is \NULL{}. All thread states associated with this
Guido van Rossum4a944d71997-08-14 20:35:38 +00002337interpreted are destroyed. (The global interpreter lock must be held
2338before calling this function and is still held when it returns.)
Fred Drakee058b4f1998-02-16 06:15:35 +00002339\cfunction{Py_Finalize()} will destroy all sub-interpreters that haven't
Guido van Rossum4a944d71997-08-14 20:35:38 +00002340been explicitly destroyed at that point.
2341\end{cfuncdesc}
2342
2343\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002344\strong{(NEW in 1.5a3!)}
Fred Drakee058b4f1998-02-16 06:15:35 +00002345This function should be called before \cfunction{Py_Initialize()} is called
Guido van Rossum4a944d71997-08-14 20:35:38 +00002346for the first time, if it is called at all. It tells the interpreter
Fred Drakee058b4f1998-02-16 06:15:35 +00002347the value of the \code{argv[0]} argument to the \cfunction{main()} function
2348of the program. This is used by \cfunction{Py_GetPath()} and some other
Guido van Rossum4a944d71997-08-14 20:35:38 +00002349functions below to find the Python run-time libraries relative to the
2350interpreter executable. The default value is \code{"python"}. The
2351argument should point to a zero-terminated character string in static
2352storage whose contents will not change for the duration of the
2353program's execution. No code in the Python interpreter will change
2354the contents of this storage.
2355\end{cfuncdesc}
2356
2357\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
Fred Drakee058b4f1998-02-16 06:15:35 +00002358Return the program name set with \cfunction{Py_SetProgramName()}, or the
Guido van Rossum4a944d71997-08-14 20:35:38 +00002359default. The returned string points into static storage; the caller
2360should not modify its value.
2361\end{cfuncdesc}
2362
2363\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
Fred Drakee058b4f1998-02-16 06:15:35 +00002364Return the \emph{prefix} for installed platform-independent files. This
Guido van Rossum4a944d71997-08-14 20:35:38 +00002365is derived through a number of complicated rules from the program name
Fred Drakee058b4f1998-02-16 06:15:35 +00002366set with \cfunction{Py_SetProgramName()} and some environment variables;
Guido van Rossum4a944d71997-08-14 20:35:38 +00002367for example, if the program name is \code{"/usr/local/bin/python"},
2368the prefix is \code{"/usr/local"}. The returned string points into
2369static storage; the caller should not modify its value. This
2370corresponds to the \code{prefix} variable in the top-level
Fred Drakee058b4f1998-02-16 06:15:35 +00002371\file{Makefile} and the \code{--prefix} argument to the
2372\program{configure} script at build time. The value is available to
Fred Drakeb0a78731998-01-13 18:51:10 +00002373Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
Guido van Rossum4a944d71997-08-14 20:35:38 +00002374also the next function.
2375\end{cfuncdesc}
2376
2377\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
Fred Drakee058b4f1998-02-16 06:15:35 +00002378Return the \emph{exec-prefix} for installed platform-\emph{de}pendent
Guido van Rossum4a944d71997-08-14 20:35:38 +00002379files. This is derived through a number of complicated rules from the
Fred Drakee058b4f1998-02-16 06:15:35 +00002380program name set with \cfunction{Py_SetProgramName()} and some environment
Guido van Rossum4a944d71997-08-14 20:35:38 +00002381variables; for example, if the program name is
2382\code{"/usr/local/bin/python"}, the exec-prefix is
2383\code{"/usr/local"}. The returned string points into static storage;
2384the caller should not modify its value. This corresponds to the
Fred Drakee058b4f1998-02-16 06:15:35 +00002385\code{exec_prefix} variable in the top-level \file{Makefile} and the
2386\code{--exec_prefix} argument to the \program{configure} script at build
Guido van Rossum4a944d71997-08-14 20:35:38 +00002387time. The value is available to Python code as
Fred Drakeb0a78731998-01-13 18:51:10 +00002388\code{sys.exec_prefix}. It is only useful on \UNIX{}.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002389
2390Background: The exec-prefix differs from the prefix when platform
2391dependent files (such as executables and shared libraries) are
2392installed in a different directory tree. In a typical installation,
2393platform dependent files may be installed in the
2394\code{"/usr/local/plat"} subtree while platform independent may be
2395installed in \code{"/usr/local"}.
2396
2397Generally speaking, a platform is a combination of hardware and
2398software families, e.g. Sparc machines running the Solaris 2.x
2399operating system are considered the same platform, but Intel machines
2400running Solaris 2.x are another platform, and Intel machines running
2401Linux are yet another platform. Different major revisions of the same
Fred Drakeb0a78731998-01-13 18:51:10 +00002402operating system generally also form different platforms. Non-\UNIX{}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002403operating systems are a different story; the installation strategies
2404on those systems are so different that the prefix and exec-prefix are
2405meaningless, and set to the empty string. Note that compiled Python
2406bytecode files are platform independent (but not independent from the
2407Python version by which they were compiled!).
2408
Fred Drakee058b4f1998-02-16 06:15:35 +00002409System administrators will know how to configure the \program{mount} or
2410\program{automount} programs to share \code{"/usr/local"} between platforms
Guido van Rossum4a944d71997-08-14 20:35:38 +00002411while having \code{"/usr/local/plat"} be a different filesystem for each
2412platform.
2413\end{cfuncdesc}
2414
2415\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002416\strong{(NEW in 1.5a3!)}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002417Return the full program name of the Python executable; this is
2418computed as a side-effect of deriving the default module search path
Fred Drakee058b4f1998-02-16 06:15:35 +00002419from the program name (set by \cfunction{Py_SetProgramName()} above). The
Guido van Rossum4a944d71997-08-14 20:35:38 +00002420returned string points into static storage; the caller should not
2421modify its value. The value is available to Python code as
Guido van Rossum42cefd01997-10-05 15:27:29 +00002422\code{sys.executable}.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002423\end{cfuncdesc}
2424
2425\begin{cfuncdesc}{char *}{Py_GetPath}{}
2426Return the default module search path; this is computed from the
Fred Drakee058b4f1998-02-16 06:15:35 +00002427program name (set by \cfunction{Py_SetProgramName()} above) and some
Guido van Rossum4a944d71997-08-14 20:35:38 +00002428environment variables. The returned string consists of a series of
2429directory names separated by a platform dependent delimiter character.
Fred Drakee5bc4971998-02-12 23:36:49 +00002430The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
2431DOS/Windows, and \code{'\\n'} (the \ASCII{} newline character) on
2432Macintosh. The returned string points into static storage; the caller
Guido van Rossum4a944d71997-08-14 20:35:38 +00002433should not modify its value. The value is available to Python code
2434as the list \code{sys.path}, which may be modified to change the
2435future search path for loaded modules.
2436
2437% XXX should give the exact rules
2438\end{cfuncdesc}
2439
2440\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
2441Return the version of this Python interpreter. This is a string that
2442looks something like
2443
Guido van Rossum09270b51997-08-15 18:57:32 +00002444\begin{verbatim}
Fred Drakee058b4f1998-02-16 06:15:35 +00002445"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
Guido van Rossum09270b51997-08-15 18:57:32 +00002446\end{verbatim}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002447
2448The first word (up to the first space character) is the current Python
2449version; the first three characters are the major and minor version
2450separated by a period. The returned string points into static storage;
2451the caller should not modify its value. The value is available to
2452Python code as the list \code{sys.version}.
2453\end{cfuncdesc}
2454
2455\begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
Fred Drakeb0a78731998-01-13 18:51:10 +00002456Return the platform identifier for the current platform. On \UNIX{},
Guido van Rossum4a944d71997-08-14 20:35:38 +00002457this is formed from the ``official'' name of the operating system,
2458converted to lower case, followed by the major revision number; e.g.,
2459for Solaris 2.x, which is also known as SunOS 5.x, the value is
2460\code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
2461is \code{"win"}. The returned string points into static storage;
2462the caller should not modify its value. The value is available to
2463Python code as \code{sys.platform}.
2464\end{cfuncdesc}
2465
2466\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
2467Return the official copyright string for the current Python version,
2468for example
2469
2470\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
2471
2472The returned string points into static storage; the caller should not
2473modify its value. The value is available to Python code as the list
2474\code{sys.copyright}.
2475\end{cfuncdesc}
2476
2477\begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
2478Return an indication of the compiler used to build the current Python
Fred Drakee058b4f1998-02-16 06:15:35 +00002479version, in square brackets, for example:
Guido van Rossum4a944d71997-08-14 20:35:38 +00002480
Fred Drakee058b4f1998-02-16 06:15:35 +00002481\begin{verbatim}
2482"[GCC 2.7.2.2]"
2483\end{verbatim}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002484
2485The returned string points into static storage; the caller should not
2486modify its value. The value is available to Python code as part of
2487the variable \code{sys.version}.
2488\end{cfuncdesc}
2489
2490\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
2491Return information about the sequence number and build date and time
2492of the current Python interpreter instance, for example
2493
Guido van Rossum09270b51997-08-15 18:57:32 +00002494\begin{verbatim}
2495"#67, Aug 1 1997, 22:34:28"
2496\end{verbatim}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002497
2498The returned string points into static storage; the caller should not
2499modify its value. The value is available to Python code as part of
2500the variable \code{sys.version}.
2501\end{cfuncdesc}
2502
2503\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
2504% XXX
2505\end{cfuncdesc}
2506
2507% XXX Other PySys thingies (doesn't really belong in this chapter)
2508
2509\section{Thread State and the Global Interpreter Lock}
2510
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002511The Python interpreter is not fully thread safe. In order to support
2512multi-threaded Python programs, there's a global lock that must be
2513held by the current thread before it can safely access Python objects.
2514Without the lock, even the simplest operations could cause problems in
2515a multi-threaded proram: for example, when two threads simultaneously
2516increment the reference count of the same object, the reference count
2517could end up being incremented only once instead of twice.
2518
2519Therefore, the rule exists that only the thread that has acquired the
2520global interpreter lock may operate on Python objects or call Python/C
2521API functions. In order to support multi-threaded Python programs,
Fred Drakee058b4f1998-02-16 06:15:35 +00002522the interpreter regularly release and reacquires the lock --- by
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002523default, every ten bytecode instructions (this can be changed with
Fred Drakee058b4f1998-02-16 06:15:35 +00002524\function{sys.setcheckinterval()}). The lock is also released and
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002525reacquired around potentially blocking I/O operations like reading or
2526writing a file, so that other threads can run while the thread that
2527requests the I/O is waiting for the I/O operation to complete.
2528
2529The Python interpreter needs to keep some bookkeeping information
Fred Drakee058b4f1998-02-16 06:15:35 +00002530separate per thread --- for this it uses a data structure called
2531\code{PyThreadState}. This is new in Python 1.5; in earlier versions,
2532such state was stored in global variables, and switching threads could
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002533cause problems. In particular, exception handling is now thread safe,
Fred Drakee058b4f1998-02-16 06:15:35 +00002534when the application uses \function{sys.exc_info()} to access the
2535exception last raised in the current thread.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002536
2537There's one global variable left, however: the pointer to the current
Fred Drakee058b4f1998-02-16 06:15:35 +00002538\code{PyThreadState} structure. While most thread packages have a way
2539to store ``per-thread global data'', Python's internal platform
2540independent thread abstraction doesn't support this yet. Therefore,
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002541the current thread state must be manipulated explicitly.
2542
2543This is easy enough in most cases. Most code manipulating the global
2544interpreter lock has the following simple structure:
2545
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002546\begin{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002547Save the thread state in a local variable.
2548Release the interpreter lock.
2549...Do some blocking I/O operation...
2550Reacquire the interpreter lock.
2551Restore the thread state from the local variable.
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002552\end{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002553
2554This is so common that a pair of macros exists to simplify it:
2555
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002556\begin{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002557Py_BEGIN_ALLOW_THREADS
2558...Do some blocking I/O operation...
2559Py_END_ALLOW_THREADS
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002560\end{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002561
Fred Drakee058b4f1998-02-16 06:15:35 +00002562The \code{Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares
2563a hidden local variable; the \code{Py_END_ALLOW_THREADS} macro closes
2564the block. Another advantage of using these two macros is that when
2565Python is compiled without thread support, they are defined empty,
2566thus saving the thread state and lock manipulations.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002567
2568When thread support is enabled, the block above expands to the
2569following code:
2570
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002571\begin{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002572{
2573 PyThreadState *_save;
2574 _save = PyEval_SaveThread();
2575 ...Do some blocking I/O operation...
2576 PyEval_RestoreThread(_save);
2577}
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002578\end{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002579
2580Using even lower level primitives, we can get roughly the same effect
2581as follows:
2582
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002583\begin{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002584{
2585 PyThreadState *_save;
2586 _save = PyThreadState_Swap(NULL);
2587 PyEval_ReleaseLock();
2588 ...Do some blocking I/O operation...
2589 PyEval_AcquireLock();
2590 PyThreadState_Swap(_save);
2591}
Guido van Rossum9faf4c51997-10-07 14:38:54 +00002592\end{verbatim}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002593
2594There are some subtle differences; in particular,
Fred Drakee058b4f1998-02-16 06:15:35 +00002595\cfunction{PyEval_RestoreThread()} saves and restores the value of the
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002596global variable \code{errno}, since the lock manipulation does not
2597guarantee that \code{errno} is left alone. Also, when thread support
Fred Drakee058b4f1998-02-16 06:15:35 +00002598is disabled, \cfunction{PyEval_SaveThread()} and
2599\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
2600case, \cfunction{PyEval_ReleaseLock()} and
2601\cfunction{PyEval_AcquireLock()} are not available. This is done so
2602that dynamically loaded extensions compiled with thread support
2603enabled can be loaded by an interpreter that was compiled with
2604disabled thread support.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002605
2606The global interpreter lock is used to protect the pointer to the
2607current thread state. When releasing the lock and saving the thread
2608state, the current thread state pointer must be retrieved before the
2609lock is released (since another thread could immediately acquire the
2610lock and store its own thread state in the global variable).
2611Reversely, when acquiring the lock and restoring the thread state, the
2612lock must be acquired before storing the thread state pointer.
2613
2614Why am I going on with so much detail about this? Because when
Fred Drakeb0a78731998-01-13 18:51:10 +00002615threads are created from \C{}, they don't have the global interpreter
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002616lock, nor is there a thread state data structure for them. Such
2617threads must bootstrap themselves into existence, by first creating a
2618thread state data structure, then acquiring the lock, and finally
2619storing their thread state pointer, before they can start using the
2620Python/C API. When they are done, they should reset the thread state
2621pointer, release the lock, and finally free their thread state data
2622structure.
2623
2624When creating a thread data structure, you need to provide an
2625interpreter state data structure. The interpreter state data
2626structure hold global data that is shared by all threads in an
2627interpreter, for example the module administration
2628(\code{sys.modules}). Depending on your needs, you can either create
2629a new interpreter state data structure, or share the interpreter state
2630data structure used by the Python main thread (to access the latter,
2631you must obtain the thread state and access its \code{interp} member;
2632this must be done by a thread that is created by Python or by the main
2633thread after Python is initialized).
2634
2635XXX More?
2636
2637\begin{ctypedesc}{PyInterpreterState}
2638\strong{(NEW in 1.5a3!)}
2639This data structure represents the state shared by a number of
2640cooperating threads. Threads belonging to the same interpreter
2641share their module administration and a few other internal items.
2642There are no public members in this structure.
2643
2644Threads belonging to different interpreters initially share nothing,
2645except process state like available memory, open file descriptors and
2646such. The global interpreter lock is also shared by all threads,
2647regardless of to which interpreter they belong.
2648\end{ctypedesc}
2649
2650\begin{ctypedesc}{PyThreadState}
2651\strong{(NEW in 1.5a3!)}
2652This data structure represents the state of a single thread. The only
2653public data member is \code{PyInterpreterState *interp}, which points
2654to this thread's interpreter state.
2655\end{ctypedesc}
2656
2657\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
2658Initialize and acquire the global interpreter lock. It should be
2659called in the main thread before creating a second thread or engaging
Fred Drakee058b4f1998-02-16 06:15:35 +00002660in any other thread operations such as
2661\cfunction{PyEval_ReleaseLock()} or
2662\code{PyEval_ReleaseThread(\var{tstate})}. It is not needed before
2663calling \cfunction{PyEval_SaveThread()} or
2664\cfunction{PyEval_RestoreThread()}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002665
2666This is a no-op when called for a second time. It is safe to call
Fred Drakee058b4f1998-02-16 06:15:35 +00002667this function before calling \cfunction{Py_Initialize()}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002668
2669When only the main thread exists, no lock operations are needed. This
2670is a common situation (most Python programs do not use threads), and
2671the lock operations slow the interpreter down a bit. Therefore, the
2672lock is not created initially. This situation is equivalent to having
2673acquired the lock: when there is only a single thread, all object
2674accesses are safe. Therefore, when this function initializes the
Fred Drakee058b4f1998-02-16 06:15:35 +00002675lock, it also acquires it. Before the Python \module{thread} module
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002676creates a new thread, knowing that either it has the lock or the lock
Fred Drakee058b4f1998-02-16 06:15:35 +00002677hasn't been created yet, it calls \cfunction{PyEval_InitThreads()}.
2678When this call returns, it is guaranteed that the lock has been
2679created and that it has acquired it.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002680
2681It is \strong{not} safe to call this function when it is unknown which
2682thread (if any) currently has the global interpreter lock.
2683
2684This function is not available when thread support is disabled at
2685compile time.
2686\end{cfuncdesc}
2687
Guido van Rossum4a944d71997-08-14 20:35:38 +00002688\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002689\strong{(NEW in 1.5a3!)}
2690Acquire the global interpreter lock. The lock must have been created
2691earlier. If this thread already has the lock, a deadlock ensues.
2692This function is not available when thread support is disabled at
2693compile time.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002694\end{cfuncdesc}
2695
2696\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002697\strong{(NEW in 1.5a3!)}
2698Release the global interpreter lock. The lock must have been created
2699earlier. This function is not available when thread support is
Fred Drakee058b4f1998-02-16 06:15:35 +00002700disabled at compile time.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002701\end{cfuncdesc}
2702
2703\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002704\strong{(NEW in 1.5a3!)}
2705Acquire the global interpreter lock and then set the current thread
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002706state to \var{tstate}, which should not be \NULL{}. The lock must
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002707have been created earlier. If this thread already has the lock,
2708deadlock ensues. This function is not available when thread support
Fred Drakee058b4f1998-02-16 06:15:35 +00002709is disabled at compile time.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002710\end{cfuncdesc}
2711
2712\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002713\strong{(NEW in 1.5a3!)}
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002714Reset the current thread state to \NULL{} and release the global
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002715interpreter lock. The lock must have been created earlier and must be
2716held by the current thread. The \var{tstate} argument, which must not
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002717be \NULL{}, is only used to check that it represents the current
Fred Drakee058b4f1998-02-16 06:15:35 +00002718thread state --- if it isn't, a fatal error is reported. This
2719function is not available when thread support is disabled at compile
2720time.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002721\end{cfuncdesc}
2722
2723\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002724\strong{(Different return type in 1.5a3!)}
2725Release the interpreter lock (if it has been created and thread
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002726support is enabled) and reset the thread state to \NULL{},
2727returning the previous thread state (which is not \NULL{}). If
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002728the lock has been created, the current thread must have acquired it.
2729(This function is available even when thread support is disabled at
2730compile time.)
Guido van Rossum4a944d71997-08-14 20:35:38 +00002731\end{cfuncdesc}
2732
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002733\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
2734\strong{(Different argument type in 1.5a3!)}
2735Acquire the interpreter lock (if it has been created and thread
2736support is enabled) and set the thread state to \var{tstate}, which
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002737must not be \NULL{}. If the lock has been created, the current
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002738thread must not have acquired it, otherwise deadlock ensues. (This
2739function is available even when thread support is disabled at compile
2740time.)
Guido van Rossum4a944d71997-08-14 20:35:38 +00002741\end{cfuncdesc}
2742
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002743% XXX These aren't really C types, but the ctypedesc macro is the simplest!
2744\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
2745This macro expands to
Fred Drakee058b4f1998-02-16 06:15:35 +00002746\samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002747Note that it contains an opening brace; it must be matched with a
2748following \code{Py_END_ALLOW_THREADS} macro. See above for further
2749discussion of this macro. It is a no-op when thread support is
2750disabled at compile time.
2751\end{ctypedesc}
2752
2753\begin{ctypedesc}{Py_END_ALLOW_THREADS}
2754This macro expands to
Fred Drakee058b4f1998-02-16 06:15:35 +00002755\samp{PyEval_RestoreThread(_save); \}}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002756Note that it contains a closing brace; it must be matched with an
2757earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
2758discussion of this macro. It is a no-op when thread support is
2759disabled at compile time.
2760\end{ctypedesc}
2761
2762\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
Fred Drakee058b4f1998-02-16 06:15:35 +00002763This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002764is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
2765brace. It is a no-op when thread support is disabled at compile
2766time.
2767\end{ctypedesc}
2768
2769\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
Fred Drakee058b4f1998-02-16 06:15:35 +00002770This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002771equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
2772and variable declaration. It is a no-op when thread support is
2773disabled at compile time.
2774\end{ctypedesc}
2775
2776All of the following functions are only available when thread support
2777is enabled at compile time, and must be called only when the
2778interpreter lock has been created. They are all new in 1.5a3.
2779
2780\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
2781Create a new interpreter state object. The interpreter lock must be
2782held.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002783\end{cfuncdesc}
2784
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002785\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
2786Reset all information in an interpreter state object. The interpreter
2787lock must be held.
Guido van Rossum4a944d71997-08-14 20:35:38 +00002788\end{cfuncdesc}
2789
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002790\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
2791Destroy an interpreter state object. The interpreter lock need not be
2792held. The interpreter state must have been reset with a previous
Fred Drakee058b4f1998-02-16 06:15:35 +00002793call to \cfunction{PyInterpreterState_Clear()}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002794\end{cfuncdesc}
2795
2796\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
2797Create a new thread state object belonging to the given interpreter
2798object. The interpreter lock must be held.
2799\end{cfuncdesc}
2800
2801\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
2802Reset all information in a thread state object. The interpreter lock
2803must be held.
2804\end{cfuncdesc}
2805
2806\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
2807Destroy a thread state object. The interpreter lock need not be
2808held. The thread state must have been reset with a previous
Fred Drakee058b4f1998-02-16 06:15:35 +00002809call to \cfunction{PyThreadState_Clear()}.
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002810\end{cfuncdesc}
2811
2812\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
2813Return the current thread state. The interpreter lock must be held.
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002814When the current thread state is \NULL{}, this issues a fatal
Guido van Rossum5b8a5231997-12-30 04:38:44 +00002815error (so that the caller needn't check for \NULL{}).
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002816\end{cfuncdesc}
2817
2818\begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
2819Swap the current thread state with the thread state given by the
Guido van Rossum580aa8d1997-11-25 15:34:51 +00002820argument \var{tstate}, which may be \NULL{}. The interpreter lock
Guido van Rossumc44d3d61997-10-06 05:10:47 +00002821must be held.
2822\end{cfuncdesc}
2823
2824
Fred Drakee058b4f1998-02-16 06:15:35 +00002825\chapter{Defining New Object Types}
Guido van Rossum4a944d71997-08-14 20:35:38 +00002826
Fred Drakee058b4f1998-02-16 06:15:35 +00002827\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
2828\end{cfuncdesc}
2829
2830\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
2831\end{cfuncdesc}
2832
2833\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
2834\end{cfuncdesc}
2835
2836\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
2837\end{cfuncdesc}
2838
Guido van Rossumae110af1997-05-22 20:11:52 +00002839
2840PyObject, PyVarObject
2841
2842PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
2843
2844Typedefs:
2845unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
2846intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
2847getreadbufferproc, getwritebufferproc, getsegcountproc,
2848destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
2849setattrofunc, cmpfunc, reprfunc, hashfunc
2850
2851PyNumberMethods
2852
2853PySequenceMethods
2854
2855PyMappingMethods
2856
2857PyBufferProcs
2858
2859PyTypeObject
2860
2861DL_IMPORT
2862
2863PyType_Type
2864
2865Py*_Check
2866
2867Py_None, _Py_NoneStruct
2868
Guido van Rossumae110af1997-05-22 20:11:52 +00002869
Fred Drakee5bf8b21998-02-12 21:22:28 +00002870\chapter{Debugging}
Guido van Rossumae110af1997-05-22 20:11:52 +00002871
Fred Drakee5bf8b21998-02-12 21:22:28 +00002872XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
Guido van Rossum5b8a5231997-12-30 04:38:44 +00002873
2874
Guido van Rossum9231c8f1997-05-15 21:43:21 +00002875\input{api.ind} % Index -- must be last
2876
2877\end{document}