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