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