| \documentclass{manual} |
| |
| \title{Python/C API Reference Manual} |
| |
| \input{boilerplate} |
| |
| \makeindex % tell \index to actually write the .idx file |
| |
| |
| \begin{document} |
| |
| \maketitle |
| |
| \ifhtml |
| \chapter*{Front Matter\label{front}} |
| \fi |
| |
| \input{copyright} |
| |
| \begin{abstract} |
| |
| \noindent |
| This manual documents the API used by C and \Cpp{} programmers who |
| want to write extension modules or embed Python. It is a companion to |
| \citetitle[../ext/ext.html]{Extending and Embedding the Python |
| Interpreter}, which describes the general principles of extension |
| writing but does not document the API functions in detail. |
| |
| \strong{Warning:} The current version of this document is incomplete. |
| I hope that it is nevertheless useful. I will continue to work on it, |
| and release new versions from time to time, independent from Python |
| source code releases. |
| |
| \end{abstract} |
| |
| \tableofcontents |
| |
| % XXX Consider moving all this back to ext.tex and giving api.tex |
| % XXX a *really* short intro only. |
| |
| \chapter{Introduction \label{intro}} |
| |
| The Application Programmer's Interface to Python gives C and |
| \Cpp{} programmers access to the Python interpreter at a variety of |
| levels. The API is equally usable from \Cpp{}, but for brevity it is |
| generally referred to as the Python/C API. There are two |
| fundamentally different reasons for using the Python/C API. The first |
| reason is to write \emph{extension modules} for specific purposes; |
| these are C modules that extend the Python interpreter. This is |
| probably the most common use. The second reason is to use Python as a |
| component in a larger application; this technique is generally |
| referred to as \dfn{embedding} Python in an application. |
| |
| Writing an extension module is a relatively well-understood process, |
| where a ``cookbook'' approach works well. There are several tools |
| that automate the process to some extent. While people have embedded |
| Python in other applications since its early existence, the process of |
| embedding Python is less straightforward than writing an extension. |
| |
| 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 \label{includes}} |
| |
| All function, type and macro definitions needed to use the Python/C |
| API are included in your code by the following line: |
| |
| \begin{verbatim} |
| #include "Python.h" |
| \end{verbatim} |
| |
| This implies inclusion of the following standard headers: |
| \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, |
| \code{<limits.h>}, and \code{<stdlib.h>} (if available). |
| |
| All user visible names defined by Python.h (except those defined by |
| the included standard headers) have one of the prefixes \samp{Py} or |
| \samp{_Py}. Names beginning with \samp{_Py} are for internal use by |
| the Python implementation and should not be used by extension writers. |
| Structure member names do not have a reserved prefix. |
| |
| \strong{Important:} user code should never define names that begin |
| with \samp{Py} or \samp{_Py}. This confuses the reader, and |
| jeopardizes the portability of the user code to future Python |
| versions, which may define additional names beginning with one of |
| these prefixes. |
| |
| The header files are typically installed with Python. On \UNIX, these |
| are located in the directories |
| \file{\envvar{prefix}/include/python\var{version}/} and |
| \file{\envvar{exec_prefix}/include/python\var{version}/}, where |
| \envvar{prefix} and \envvar{exec_prefix} are defined by the |
| corresponding parameters to Python's \program{configure} script and |
| \var{version} is \code{sys.version[:3]}. On Windows, the headers are |
| installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is |
| the installation directory specified to the installer. |
| |
| To include the headers, place both directories (if different) on your |
| compiler's search path for includes. Do \emph{not} place the parent |
| directories on the search path and then use |
| \samp{\#include <python\shortversion/Python.h>}; this will break on |
| multi-platform builds since the platform independent headers under |
| \envvar{prefix} include the platform specific headers from |
| \envvar{exec_prefix}. |
| |
| \Cpp{} users should note that though the API is defined entirely using |
| C, the header files do properly declare the entry points to be |
| \code{extern "C"}, so there is no need to do anything special to use |
| the API from \Cpp. |
| |
| |
| \section{Objects, Types and Reference Counts \label{objects}} |
| |
| Most Python/C API functions have one or more arguments as well as a |
| return value of type \ctype{PyObject*}. This type is a pointer |
| to an opaque data type representing an arbitrary Python |
| object. Since all Python object types are treated the same way by the |
| Python language in most situations (e.g., assignments, scope rules, |
| and argument passing), it is only fitting that they should be |
| represented by a single C type. Almost all Python objects live on the |
| heap: you never declare an automatic or static variable of type |
| \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can |
| be declared. The sole exception are the type objects\obindex{type}; |
| since these must never be deallocated, they are typically static |
| \ctype{PyTypeObject} objects. |
| |
| All Python objects (even Python integers) have a \dfn{type} and a |
| \dfn{reference count}. An object's type determines what kind of object |
| it is (e.g., an integer, a list, or a user-defined function; there are |
| many more as explained in the \citetitle[../ref/ref.html]{Python |
| Reference Manual}). For each of the well-known types there is a macro |
| to check whether an object is of that type; for instance, |
| \samp{PyList_Check(\var{a})} is true if (and only if) the object |
| pointed to by \var{a} is a Python list. |
| |
| |
| \subsection{Reference Counts \label{refcounts}} |
| |
| The reference count is important because today's computers have a |
| finite (and often severely limited) memory size; it counts how many |
| different places there are that have a reference to an object. Such a |
| place could be another object, or a global (or static) C variable, or |
| a local variable in some C function. When an object's reference count |
| becomes zero, the object is deallocated. If it contains references to |
| other objects, their reference count is decremented. Those other |
| objects may be deallocated in turn, if this decrement makes their |
| reference count become zero, and so on. (There's an obvious problem |
| with objects that reference each other here; for now, the solution is |
| ``don't do that.'') |
| |
| Reference counts are always manipulated explicitly. The normal way is |
| to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to |
| increment an object's reference count by one, and |
| \cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by |
| one. The \cfunction{Py_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 to be called. |
| The deallocator 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 if this |
| is a compound object type, such as a list, as well as performing any |
| additional finalization that's needed. There's no chance that the |
| reference count can overflow; at least as many bits are used to hold |
| the reference count as there are distinct memory locations in virtual |
| memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the |
| reference count increment is a simple operation. |
| |
| It is not necessary to increment an object's reference count for every |
| local variable that contains a pointer to an object. In theory, the |
| object's reference count goes up by one when the variable is made to |
| point to it and it goes down by one when the variable goes out of |
| scope. However, these two cancel each other out, so at the end the |
| reference count hasn't changed. The only real reason to use the |
| reference count is to prevent the object from being deallocated as |
| long as our variable is pointing to it. If we know that there is at |
| least one other reference to the object that lives at least as long as |
| our variable, there is no need to increment the reference count |
| temporarily. An important situation where this arises is in objects |
| that are passed as arguments to C functions in an extension module |
| that are called from Python; the call mechanism guarantees to hold a |
| reference to every argument for the duration of the call. |
| |
| However, a common pitfall is to extract an object from a list and |
| hold on to it for a while without incrementing its reference count. |
| Some other operation might conceivably remove the object from the |
| list, decrementing its reference count and possible deallocating it. |
| The real danger is that innocent-looking operations may invoke |
| arbitrary Python code which could do this; there is a code path which |
| allows control to flow back to the user from a \cfunction{Py_DECREF()}, |
| so almost any operation is potentially dangerous. |
| |
| A safe approach is to always use the generic operations (functions |
| whose name begins with \samp{PyObject_}, \samp{PyNumber_}, |
| \samp{PySequence_} or \samp{PyMapping_}). These operations always |
| increment the reference count of the object they return. This leaves |
| the caller with the responsibility to call |
| \cfunction{Py_DECREF()} when they are done with the result; this soon |
| becomes second nature. |
| |
| |
| \subsubsection{Reference Count Details \label{refcountDetails}} |
| |
| The reference count behavior of functions in the Python/C API is best |
| explained in terms of \emph{ownership of references}. Note that we |
| talk of owning references, never of owning objects; objects are always |
| shared! When a function owns a reference, it has to dispose of it |
| properly --- either by passing ownership on (usually to its caller) or |
| by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When |
| a function passes ownership of a reference on to its caller, the |
| caller is said to receive a \emph{new} reference. When no ownership |
| is transferred, the caller is said to \emph{borrow} the reference. |
| Nothing needs to be done for a borrowed reference. |
| |
| Conversely, when a calling function passes it a reference to an |
| object, there are two possibilities: the function \emph{steals} a |
| reference to the object, or it does not. Few functions steal |
| references; the two notable exceptions are |
| \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and |
| \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which |
| steal a reference to the item (but not to the tuple or list into which |
| the item is 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): |
| |
| \begin{verbatim} |
| PyObject *t; |
| |
| t = PyTuple_New(3); |
| PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); |
| PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); |
| PyTuple_SetItem(t, 2, PyString_FromString("three")); |
| \end{verbatim} |
| |
| Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to |
| set tuple items; \cfunction{PySequence_SetItem()} and |
| \cfunction{PyObject_SetItem()} refuse to do this since tuples are an |
| immutable data type. You should only use |
| \cfunction{PyTuple_SetItem()} for tuples that you are creating |
| yourself. |
| |
| Equivalent code for populating a list can be written using |
| \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code |
| can also use \cfunction{PySequence_SetItem()}; this illustrates the |
| difference between the two (the extra \cfunction{Py_DECREF()} calls): |
| |
| \begin{verbatim} |
| PyObject *l, *x; |
| |
| l = PyList_New(3); |
| x = PyInt_FromLong(1L); |
| PySequence_SetItem(l, 0, x); Py_DECREF(x); |
| x = PyInt_FromLong(2L); |
| PySequence_SetItem(l, 1, x); Py_DECREF(x); |
| x = PyString_FromString("three"); |
| PySequence_SetItem(l, 2, x); Py_DECREF(x); |
| \end{verbatim} |
| |
| You might find it strange that the ``recommended'' approach takes more |
| code. However, in practice, you will rarely use these ways of |
| creating and populating a tuple or list. There's a generic function, |
| \cfunction{Py_BuildValue()}, that can create most common objects from |
| C values, directed by a \dfn{format string}. For example, the |
| above two blocks of code could be replaced by the following (which |
| also takes care of the error checking): |
| |
| \begin{verbatim} |
| PyObject *t, *l; |
| |
| t = Py_BuildValue("(iis)", 1, 2, "three"); |
| l = Py_BuildValue("[iis]", 1, 2, "three"); |
| \end{verbatim} |
| |
| It is much more common to use \cfunction{PyObject_SetItem()} and |
| friends with items whose references you are only borrowing, like |
| arguments that were passed in to the function you are writing. In |
| that case, their behaviour regarding reference counts is much saner, |
| since you don't have to increment a reference count so you can give a |
| reference away (``have it be stolen''). For example, this function |
| sets all items of a list (actually, any mutable sequence) to a given |
| item: |
| |
| \begin{verbatim} |
| int set_all(PyObject *target, PyObject *item) |
| { |
| int i, n; |
| |
| n = PyObject_Length(target); |
| if (n < 0) |
| return -1; |
| for (i = 0; i < n; i++) { |
| if (PyObject_SetItem(target, i, item) < 0) |
| return -1; |
| } |
| return 0; |
| } |
| \end{verbatim} |
| \ttindex{set_all()} |
| |
| The situation is slightly different for function return values. |
| While passing a reference to most functions does not change your |
| ownership responsibilities for that reference, many functions that |
| return a referece to an object give you ownership of the reference. |
| The reason is simple: in many cases, the returned object is created |
| on the fly, and the reference you get is the only reference to the |
| object. Therefore, the generic functions that return object |
| references, like \cfunction{PyObject_GetItem()} and |
| \cfunction{PySequence_GetItem()}, always return a new reference (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} (the type of the type of the object passed as an |
| argument to the function) \emph{doesn't enter into it!} Thus, if you |
| extract an item from a list using \cfunction{PyList_GetItem()}, you |
| don't own the reference --- but if you obtain the same item from the |
| same list using \cfunction{PySequence_GetItem()} (which happens to |
| take exactly the same arguments), you do own a reference to the |
| returned object. |
| |
| Here is an example of how you could write a function that computes the |
| sum of the items in a list of integers; once using |
| \cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using |
| \cfunction{PySequence_GetItem()}\ttindex{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} |
| \ttindex{sum_list()} |
| |
| \begin{verbatim} |
| long sum_sequence(PyObject *sequence) |
| { |
| int i, n; |
| long total = 0; |
| PyObject *item; |
| n = PySequence_Length(sequence); |
| if (n < 0) |
| return -1; /* Has no length */ |
| for (i = 0; i < n; i++) { |
| item = PySequence_GetItem(sequence, 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} |
| \ttindex{sum_sequence()} |
| |
| |
| \subsection{Types \label{types}} |
| |
| There are few other data types that play a significant role in |
| the Python/C API; most are simple C types such as \ctype{int}, |
| \ctype{long}, \ctype{double} and \ctype{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, and another |
| is used to describe the value of a complex number. These will |
| be discussed together with the functions that use them. |
| |
| |
| \section{Exceptions \label{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, until |
| they reach the top-level interpreter, where they are reported to the |
| user accompanied by a stack traceback. |
| |
| For C programmers, however, error checking always has to be explicit. |
| All functions in the Python/C API can raise exceptions, unless an |
| explicit claim is made otherwise in a function's documentation. In |
| general, when a function encounters an error, it sets an exception, |
| discards any object references that it owns, and returns an |
| error indicator --- usually \NULL{} or \code{-1}. A few functions |
| return a Boolean true/false result, with false indicating an error. |
| Very few functions return no explicit error indicator or have an |
| ambiguous return value, and require explicit testing for errors with |
| \cfunction{PyErr_Occurred()}\ttindex{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 in one of two states: an exception has occurred, or not. |
| The function \cfunction{PyErr_Occurred()} can be used to check for |
| this: it returns a borrowed reference to the exception type object |
| when an exception has occurred, and \NULL{} otherwise. There are a |
| number of functions to set the exception state: |
| \cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most |
| common (though not the most general) function to set the exception |
| state, and \cfunction{PyErr_Clear()}\ttindex{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 |
| \withsubitem{(in module sys)}{ |
| \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
| objects \code{sys.exc_type}, \code{sys.exc_value}, and |
| \code{sys.exc_traceback}; however, they are not the same: the Python |
| objects represent the last exception being handled by a Python |
| \keyword{try} \ldots\ \keyword{except} statement, while the C level |
| exception state only exists while an exception is being passed on |
| between C functions until it reaches the Python bytecode interpreter's |
| main loop, 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 |
| \withsubitem{(in module sys)}{\ttindex{exc_info()}} |
| \function{sys.exc_info()}, which returns the per-thread exception state |
| for Python code. Also, the semantics of both ways to access the |
| exception state have changed so that a function which catches an |
| exception will save and restore its thread's exception state so as to |
| preserve the exception state of its caller. This prevents common bugs |
| in exception handling code caused by an innocent-looking function |
| overwriting the exception being handled; it also reduces the often |
| unwanted lifetime extension for objects that are referenced by the |
| stack frames in the traceback. |
| |
| As a general principle, a function that calls another function to |
| perform some task should check whether the called function raised an |
| exception, and if so, pass the exception state on to its caller. It |
| should discard any object references that it owns, and return an |
| error indicator, but it should \emph{not} set another exception --- |
| that would overwrite the exception that was just raised, and lose |
| important information about the exact cause of the error. |
| |
| A simple example of detecting exceptions and passing them on is shown |
| in the \cfunction{sum_sequence()}\ttindex{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 |
| dict[key] = item + 1 |
| \end{verbatim} |
| \ttindex{incr_item()} |
| |
| 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} |
| \ttindex{incr_item()} |
| |
| This example represents an endorsed use of the \keyword{goto} statement |
| in C! It illustrates the use of |
| \cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and |
| \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to |
| handle specific exceptions, and the use of |
| \cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to |
| dispose of owned references that may be \NULL{} (note the |
| \character{X} in the name; \cfunction{Py_DECREF()} would crash when |
| confronted with a \NULL{} reference). It is important that the |
| variables used to hold owned references are initialized to \NULL{} for |
| this to work; likewise, the proposed return value is initialized to |
| \code{-1} (failure) and only set to success after the final call made |
| is successful. |
| |
| |
| \section{Embedding Python \label{embedding}} |
| |
| The one important task that only embedders (as opposed to extension |
| writers) of the Python interpreter have to worry about is the |
| initialization, and possibly the finalization, of the Python |
| interpreter. Most functionality of the interpreter can only be used |
| after the interpreter has been initialized. |
| |
| The basic initialization function is |
| \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. |
| This initializes the table of loaded modules, and creates the |
| fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, |
| \module{__main__}\refbimodindex{__main__} and |
| \module{sys}\refbimodindex{sys}. It also initializes the module |
| search path (\code{sys.path}).% |
| \indexiii{module}{search}{path} |
| \withsubitem{(in module sys)}{\ttindex{path}} |
| |
| \cfunction{Py_Initialize()} does not set the ``script argument list'' |
| (\code{sys.argv}). If this variable is needed by Python code that |
| will be executed later, it must be set explicitly with a call to |
| \code{PySys_SetArgv(\var{argc}, |
| \var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to |
| \cfunction{Py_Initialize()}. |
| |
| On most systems (in particular, on \UNIX{} and Windows, although the |
| details are slightly different), |
| \cfunction{Py_Initialize()} calculates the module search path based |
| upon its best guess for the location of the standard Python |
| interpreter executable, assuming that the Python library is found in a |
| fixed location relative to the Python interpreter executable. In |
| particular, it looks for a directory named |
| \file{lib/python\shortversion} relative to the parent directory where |
| the executable named \file{python} is found on the shell command |
| search path (the environment variable \envvar{PATH}). |
| |
| For instance, if the Python executable is found in |
| \file{/usr/local/bin/python}, it will assume that the libraries are in |
| \file{/usr/local/lib/python\shortversion}. (In fact, this particular path |
| is also the ``fallback'' location, used when no executable file named |
| \file{python} is found along \envvar{PATH}.) The user can override |
| this behavior by setting the environment variable \envvar{PYTHONHOME}, |
| or insert additional directories in front of the standard path by |
| setting \envvar{PYTHONPATH}. |
| |
| The embedding application can steer the search by calling |
| \code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling |
| \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still |
| overrides this and \envvar{PYTHONPATH} is still inserted in front of |
| the standard path. An application that requires total control has to |
| provide its own implementation of |
| \cfunction{Py_GetPath()}\ttindex{Py_GetPath()}, |
| \cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()}, |
| \cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and |
| \cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all |
| defined in \file{Modules/getpath.c}). |
| |
| Sometimes, it is desirable to ``uninitialize'' Python. For instance, |
| the application may want to start over (make another call to |
| \cfunction{Py_Initialize()}) or the application is simply done with its |
| use of Python and wants to free all memory allocated by Python. This |
| can be accomplished by calling \cfunction{Py_Finalize()}. The function |
| \cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns |
| true if Python is currently in the initialized state. More |
| information about these functions is given in a later chapter. |
| |
| |
| \chapter{The Very High Level Layer \label{veryhigh}} |
| |
| 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. |
| |
| Several of these functions accept a start symbol from the grammar as a |
| parameter. The available start symbols are \constant{Py_eval_input}, |
| \constant{Py_file_input}, and \constant{Py_single_input}. These are |
| described following the functions which accept them as parameters. |
| |
| Note also that several of these functions take \ctype{FILE*} |
| parameters. On particular issue which needs to be handled carefully |
| is that the \ctype{FILE} structure for different C libraries can be |
| different and incompatible. Under Windows (at least), it is possible |
| for dynamically linked extensions to actually use different libraries, |
| so care should be taken that \ctype{FILE*} parameters are only passed |
| to these functions if it is certain that they were created by the same |
| library that the Python runtime is using. |
| |
| \begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv} |
| The main program for the standard interpreter. This is made |
| available for programs which embed Python. The \var{argc} and |
| \var{argv} parameters should be prepared exactly as those which are |
| passed to a C program's \cfunction{main()} function. It is |
| important to note that the argument list may be modified (but the |
| contents of the strings pointed to by the argument list are not). |
| The return value will be the integer passed to the |
| \function{sys.exit()} function, \code{1} if the interpreter exits |
| due to an exception, or \code{2} if the parameter list does not |
| represent a valid Python command line. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename} |
| If \var{fp} refers to a file associated with an interactive device |
| (console or terminal input or \UNIX{} pseudo-terminal), return the |
| value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the |
| result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is |
| \NULL{}, this function uses \code{"???"} as the filename. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command} |
| Executes the Python source code from \var{command} in the |
| \module{__main__} module. If \module{__main__} does not already |
| exist, it is created. Returns \code{0} on success or \code{-1} if |
| an exception was raised. If there was an error, there is no way to |
| get the exception information. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename} |
| Similar to \cfunction{PyRun_SimpleString()}, but the Python source |
| code is read from \var{fp} instead of an in-memory string. |
| \var{filename} should be the name of the file. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename} |
| Read and execute a single statement from a file associated with an |
| interactive device. If \var{filename} is \NULL, \code{"???"} is |
| used instead. The user will be prompted using \code{sys.ps1} and |
| \code{sys.ps2}. Returns \code{0} when the input was executed |
| successfully, \code{-1} if there was an exception, or an error code |
| from the \file{errcode.h} include file distributed as part of Python |
| in case of a parse error. (Note that \file{errcode.h} is not |
| included by \file{Python.h}, so must be included specifically if |
| needed.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename} |
| Read and execute statements from a file associated with an |
| interactive device until \EOF{} is reached. If \var{filename} is |
| \NULL, \code{"???"} is used instead. The user will be prompted |
| using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str, |
| int start} |
| Parse Python source code from \var{str} using the start token |
| \var{start}. The result can be used to create a code object which |
| can be evaluated efficiently. This is useful if a code fragment |
| must be evaluated many times. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp, |
| char *filename, int start} |
| Similar to \cfunction{PyParser_SimpleParseString()}, but the Python |
| source code is read from \var{fp} instead of an in-memory string. |
| \var{filename} should be the name of the file. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start, |
| PyObject *globals, |
| PyObject *locals} |
| Execute Python source code from \var{str} in the context specified |
| by the dictionaries \var{globals} and \var{locals}. The parameter |
| \var{start} specifies the start token that should be used to parse |
| the source code. |
| |
| Returns the result of executing the code as a Python object, or |
| \NULL{} if an exception was raised. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename, |
| int start, PyObject *globals, |
| PyObject *locals} |
| Similar to \cfunction{PyRun_String()}, but the Python source code is |
| read from \var{fp} instead of an in-memory string. |
| \var{filename} should be the name of the file. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename, |
| int start} |
| Parse and compile the Python source code in \var{str}, returning the |
| resulting code object. The start token is given by \var{start}; |
| this can be used to constrain the code which can be compiled and should |
| be \constant{Py_eval_input}, \constant{Py_file_input}, or |
| \constant{Py_single_input}. The filename specified by |
| \var{filename} is used to construct the code object and may appear |
| in tracebacks or \exception{SyntaxError} exception messages. This |
| returns \NULL{} if the code cannot be parsed or compiled. |
| \end{cfuncdesc} |
| |
| \begin{cvardesc}{int}{Py_eval_input} |
| The start symbol from the Python grammar for isolated expressions; |
| for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{Py_file_input} |
| The start symbol from the Python grammar for sequences of statements |
| as read from a file or other source; for use with |
| \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is |
| the symbol to use when compiling arbitrarily long Python source code. |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{Py_single_input} |
| The start symbol from the Python grammar for a single statement; for |
| use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. |
| This is the symbol used for the interactive interpreter loop. |
| \end{cvardesc} |
| |
| |
| \chapter{Reference Counting \label{countingRefs}} |
| |
| 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 \var{o}. The object must |
| not be \NULL{}; if you aren't sure that it isn't \NULL{}, use |
| \cfunction{Py_XINCREF()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} |
| Increment the reference count for object \var{o}. The object may be |
| \NULL{}, in which case the macro has no effect. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} |
| Decrement the reference count for object \var{o}. The object must |
| not be \NULL{}; if you aren't sure that it isn't \NULL{}, use |
| \cfunction{Py_XDECREF()}. If the reference count reaches zero, the |
| object's type's deallocation function (which must not be \NULL{}) is |
| invoked. |
| |
| \strong{Warning:} The deallocation function can cause arbitrary Python |
| code to be invoked (e.g. when a class instance with a |
| \method{__del__()} method is deallocated). While exceptions in such |
| code are not propagated, the executed code has free access to all |
| Python global variables. This means that any object that is reachable |
| from a global variable should be in a consistent state before |
| \cfunction{Py_DECREF()} is invoked. For example, code to delete an |
| object from a list should copy a reference to the deleted object in a |
| temporary variable, update the list data structure, and then call |
| \cfunction{Py_DECREF()} for the temporary variable. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} |
| Decrement the reference count for object \var{o}. The object may be |
| \NULL{}, in which case the macro has no effect; otherwise the effect |
| is the same as for \cfunction{Py_DECREF()}, and the same warning |
| applies. |
| \end{cfuncdesc} |
| |
| The following functions or macros are only for use within the |
| interpreter core: \cfunction{_Py_Dealloc()}, |
| \cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as |
| well as the global variable \cdata{_Py_RefTotal}. |
| |
| |
| \chapter{Exception Handling \label{exceptionHandling}} |
| |
| The functions described 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{} \cdata{errno} variable: there is a global indicator (per |
| thread) of the last error that occurred. Most functions don't clear |
| this on success, but will set it to indicate the cause of the error on |
| failure. Most functions also return an error indicator, usually |
| \NULL{} if they are supposed to return a pointer, or \code{-1} if they |
| return an integer (exception: the \cfunction{PyArg_Parse*()} functions |
| return \code{1} for success and \code{0} for failure). When a |
| function must fail because some function it called failed, it |
| generally doesn't set the error indicator; the function it called |
| already set it. |
| |
| The error indicator consists of three Python objects corresponding to |
| \withsubitem{(in module sys)}{ |
| \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
| the Python variables \code{sys.exc_type}, \code{sys.exc_value} and |
| \code{sys.exc_traceback}. API functions exist to interact with the |
| error indicator in various ways. There is a separate error indicator |
| for each thread. |
| |
| % XXX Order of these should be more thoughtful. |
| % Either alphabetical or some kind of structure. |
| |
| \begin{cfuncdesc}{void}{PyErr_Print}{} |
| Print a standard traceback to \code{sys.stderr} and clear the error |
| indicator. Call this function only when the error indicator is set. |
| (Otherwise it will cause a fatal error!) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} |
| Test whether the error indicator is set. If set, return the exception |
| \emph{type} (the first argument to the last call to one of the |
| \cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If |
| not set, return \NULL{}. You do not own a reference to the return |
| value, so you do not need to \cfunction{Py_DECREF()} it. |
| \strong{Note:} Do not compare the return value to a specific |
| exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown |
| below. (The comparison could easily fail since the exception may be |
| an instance instead of a class, in the case of a class exception, or |
| it may the a subclass of the expected exception.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} |
| Equivalent to |
| \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}. |
| This should only be called when an exception is actually set; a memory |
| access violation will occur if no exception has been raised. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} |
| Return true if the \var{given} exception matches the exception in |
| \var{exc}. If \var{exc} is a class object, this also returns true |
| when \var{given} is an instance of a subclass. If \var{exc} is a tuple, all |
| exceptions in the tuple (and recursively in subtuples) are searched |
| for a match. If \var{given} is \NULL, a memory access violation will |
| occur. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} |
| Under certain circumstances, the values returned by |
| \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that |
| \code{*\var{exc}} is a class object but \code{*\var{val}} is not an |
| instance of the same class. This function can be used to instantiate |
| the class in that case. If the values are already normalized, nothing |
| happens. The delayed normalization is implemented to improve |
| performance. |
| \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: 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. \cdata{PyExc_RuntimeError}. You need not |
| increment its reference count. The second argument is an error |
| message; it is converted to a string object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} |
| This function is similar to \cfunction{PyErr_SetString()} but lets you |
| specify an arbitrary Python object for the ``value'' of the exception. |
| You need not increment its reference count. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, |
| const char *format, \moreargs} |
| This function sets the error indicator. \var{exception} should be a |
| Python exception (string or class, not an instance). |
| \var{format} should be a string, containing format codes, similar to |
| \cfunction{printf}. The \code{width.precision} before a format code |
| is parsed, but the width part is ignored. |
| |
| \begin{tableii}{c|l}{character}{Character}{Meaning} |
| \lineii{c}{Character, as an \ctype{int} parameter} |
| \lineii{d}{Number in decimal, as an \ctype{int} parameter} |
| \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} |
| \lineii{x}{A string, as a \ctype{char *} parameter} |
| \end{tableii} |
| |
| An unrecognized format character causes all the rest of |
| the format string to be copied as-is to the result string, |
| and any extra arguments discarded. |
| |
| A new reference is returned, which is owned by the caller. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} |
| This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_BadArgument}{} |
| This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
| \var{message})}, where \var{message} indicates that a built-in operation |
| was invoked with an illegal argument. It is mostly for internal use. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} |
| This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it |
| returns \NULL{} so an object allocation function can write |
| \samp{return PyErr_NoMemory();} when it runs out of memory. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} |
| This is a convenience function to raise an exception when a C library |
| function has returned an error and set the C variable \cdata{errno}. |
| It constructs a tuple object whose first item is the integer |
| \cdata{errno} value and whose second item is the corresponding error |
| message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and |
| then calls |
| \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when |
| the \cdata{errno} value is \constant{EINTR}, indicating an interrupted |
| system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set |
| the error indicator, leaves it set to that. The function always |
| returns \NULL{}, so a wrapper function around a system call can write |
| \samp{return PyErr_SetFromErrno();} when the system call returns an |
| error. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, |
| char *filename} |
| Similar to \cfunction{PyErr_SetFromErrno()}, with the additional |
| behavior that if \var{filename} is not \NULL, it is passed to the |
| constructor of \var{type} as a third parameter. In the case of |
| exceptions such as \exception{IOError} and \exception{OSError}, this |
| is used to define the \member{filename} attribute of the exception |
| instance. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} |
| This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
| \var{message})}, where \var{message} indicates that an internal |
| operation (e.g. a Python/C API function) was invoked with an illegal |
| argument. It is mostly for internal use. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} |
| Issue a warning message. The \var{category} argument is a warning |
| category (see below) or \NULL; the \var{message} argument is a message |
| string. |
| |
| This function normally prints a warning message to \var{sys.stderr}; |
| however, it is also possible that the user has specified that warnings |
| are to be turned into errors, and in that case this will raise an |
| exception. It is also possible that the function raises an exception |
| because of a problem with the warning machinery (the implementation |
| imports the \module{warnings} module to do the heavy lifting). The |
| return value is \code{0} if no exception is raised, or \code{-1} if |
| an exception is raised. (It is not possible to determine whether a |
| warning message is actually printed, nor what the reason is for the |
| exception; this is intentional.) If an exception is raised, the |
| caller should do its normal exception handling |
| (e.g. \cfunction{Py_DECREF()} owned references and return an error |
| value). |
| |
| Warning categories must be subclasses of \cdata{Warning}; the default |
| warning category is \cdata{RuntimeWarning}. The standard Python |
| warning categories are available as global variables whose names are |
| \samp{PyExc_} followed by the Python exception name. These have the |
| type \ctype{PyObject*}; they are all class objects. Their names are |
| \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, |
| \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and |
| \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of |
| \cdata{PyExc_Exception}; the other warning categories are subclasses |
| of \cdata{PyExc_Warning}. |
| |
| For information about warning control, see the documentation for the |
| \module{warnings} module and the \programopt{-W} option in the command |
| line documentation. There is no C API for warning control. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, |
| char *filename, int lineno, char *module, PyObject *registry} |
| Issue a warning message with explicit control over all warning |
| attributes. This is a straightforward wrapper around the Python |
| function \function{warnings.warn_explicit()}, see there for more |
| information. The \var{module} and \var{registry} arguments may be |
| set to \code{NULL} to get the default effect described there. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_CheckSignals}{} |
| This function interacts with Python's signal handling. It checks |
| whether a signal has been sent to the processes and if so, invokes the |
| corresponding signal handler. If the |
| \module{signal}\refbimodindex{signal} module is supported, this can |
| invoke a signal handler written in Python. In all cases, the default |
| effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the |
| \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
| \exception{KeyboardInterrupt} exception. If an exception is raised the |
| error indicator is set and the function returns \code{1}; otherwise |
| the function returns \code{0}. The error indicator may or may not be |
| cleared if it was previously set. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} |
| This function is obsolete. It simulates the effect of a |
| \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time |
| \cfunction{PyErr_CheckSignals()} is called, |
| \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
| \exception{KeyboardInterrupt} will be raised. |
| It may be called without holding the interpreter lock. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, |
| PyObject *base, |
| PyObject *dict} |
| This utility function creates and returns a new exception object. The |
| \var{name} argument must be the name of the new exception, a C string |
| of the form \code{module.class}. The \var{base} and |
| \var{dict} arguments are normally \NULL{}. This creates a |
| class object derived from the root for all exceptions, the built-in |
| name \exception{Exception} (accessible in C as |
| \cdata{PyExc_Exception}). The \member{__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). 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} |
| |
| \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} |
| This utility function prints a warning message to \var{sys.stderr} |
| when an exception has been set but it is impossible for the |
| interpreter to actually raise the exception. It is used, for example, |
| when an exception occurs in an \member{__del__} method. |
| |
| The function is called with a single argument \var{obj} that |
| identifies where the context in which the unraisable exception |
| occurred. The repr of \var{obj} will be printed in the warning |
| message. |
| \end{cfuncdesc} |
| |
| \section{Standard Exceptions \label{standardExceptions}} |
| |
| All standard Python exceptions are available as global variables whose |
| names are \samp{PyExc_} followed by the Python exception name. These |
| have the type \ctype{PyObject*}; they are all class objects. For |
| completeness, here are all the variables: |
| |
| \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} |
| \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} |
| \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} |
| \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} |
| \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} |
| \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} |
| \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} |
| \lineiii{PyExc_EOFError}{\exception{EOFError}}{} |
| \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} |
| \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} |
| \lineiii{PyExc_IOError}{\exception{IOError}}{} |
| \lineiii{PyExc_ImportError}{\exception{ImportError}}{} |
| \lineiii{PyExc_IndexError}{\exception{IndexError}}{} |
| \lineiii{PyExc_KeyError}{\exception{KeyError}}{} |
| \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} |
| \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} |
| \lineiii{PyExc_NameError}{\exception{NameError}}{} |
| \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} |
| \lineiii{PyExc_OSError}{\exception{OSError}}{} |
| \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} |
| \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} |
| \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} |
| \lineiii{PyExc_SystemError}{\exception{SystemError}}{} |
| \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} |
| \lineiii{PyExc_TypeError}{\exception{TypeError}}{} |
| \lineiii{PyExc_ValueError}{\exception{ValueError}}{} |
| \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(2)} |
| \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} |
| \end{tableiii} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| This is a base class for other standard exceptions. |
| |
| \item[(2)] |
| Only defined on Windows; protect code that uses this by testing that |
| the preprocessor macro \code{MS_WINDOWS} is defined. |
| \end{description} |
| |
| |
| \section{Deprecation of String Exceptions} |
| |
| All exceptions built into Python or provided in the standard library |
| are derived from \exception{Exception}. |
| \withsubitem{(built-in exception)}{\ttindex{Exception}} |
| |
| String exceptions are still supported in the interpreter to allow |
| existing code to run unmodified, but this will also change in a future |
| release. |
| |
| |
| \chapter{Utilities \label{utilities}} |
| |
| The functions in this chapter perform various utility tasks, ranging |
| from helping C code be more portable across platforms, using Python |
| modules from C, and parsing function arguments and constructing Python |
| values from C values. |
| |
| |
| \section{Operating System Utilities \label{os}} |
| |
| \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} |
| Return true (nonzero) if the standard I/O file \var{fp} with name |
| \var{filename} is deemed interactive. This is the case for files for |
| which \samp{isatty(fileno(\var{fp}))} is true. If the global flag |
| \cdata{Py_InteractiveFlag} is true, this function also returns true if |
| the \var{filename} pointer is \NULL{} or if the name is equal to one of |
| the strings \code{'<stdin>'} or \code{'???'}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} |
| Return the time of last modification of the file \var{filename}. |
| The result is encoded in the same way as the timestamp returned by |
| the standard C library function \cfunction{time()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyOS_AfterFork}{} |
| Function to update some internal state after a process fork; this |
| should be called in the new process if the Python interpreter will |
| continue to be used. If a new executable is loaded into the new |
| process, this function does not need to be called. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyOS_CheckStack}{} |
| Return true when the interpreter runs out of stack space. This is a |
| reliable check, but is only available when \code{USE_STACKCHECK} is |
| defined (currently on Windows using the Microsoft Visual C++ compiler |
| and on the Macintosh). \code{USE_CHECKSTACK} will be defined |
| automatically; you should never change the definition in your own |
| code. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i} |
| Return the current signal handler for signal \var{i}. |
| This is a thin wrapper around either \cfunction{sigaction} or |
| \cfunction{signal}. Do not call those functions directly! |
| \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h} |
| Set the signal handler for signal \var{i} to be \var{h}; |
| return the old signal handler. |
| This is a thin wrapper around either \cfunction{sigaction} or |
| \cfunction{signal}. Do not call those functions directly! |
| \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. |
| \end{cfuncdesc} |
| |
| |
| \section{Process Control \label{processControl}} |
| |
| \begin{cfuncdesc}{void}{Py_FatalError}{char *message} |
| Print a fatal error message and kill the process. No cleanup is |
| performed. This function should only be invoked when a condition is |
| detected that would make it dangerous to continue using the Python |
| interpreter; e.g., when the object administration appears to be |
| corrupted. On \UNIX{}, the standard C library function |
| \cfunction{abort()}\ttindex{abort()} is called which will attempt to |
| produce a \file{core} file. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_Exit}{int status} |
| Exit the current process. This calls |
| \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and |
| then calls the standard C library function |
| \code{exit(\var{status})}\ttindex{exit()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} |
| Register a cleanup function to be called by |
| \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. |
| The cleanup function will be called with no arguments and should |
| return no value. At most 32 \index{cleanup functions}cleanup |
| functions can be registered. |
| When the registration is successful, \cfunction{Py_AtExit()} returns |
| \code{0}; on failure, it returns \code{-1}. The cleanup function |
| registered last is called first. Each cleanup function will be called |
| at most once. Since Python's internal finallization will have |
| completed before the cleanup function, no Python APIs should be called |
| by \var{func}. |
| \end{cfuncdesc} |
| |
| |
| \section{Importing Modules \label{importing}} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name} |
| This is a simplified interface to |
| \cfunction{PyImport_ImportModuleEx()} below, leaving the |
| \var{globals} and \var{locals} arguments set to \NULL{}. When the |
| \var{name} argument contains a dot (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 |
| \index{package variable!\code{__all__}} |
| \withsubitem{(package variable)}{\ttindex{__all__}}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 --- examine \code{sys.modules} to find out). |
| \withsubitem{(in module sys)}{\ttindex{modules}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, |
| PyObject *globals, PyObject *locals, PyObject *fromlist} |
| Import a module. This is best described by referring to the built-in |
| Python function \function{__import__()}\bifuncindex{__import__}, as |
| the standard \function{__import__()} function calls this function |
| directly. |
| |
| The return value is a new reference to the imported module or |
| top-level package, or \NULL{} with an exception set on failure |
| (the module may still be created in this case). Like for |
| \function{__import__()}, the return value when a submodule of a |
| package was requested is normally the top-level package, unless a |
| non-empty \var{fromlist} was given. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name} |
| This is a higher-level interface that calls the current ``import hook |
| function''. It invokes the \function{__import__()} function from the |
| \code{__builtins__} of the current globals. This means that the |
| import is done using whatever import hooks are installed in the |
| current environment, e.g. by \module{rexec}\refstmodindex{rexec} or |
| \module{ihooks}\refstmodindex{ihooks}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m} |
| Reload a module. This is best described by referring to the built-in |
| Python function \function{reload()}\bifuncindex{reload}, as the standard |
| \function{reload()} function calls this function directly. Return a |
| new reference to the reloaded module, or \NULL{} with an exception set |
| on failure (the module still exists in this case). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name} |
| Return the module object corresponding to a module name. The |
| \var{name} argument may be of the form \code{package.module}). First |
| check the modules dictionary if there's one there, and if not, create |
| a new one and insert in in the modules dictionary. |
| Warning: this function does not load or import the module; if the |
| module wasn't already loaded, you will get an empty module object. |
| Use \cfunction{PyImport_ImportModule()} or one of its variants to |
| import a module. |
| Return \NULL{} with an exception set on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co} |
| Given a module name (possibly of the form \code{package.module}) and a |
| code object read from a Python bytecode file or obtained from the |
| built-in function \function{compile()}\bifuncindex{compile}, load the |
| module. Return a new reference to the module object, or \NULL{} with |
| an exception set if an error occurred (the module may still be created |
| in this case). (This function would reload the module if it was |
| already imported.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} |
| Return the magic number for Python bytecode files (a.k.a. |
| \file{.pyc} and \file{.pyo} files). The magic number should be |
| present in the first four bytes of the bytecode file, in little-endian |
| byte order. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{} |
| Return the dictionary used for the module administration |
| (a.k.a. \code{sys.modules}). Note that this is a per-interpreter |
| variable. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{_PyImport_Init}{} |
| Initialize the import mechanism. For internal use only. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyImport_Cleanup}{} |
| Empty the module table. For internal use only. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{_PyImport_Fini}{} |
| Finalize the import mechanism. For internal use only. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *} |
| For internal use only. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *} |
| For internal use only. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name} |
| Load a frozen module named \var{name}. Return \code{1} for success, |
| \code{0} if the module is not found, and \code{-1} with an exception |
| set if the initialization failed. To access the imported module on a |
| successful load, use \cfunction{PyImport_ImportModule()}. |
| (Note the misnomer --- this function would reload the module if it was |
| already imported.) |
| \end{cfuncdesc} |
| |
| \begin{ctypedesc}[_frozen]{struct _frozen} |
| This is the structure type definition for frozen module descriptors, |
| as generated by the \program{freeze}\index{freeze utility} utility |
| (see \file{Tools/freeze/} in the Python source distribution). Its |
| definition, found in \file{Include/import.h}, 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 \ctype{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} |
| |
| \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name, |
| void (*initfunc)(void)} |
| Add a single module to the existing table of built-in modules. This |
| is a convenience wrapper around \cfunction{PyImport_ExtendInittab()}, |
| returning \code{-1} if the table could not be extended. The new |
| module can be imported by the name \var{name}, and uses the function |
| \var{initfunc} as the initialization function called on the first |
| attempted import. This should be called before |
| \cfunction{Py_Initialize()}. |
| \end{cfuncdesc} |
| |
| \begin{ctypedesc}[_inittab]{struct _inittab} |
| Structure describing a single entry in the list of built-in modules. |
| Each of these structures gives the name and initialization function |
| for a module built into the interpreter. Programs which embed Python |
| may use an array of these structures in conjunction with |
| \cfunction{PyImport_ExtendInittab()} to provide additional built-in |
| modules. The structure is defined in \file{Include/import.h} as: |
| |
| \begin{verbatim} |
| struct _inittab { |
| char *name; |
| void (*initfunc)(void); |
| }; |
| \end{verbatim} |
| \end{ctypedesc} |
| |
| \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab} |
| Add a collection of modules to the table of built-in modules. The |
| \var{newtab} array must end with a sentinel entry which contains |
| \NULL{} for the \member{name} field; failure to provide the sentinel |
| value can result in a memory fault. Returns \code{0} on success or |
| \code{-1} if insufficient memory could be allocated to extend the |
| internal table. In the event of failure, no modules are added to the |
| internal table. This should be called before |
| \cfunction{Py_Initialize()}. |
| \end{cfuncdesc} |
| |
| |
| \section{Parsing arguements and building values |
| \label{arg-parsing}} |
| |
| These functions are useful when creating your own extensions functions |
| and methods. Additional information and examples are available in |
| \citetitle[../ext/ext.html]{Extending and Embedding the Python |
| Interpreter}. |
| |
| \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format, |
| \moreargs} |
| Parse the parameters of a function that takes only positional |
| parameters into local variables. Returns true on success; on |
| failure, it returns false and raises the appropriate exception. See |
| \citetitle[../ext/parseTuple.html]{Extending and Embedding the |
| Python Interpreter} for more information. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args, |
| PyObject *kw, char *format, char *keywords[], |
| \moreargs} |
| Parse the parameters of a function that takes both positional and |
| keyword parameters into local variables. Returns true on success; |
| on failure, it returns false and raises the appropriate exception. |
| See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and |
| Embedding the Python Interpreter} for more information. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format, |
| \moreargs} |
| Function used to deconstruct the argument lists of ``old-style'' |
| functions --- these are functions which use the |
| \constant{METH_OLDARGS} parameter parsing method. This is not |
| recommended for use in parameter parsing in new code, and most code |
| in the standard interpreter has been modified to no longer use this |
| for that purpose. It does remain a convenient way to decompose |
| other tuples, however, and may continue to be used for that |
| purpose. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format, |
| \moreargs} |
| Create a new value based on a format string similar to those |
| accepted by the \cfunction{PyArg_Parse*()} family of functions and a |
| sequence of values. Returns the value or \NULL{} in the case of an |
| error; an exception will be raised if \NULL{} is returned. For more |
| information on the format string and additional parameters, see |
| \citetitle[../ext/buildValue.html]{Extending and Embedding the |
| Python Interpreter}. |
| \end{cfuncdesc} |
| |
| |
| |
| \chapter{Abstract Objects Layer \label{abstract}} |
| |
| 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 raise a Python exception. |
| |
| \section{Object Protocol \label{object}} |
| |
| \begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} |
| Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error. |
| The flags argument is used to enable certain printing options. The |
| only option currently supported is \constant{Py_PRINT_RAW}; if given, |
| the \function{str()} of the object is written instead of the |
| \function{repr()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} |
| Returns \code{1} if \var{o} has the attribute \var{attr_name}, and |
| \code{0} otherwise. This is equivalent to the Python expression |
| \samp{hasattr(\var{o}, \var{attr_name})}. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, |
| char *attr_name} |
| Retrieve an attribute named \var{attr_name} from object \var{o}. |
| Returns the attribute value on success, or \NULL{} on failure. |
| This is the equivalent of the Python expression |
| \samp{\var{o}.\var{attr_name}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} |
| Returns \code{1} if \var{o} has the attribute \var{attr_name}, and |
| \code{0} otherwise. This is equivalent to the Python expression |
| \samp{hasattr(\var{o}, \var{attr_name})}. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, |
| PyObject *attr_name} |
| Retrieve an attribute named \var{attr_name} from object \var{o}. |
| Returns the attribute value on success, or \NULL{} on failure. |
| This is the equivalent of the Python expression |
| \samp{\var{o}.\var{attr_name}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, |
| char *attr_name, PyObject *v} |
| Set the value of the attribute named \var{attr_name}, for object |
| \var{o}, to the value \var{v}. Returns \code{-1} on failure. This is |
| the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = |
| \var{v}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, |
| PyObject *attr_name, PyObject *v} |
| Set the value of the attribute named \var{attr_name}, for |
| object \var{o}, |
| to the value \var{v}. Returns \code{-1} on failure. This is |
| the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = |
| \var{v}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} |
| Delete attribute named \var{attr_name}, for object \var{o}. Returns |
| \code{-1} on failure. This is the equivalent of the Python |
| statement: \samp{del \var{o}.\var{attr_name}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} |
| Delete attribute named \var{attr_name}, for object \var{o}. Returns |
| \code{-1} on failure. This is the equivalent of the Python |
| statement \samp{del \var{o}.\var{attr_name}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} |
| Compare the values of \var{o1} and \var{o2} using a routine provided |
| by \var{o1}, if one exists, otherwise with a routine provided by |
| \var{o2}. The result of the comparison is returned in \var{result}. |
| Returns \code{-1} on failure. This is the equivalent of the Python |
| statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} |
| Compare the values of \var{o1} and \var{o2} using a routine provided |
| by \var{o1}, if one exists, otherwise with a routine provided by |
| \var{o2}. Returns the result of the comparison on success. On error, |
| the value returned is undefined; use \cfunction{PyErr_Occurred()} to |
| detect an error. This is equivalent to the Python |
| expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} |
| Compute a string representation of object \var{o}. Returns the |
| string representation on success, \NULL{} on failure. This is |
| the equivalent of the Python expression \samp{repr(\var{o})}. |
| Called by the \function{repr()}\bifuncindex{repr} built-in function |
| and by reverse quotes. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} |
| Compute a string representation of object \var{o}. Returns the |
| string representation on success, \NULL{} on failure. This is |
| the equivalent of the Python expression \samp{str(\var{o})}. |
| Called by the \function{str()}\bifuncindex{str} built-in function and |
| by the \keyword{print} statement. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o} |
| Compute a Unicode string representation of object \var{o}. Returns the |
| Unicode string representation on success, \NULL{} on failure. This is |
| the equivalent of the Python expression \samp{unistr(\var{o})}. |
| Called by the \function{unistr()}\bifuncindex{unistr} built-in function. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls} |
| Return \code{1} if \var{inst} is an instance of the class \var{cls} or |
| a subclass of \var{cls}. If \var{cls} is a type object rather than a |
| class object, \cfunction{PyObject_IsInstance()} returns \code{1} if |
| \var{inst} is of type \var{cls}. If \var{inst} is not a class |
| instance and \var{cls} is neither a type object or class object, |
| \var{inst} must have a \member{__class__} attribute --- the class |
| relationship of the value of that attribute with \var{cls} will be |
| used to determine the result of this function. |
| \versionadded{2.1} |
| \end{cfuncdesc} |
| |
| Subclass determination is done in a fairly straightforward way, but |
| includes a wrinkle that implementors of extensions to the class system |
| may want to be aware of. If \class{A} and \class{B} are class |
| objects, \class{B} is a subclass of \class{A} if it inherits from |
| \class{A} either directly or indirectly. If either is not a class |
| object, a more general mechanism is used to determine the class |
| relationship of the two objects. When testing if \var{B} is a |
| subclass of \var{A}, if \var{A} is \var{B}, |
| \cfunction{PyObject_IsSubclass()} returns true. If \var{A} and |
| \var{B} are different objects, \var{B}'s \member{__bases__} attribute |
| is searched in a depth-first fashion for \var{A} --- the presence of |
| the \member{__bases__} attribute is considered sufficient for this |
| determination. |
| |
| \begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived, |
| PyObject *cls} |
| Returns \code{1} if the class \var{derived} is identical to or derived |
| from the class \var{cls}, otherwise returns \code{0}. In case of an |
| error, returns \code{-1}. If either \var{derived} or \var{cls} is not |
| an actual class object, this function uses the generic algorithm |
| described above. |
| \versionadded{2.1} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} |
| Determine if the object \var{o} is callable. Return \code{1} if the |
| object is callable and \code{0} otherwise. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, |
| PyObject *args} |
| Call a callable Python object \var{callable_object}, with |
| arguments given by the tuple \var{args}. If no arguments are |
| needed, then \var{args} may be \NULL{}. Returns the result of the |
| call on success, or \NULL{} on failure. This is the equivalent |
| of the Python expression \samp{apply(\var{callable_object}, |
| \var{args})} or \samp{\var{callable_object}(*\var{args})}. |
| \bifuncindex{apply} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, |
| char *format, ...} |
| Call a callable Python object \var{callable_object}, with a |
| variable number of C arguments. The C arguments are described |
| using a \cfunction{Py_BuildValue()} style format string. The format may |
| be \NULL{}, indicating that no arguments are provided. Returns the |
| result of the call on success, or \NULL{} on failure. This is |
| the equivalent of the Python expression |
| \samp{apply(\var{callable_object}\var{args})} or |
| \samp{\var{callable_object}(*\var{args})}. |
| \bifuncindex{apply} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, |
| char *method, char *format, ...} |
| Call the method named \var{m} of object \var{o} with a variable number |
| of C arguments. The C arguments are described by a |
| \cfunction{Py_BuildValue()} format string. The format may be \NULL{}, |
| indicating that no arguments are provided. Returns the result of the |
| call on success, or \NULL{} on failure. This is the equivalent of the |
| Python expression \samp{\var{o}.\var{method}(\var{args})}. |
| Note that special method names, such as \method{__add__()}, |
| \method{__getitem__()}, and so on are not supported. The specific |
| abstract-object routines for these must be used. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} |
| Compute and return the hash value of an object \var{o}. On |
| failure, return \code{-1}. This is the equivalent of the Python |
| expression \samp{hash(\var{o})}.\bifuncindex{hash} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} |
| Returns \code{1} if the object \var{o} is considered to be true, and |
| \code{0} otherwise. This is equivalent to the Python expression |
| \samp{not not \var{o}}. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} |
| On success, returns a type object corresponding to the object |
| type of object \var{o}. On failure, returns \NULL{}. This is |
| equivalent to the Python expression \samp{type(\var{o})}. |
| \bifuncindex{type} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} |
| Return the length of object \var{o}. If the object \var{o} provides |
| both sequence and mapping protocols, the sequence length is |
| returned. On error, \code{-1} is returned. This is the equivalent |
| to the Python expression \samp{len(\var{o})}.\bifuncindex{len} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} |
| Return element of \var{o} corresponding to the object \var{key} or |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{\var{o}[\var{key}]}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, |
| PyObject *key, PyObject *v} |
| Map the object \var{key} to the value \var{v}. |
| Returns \code{-1} on failure. This is the equivalent |
| of the Python statement \samp{\var{o}[\var{key}] = \var{v}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key} |
| Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on |
| failure. This is the equivalent of the Python statement \samp{del |
| \var{o}[\var{key}]}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o} |
| Derives a file-descriptor from a Python object. If the object |
| is an integer or long integer, its value is returned. If not, the |
| object's \method{fileno()} method is called if it exists; the method |
| must return an integer or long integer, which is returned as the file |
| descriptor value. Returns \code{-1} on failure. |
| \end{cfuncdesc} |
| |
| |
| \section{Number Protocol \label{number}} |
| |
| \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} |
| Returns \code{1} if the object \var{o} provides numeric protocols, and |
| false otherwise. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} |
| Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on |
| failure. This is the equivalent of the Python expression |
| \samp{\var{o1} + \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} |
| Returns the result of subtracting \var{o2} from \var{o1}, or |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{\var{o1} - \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} |
| Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on |
| failure. This is the equivalent of the Python expression |
| \samp{\var{o1} * \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} |
| Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on |
| failure. |
| This is the equivalent of the Python expression \samp{\var{o1} / |
| \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2} |
| Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on |
| failure. This is equivalent to the ``classic'' division of integers. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2} |
| Return a reasonable approximation for the mathematical value of |
| \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value |
| is ``approximate'' because binary floating point numbers are |
| approximate; it is not possible to represent all real numbers in base |
| two. This function can return a floating point value when passed two |
| integers. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} |
| Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on |
| failure. This is the equivalent of the Python expression |
| \samp{\var{o1} \%\ \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} |
| See the built-in function \function{divmod()}\bifuncindex{divmod}. |
| Returns \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{divmod(\var{o1}, \var{o2})}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, |
| PyObject *o2, PyObject *o3} |
| See the built-in function \function{pow()}\bifuncindex{pow}. Returns |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional. |
| If \var{o3} is to be ignored, pass \cdata{Py_None} in its place |
| (passing \NULL{} for \var{o3} would cause an illegal memory access). |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} |
| Returns the negation of \var{o} on success, or \NULL{} on failure. |
| This is the equivalent of the Python expression \samp{-\var{o}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} |
| Returns \var{o} on success, or \NULL{} on failure. |
| This is the equivalent of the Python expression \samp{+\var{o}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} |
| Returns the absolute value of \var{o}, or \NULL{} on failure. This is |
| the equivalent of the Python expression \samp{abs(\var{o})}. |
| \bifuncindex{abs} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} |
| Returns the bitwise negation of \var{o} on success, or \NULL{} on |
| failure. This is the equivalent of the Python expression |
| \samp{\~\var{o}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} |
| Returns the result of left shifting \var{o1} by \var{o2} on success, |
| or \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{\var{o1} <\code{<} \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} |
| Returns the result of right shifting \var{o1} by \var{o2} on success, |
| or \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{\var{o1} >\code{>} \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{\var{o1} \&\ \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success, |
| or \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{\var{o1} \textasciicircum{} \var{o2}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{\var{o1} | \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2} |
| Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on |
| failure. The operation is done \emph{in-place} when \var{o1} supports |
| it. This is the equivalent of the Python statement \samp{\var{o1} += |
| \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, |
| PyObject *o2} |
| Returns the result of subtracting \var{o2} from \var{o1}, or |
| \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} -= \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, |
| PyObject *o2} |
| Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on |
| failure. The operation is done \emph{in-place} when \var{o1} supports it. |
| This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, |
| PyObject *o2} |
| Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on |
| failure. The operation is done \emph{in-place} when \var{o1} supports |
| it. This is the equivalent of the Python statement \samp{\var{o1} /= |
| \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1, |
| PyObject *o2} |
| Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{} |
| on failure. The operation is done \emph{in-place} when \var{o1} |
| supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} //= \var{o2}}. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1, |
| PyObject *o2} |
| Return a reasonable approximation for the mathematical value of |
| \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value |
| is ``approximate'' because binary floating point numbers are |
| approximate; it is not possible to represent all real numbers in base |
| two. This function can return a floating point value when passed two |
| integers. The operation is done \emph{in-place} when \var{o1} |
| supports it. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, |
| PyObject *o2} |
| Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on |
| failure. The operation is done \emph{in-place} when \var{o1} supports it. |
| This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, |
| PyObject *o2, PyObject *o3} |
| See the built-in function \function{pow()}.\bifuncindex{pow} Returns |
| \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an |
| in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})} |
| otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its |
| place (passing \NULL{} for \var{o3} would cause an illegal memory |
| access). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, |
| PyObject *o2} |
| Returns the result of left shifting \var{o1} by \var{o2} on success, |
| or \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} <\code{<=} \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, |
| PyObject *o2} |
| Returns the result of right shifting \var{o1} by \var{o2} on success, |
| or \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} >\code{>=} \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise and'' of \var{o1} and \var{o2} on success |
| and \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} \&= \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on |
| success, or \NULL{} on failure. The operation is done \emph{in-place} |
| when \var{o1} supports it. This is the equivalent of the Python |
| statement \samp{\var{o1} \textasciicircum= \var{o2}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2} |
| Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or |
| \NULL{} on failure. The operation is done \emph{in-place} when |
| \var{o1} supports it. This is the equivalent of the Python statement |
| \samp{\var{o1} |= \var{o2}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2} |
| This function takes the addresses of two variables of type |
| \ctype{PyObject*}. If the objects pointed to by \code{*\var{p1}} and |
| \code{*\var{p2}} have the same type, increment their reference count |
| and return \code{0} (success). If the objects can be converted to a |
| common numeric type, replace \code{*p1} and \code{*p2} by their |
| converted value (with 'new' reference counts), and return \code{0}. |
| If no conversion is possible, or if some other error occurs, return |
| \code{-1} (failure) and don't increment the reference counts. The |
| call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python |
| statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}. |
| \bifuncindex{coerce} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} |
| Returns the \var{o} converted to an integer object on success, or |
| \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{int(\var{o})}.\bifuncindex{int} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} |
| Returns the \var{o} converted to a long integer object on success, |
| or \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{long(\var{o})}.\bifuncindex{long} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} |
| Returns the \var{o} converted to a float object on success, or |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{float(\var{o})}.\bifuncindex{float} |
| \end{cfuncdesc} |
| |
| |
| \section{Sequence Protocol \label{sequence}} |
| |
| \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} |
| Return \code{1} if the object provides sequence protocol, and |
| \code{0} otherwise. This function always succeeds. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o} |
| Returns the number of objects in sequence \var{o} on success, and |
| \code{-1} on failure. For objects that do not provide sequence |
| protocol, this is equivalent to the Python expression |
| \samp{len(\var{o})}.\bifuncindex{len} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o} |
| Alternate name for \cfunction{PySequence_Size()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} |
| Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on |
| failure. This is the equivalent of the Python |
| expression \samp{\var{o1} + \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} |
| Return the result of repeating sequence object |
| \var{o} \var{count} times, or \NULL{} on failure. This is the |
| equivalent of the Python expression \samp{\var{o} * \var{count}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, |
| PyObject *o2} |
| Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on |
| failure. The operation is done \emph{in-place} when \var{o1} supports it. |
| This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count} |
| Return the result of repeating sequence object \var{o} \var{count} times, or |
| \NULL{} on failure. The operation is done \emph{in-place} when \var{o} |
| supports it. This is the equivalent of the Python expression \samp{\var{o} |
| *= \var{count}}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} |
| Return the \var{i}th element of \var{o}, or \NULL{} on failure. This |
| is the equivalent of the Python expression \samp{\var{o}[\var{i}]}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} |
| Return the slice of sequence object \var{o} between \var{i1} and |
| \var{i2}, or \NULL{} on failure. This is the equivalent of the Python |
| expression \samp{\var{o}[\var{i1}:\var{i2}]}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} |
| Assign object \var{v} to the \var{i}th element of \var{o}. |
| Returns \code{-1} on failure. This is the equivalent of the Python |
| statement \samp{\var{o}[\var{i}] = \var{v}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} |
| Delete the \var{i}th element of object \var{o}. Returns |
| \code{-1} on failure. This is the equivalent of the Python |
| statement \samp{del \var{o}[\var{i}]}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, |
| int i2, PyObject *v} |
| Assign the sequence object \var{v} to the slice in sequence |
| object \var{o} from \var{i1} to \var{i2}. This is the equivalent of |
| the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} |
| Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}. |
| Returns \code{-1} on failure. This is the equivalent of the Python |
| statement \samp{del \var{o}[\var{i1}:\var{i2}]}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} |
| Returns the \var{o} as a tuple on success, and \NULL{} on failure. |
| This is equivalent to the Python expression \samp{tuple(\var{o})}. |
| \bifuncindex{tuple} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} |
| Return the number of occurrences of \var{value} in \var{o}, that is, |
| return the number of keys for which \code{\var{o}[\var{key}] == |
| \var{value}}. On failure, return \code{-1}. This is equivalent to |
| the Python expression \samp{\var{o}.count(\var{value})}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value} |
| Determine if \var{o} contains \var{value}. If an item in \var{o} is |
| equal to \var{value}, return \code{1}, otherwise return \code{0}. On |
| error, return \code{-1}. This is equivalent to the Python expression |
| \samp{\var{value} in \var{o}}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} |
| Return the first index \var{i} for which \code{\var{o}[\var{i}] == |
| \var{value}}. On error, return \code{-1}. This is equivalent to |
| the Python expression \samp{\var{o}.index(\var{value})}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o} |
| Return a list object with the same contents as the arbitrary sequence |
| \var{o}. The returned list is guaranteed to be new. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} |
| Return a tuple object with the same contents as the arbitrary sequence |
| \var{o}. If \var{o} is a tuple, a new reference will be returned, |
| otherwise a tuple will be constructed with the appropriate contents. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m} |
| Returns the sequence \var{o} as a tuple, unless it is already a |
| tuple or list, in which case \var{o} is returned. Use |
| \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the |
| result. Returns \NULL{} on failure. If the object is not a sequence, |
| raises \exception{TypeError} with \var{m} as the message text. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i} |
| Return the \var{i}th element of \var{o}, assuming that \var{o} was |
| returned by \cfunction{PySequence_Fast()}, and that \var{i} is within |
| bounds. The caller is expected to get the length of the sequence by |
| calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples |
| are guaranteed to always return their true length. |
| \end{cfuncdesc} |
| |
| |
| \section{Mapping Protocol \label{mapping}} |
| |
| \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} |
| Return \code{1} if the object provides mapping protocol, and |
| \code{0} otherwise. This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} |
| Returns the number of keys in object \var{o} on success, and |
| \code{-1} on failure. For objects that do not provide mapping |
| protocol, this is equivalent to the Python expression |
| \samp{len(\var{o})}.\bifuncindex{len} |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} |
| Remove the mapping for object \var{key} from the object \var{o}. |
| Return \code{-1} on failure. This is equivalent to |
| the Python statement \samp{del \var{o}[\var{key}]}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} |
| Remove the mapping for object \var{key} from the object \var{o}. |
| Return \code{-1} on failure. This is equivalent to |
| the Python statement \samp{del \var{o}[\var{key}]}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} |
| On success, return \code{1} if the mapping object has the key |
| \var{key} and \code{0} otherwise. This is equivalent to the Python |
| expression \samp{\var{o}.has_key(\var{key})}. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} |
| Return \code{1} if the mapping object has the key \var{key} and |
| \code{0} otherwise. This is equivalent to the Python expression |
| \samp{\var{o}.has_key(\var{key})}. |
| This function always succeeds. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} |
| On success, return a list of the keys in object \var{o}. On |
| failure, return \NULL{}. This is equivalent to the Python |
| expression \samp{\var{o}.keys()}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} |
| On success, return a list of the values in object \var{o}. On |
| failure, return \NULL{}. This is equivalent to the Python |
| expression \samp{\var{o}.values()}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} |
| On success, return a list of the items in object \var{o}, where |
| each item is a tuple containing a key-value pair. On |
| failure, return \NULL{}. This is equivalent to the Python |
| expression \samp{\var{o}.items()}. |
| \end{cfuncdesc} |
| |
| |
| \begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} |
| Return element of \var{o} corresponding to the object \var{key} or |
| \NULL{} on failure. This is the equivalent of the Python expression |
| \samp{\var{o}[\var{key}]}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, |
| PyObject *v} |
| Map the object \var{key} to the value \var{v} in object \var{o}. |
| Returns \code{-1} on failure. This is the equivalent of the Python |
| statement \samp{\var{o}[\var{key}] = \var{v}}. |
| \end{cfuncdesc} |
| |
| |
| \section{Iterator Protocol \label{iterator}} |
| |
| \versionadded{2.2} |
| |
| There are only a couple of functions specifically for working with |
| iterators. |
| |
| \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o} |
| Return true if the object \var{o} supports the iterator protocol. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o} |
| Return the next value from the iteration \var{o}. If the object is |
| an iterator, this retrieves the next value from the iteration, and |
| returns \NULL{} with no exception set if there are no remaining |
| items. If the object is not an iterator, \exception{TypeError} is |
| raised, or if there is an error in retrieving the item, returns |
| \NULL{} and passes along the exception. |
| \end{cfuncdesc} |
| |
| To write a loop which iterates over an iterator, the C code should |
| look something like this: |
| |
| \begin{verbatim} |
| PyObject *iterator = ...; |
| PyObject *item; |
| |
| while (item = PyIter_Next(iter)) { |
| /* do something with item */ |
| } |
| if (PyErr_Occurred()) { |
| /* propogate error */ |
| } |
| else { |
| /* continue doing useful work */ |
| } |
| \end{verbatim} |
| |
| |
| \chapter{Concrete Objects Layer \label{concrete}} |
| |
| 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; |
| for example, to check that an object is a dictionary, use |
| \cfunction{PyDict_Check()}. The chapter is structured like the |
| ``family tree'' of Python object types. |
| |
| \strong{Warning:} |
| While the functions described in this chapter carefully check the type |
| of the objects which are passed in, many of them do not check for |
| \NULL{} being passed instead of a valid object. Allowing \NULL{} to |
| be passed in can cause memory access violations and immediate |
| termination of the interpreter. |
| |
| |
| \section{Fundamental Objects \label{fundamental}} |
| |
| This section describes Python type objects and the singleton object |
| \code{None}. |
| |
| |
| \subsection{Type Objects \label{typeObjects}} |
| |
| \obindex{type} |
| \begin{ctypedesc}{PyTypeObject} |
| The C structure of the objects used to describe built-in types. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyObject*}{PyType_Type} |
| This is the type object for type objects; it is the same object as |
| \code{types.TypeType} in the Python layer. |
| \withsubitem{(in module types)}{\ttindex{TypeType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyType_Check}{PyObject *o} |
| Returns true is the object \var{o} is a type object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} |
| Returns true if the type object \var{o} sets the feature |
| \var{feature}. Type features are denoted by single bit flags. |
| \end{cfuncdesc} |
| |
| |
| \subsection{The None Object \label{noneObject}} |
| |
| \obindex{None@\texttt{None}} |
| Note that the \ctype{PyTypeObject} for \code{None} is not directly |
| exposed in the Python/C API. Since \code{None} is a singleton, |
| testing for object identity (using \samp{==} in C) is sufficient. |
| There is no \cfunction{PyNone_Check()} function for the same reason. |
| |
| \begin{cvardesc}{PyObject*}{Py_None} |
| The Python \code{None} object, denoting lack of value. This object has |
| no methods. |
| \end{cvardesc} |
| |
| |
| \section{Numeric Objects \label{numericObjects}} |
| |
| \obindex{numeric} |
| |
| |
| \subsection{Plain Integer Objects \label{intObjects}} |
| |
| \obindex{integer} |
| \begin{ctypedesc}{PyIntObject} |
| This subtype of \ctype{PyObject} represents a Python integer object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyInt_Type} |
| This instance of \ctype{PyTypeObject} represents the Python plain |
| integer type. This is the same object as \code{types.IntType}. |
| \withsubitem{(in modules types)}{\ttindex{IntType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o} |
| Returns true if \var{o} is of type \cdata{PyInt_Type}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival} |
| Creates a new integer object with a value of \var{ival}. |
| |
| The current implementation keeps an array of integer objects for all |
| integers between \code{-1} and \code{100}, when you create an int in |
| that range you actually just get back a reference to the existing |
| object. So it should be possible to change the value of \code{1}. I |
| suspect the behaviour of Python in this case is undefined. :-) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} |
| Will first attempt to cast the object to a \ctype{PyIntObject}, if |
| it is not already one, and then return its value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io} |
| Returns the value of the object \var{io}. No error checking is |
| performed. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyInt_GetMax}{} |
| Returns the system's idea of the largest integer it can handle |
| (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system |
| header files). |
| \end{cfuncdesc} |
| |
| |
| \subsection{Long Integer Objects \label{longObjects}} |
| |
| \obindex{long integer} |
| \begin{ctypedesc}{PyLongObject} |
| This subtype of \ctype{PyObject} represents a Python long integer |
| object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyLong_Type} |
| This instance of \ctype{PyTypeObject} represents the Python long |
| integer type. This is the same object as \code{types.LongType}. |
| \withsubitem{(in modules types)}{\ttindex{LongType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyLongObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} |
| Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on |
| failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v} |
| Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned |
| long}, or \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} |
| Returns a new \ctype{PyLongObject} object from the integer part of |
| \var{v}, or \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong} |
| Returns a C \ctype{long} representation of the contents of |
| \var{pylong}. If \var{pylong} is greater than |
| \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is |
| raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong} |
| Returns a C \ctype{unsigned long} representation of the contents of |
| \var{pylong}. If \var{pylong} is greater than |
| \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError} |
| is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} |
| Returns a C \ctype{double} representation of the contents of \var{pylong}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend, |
| int base} |
| Return a new \ctype{PyLongObject} based on the string value in |
| \var{str}, which is interpreted according to the radix in \var{base}. |
| If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first |
| character in \var{str} which follows the representation of the |
| number. If \var{base} is \code{0}, the radix will be determined base |
| on the leading characters of \var{str}: if \var{str} starts with |
| \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts |
| with \code{'0'}, radix 8 will be used; otherwise radix 10 will be |
| used. If \var{base} is not \code{0}, it must be between \code{2} and |
| \code{36}, inclusive. Leading spaces are ignored. If there are no |
| digits, \exception{ValueError} will be raised. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Floating Point Objects \label{floatObjects}} |
| |
| \obindex{floating point} |
| \begin{ctypedesc}{PyFloatObject} |
| This subtype of \ctype{PyObject} represents a Python floating point |
| object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyFloat_Type} |
| This instance of \ctype{PyTypeObject} represents the Python floating |
| point type. This is the same object as \code{types.FloatType}. |
| \withsubitem{(in modules types)}{\ttindex{FloatType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyFloatObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} |
| Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on |
| failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} |
| Returns a C \ctype{double} representation of the contents of \var{pyfloat}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} |
| Returns a C \ctype{double} representation of the contents of |
| \var{pyfloat}, but without error checking. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Complex Number Objects \label{complexObjects}} |
| |
| \obindex{complex number} |
| Python's complex number objects are implemented as two distinct types |
| when viewed from the C API: one is the Python object exposed to |
| Python programs, and the other is a C structure which represents the |
| actual complex number value. The API provides functions for working |
| with both. |
| |
| \subsubsection{Complex Numbers as C Structures} |
| |
| Note that the functions which accept these structures as parameters |
| and return them as results do so \emph{by value} rather than |
| dereferencing them through pointers. This is consistent throughout |
| the API. |
| |
| \begin{ctypedesc}{Py_complex} |
| The C structure which corresponds to the value portion of a Python |
| complex number object. Most of the functions for dealing with complex |
| number objects use structures of this type as input or output values, |
| as appropriate. It is defined as: |
| |
| \begin{verbatim} |
| typedef struct { |
| double real; |
| double imag; |
| } Py_complex; |
| \end{verbatim} |
| \end{ctypedesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right} |
| Return the sum of two complex numbers, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right} |
| Return the difference between two complex numbers, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex} |
| Return the negation of the complex number \var{complex}, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right} |
| Return the product of two complex numbers, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend, |
| Py_complex divisor} |
| Return the quotient of two complex numbers, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp} |
| Return the exponentiation of \var{num} by \var{exp}, using the C |
| \ctype{Py_complex} representation. |
| \end{cfuncdesc} |
| |
| |
| \subsubsection{Complex Numbers as Python Objects} |
| |
| \begin{ctypedesc}{PyComplexObject} |
| This subtype of \ctype{PyObject} represents a Python complex number object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyComplex_Type} |
| This instance of \ctype{PyTypeObject} represents the Python complex |
| number type. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyComplexObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v} |
| Create a new Python complex number object from a C |
| \ctype{Py_complex} value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag} |
| Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op} |
| Returns the real part of \var{op} as a C \ctype{double}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op} |
| Returns the imaginary part of \var{op} as a C \ctype{double}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} |
| Returns the \ctype{Py_complex} value of the complex number \var{op}. |
| \end{cfuncdesc} |
| |
| |
| |
| \section{Sequence Objects \label{sequenceObjects}} |
| |
| \obindex{sequence} |
| 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 \label{stringObjects}} |
| |
| These functions raise \exception{TypeError} when expecting a string |
| parameter and are called with a non-string parameter. |
| |
| \obindex{string} |
| \begin{ctypedesc}{PyStringObject} |
| This subtype of \ctype{PyObject} represents a Python string object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyString_Type} |
| This instance of \ctype{PyTypeObject} represents the Python string |
| type; it is the same object as \code{types.TypeType} in the Python |
| layer.\withsubitem{(in module types)}{\ttindex{StringType}}. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} |
| Returns true if the object \var{o} is a string object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v} |
| Returns a new string object with the value \var{v} on success, and |
| \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v, |
| int len} |
| Returns a new string object with the value \var{v} and length |
| \var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{}, |
| the contents of the string are uninitialized. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyString_Size}{PyObject *string} |
| Returns the length of the string in string object \var{string}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string} |
| Macro form of \cfunction{PyString_Size()} but without error |
| checking. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} |
| Returns a null-terminated representation of the contents of |
| \var{string}. The pointer refers to the internal buffer of |
| \var{string}, not a copy. The data must not be modified in any way, |
| unless the string was just created using |
| \code{PyString_FromStringAndSize(NULL, \var{size})}. |
| It must not be deallocated. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} |
| Macro form of \cfunction{PyString_AsString()} but without error |
| checking. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj, |
| char **buffer, |
| int *length} |
| Returns a null-terminated representation of the contents of the object |
| \var{obj} through the output variables \var{buffer} and \var{length}. |
| |
| The function accepts both string and Unicode objects as input. For |
| Unicode objects it returns the default encoded version of the object. |
| If \var{length} is set to \NULL{}, the resulting buffer may not contain |
| null characters; if it does, the function returns -1 and a |
| TypeError is raised. |
| |
| The buffer refers to an internal string buffer of \var{obj}, not a |
| copy. The data must not be modified in any way, unless the string was |
| just created using \code{PyString_FromStringAndSize(NULL, |
| \var{size})}. It must not be deallocated. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, |
| PyObject *newpart} |
| Creates a new string object in \var{*string} containing the |
| contents of \var{newpart} appended to \var{string}; the caller will |
| own the new reference. The reference to the old value of \var{string} |
| will be stolen. If the new string |
| cannot be created, the old reference to \var{string} will still be |
| discarded and the value of \var{*string} will be set to |
| \NULL{}; the appropriate exception will be set. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string, |
| PyObject *newpart} |
| Creates a new string object in \var{*string} containing the contents |
| of \var{newpart} appended to \var{string}. This version decrements |
| the reference count of \var{newpart}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize} |
| A way to resize a string object even though it is ``immutable''. |
| Only use this to build up a brand new string object; don't use this if |
| the string may already be known in other parts of the code. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format, |
| PyObject *args} |
| Returns a new string object from \var{format} and \var{args}. Analogous |
| to \code{\var{format} \%\ \var{args}}. The \var{args} argument must be |
| a tuple. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string} |
| Intern the argument \var{*string} in place. The argument must be the |
| address of a pointer variable pointing to a Python string object. |
| If there is an existing interned string that is the same as |
| \var{*string}, it sets \var{*string} to it (decrementing the reference |
| count of the old string object and incrementing the reference count of |
| the interned string object), otherwise it leaves \var{*string} alone |
| and interns it (incrementing its reference count). (Clarification: |
| even though there is a lot of talk about reference counts, think of |
| this function as reference-count-neutral; you own the object after |
| the call if and only if you owned it before the call.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v} |
| A combination of \cfunction{PyString_FromString()} and |
| \cfunction{PyString_InternInPlace()}, returning either a new string object |
| that has been interned, or a new (``owned'') reference to an earlier |
| interned string object with the same value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s, |
| int size, |
| const char *encoding, |
| const char *errors} |
| Creates an object by decoding \var{size} bytes of the encoded |
| buffer \var{s} using the codec registered |
| for \var{encoding}. \var{encoding} and \var{errors} have the same meaning |
| as the parameters of the same name in the unicode() builtin |
| function. The codec to be used is looked up using the Python codec |
| registry. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str, |
| const char *encoding, |
| const char *errors} |
| Decodes a string object by passing it to the codec registered |
| for \var{encoding} and returns the result as Python |
| object. \var{encoding} and \var{errors} have the same meaning as the |
| parameters of the same name in the string .encode() method. The codec |
| to be used is looked up using the Python codec registry. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s, |
| int size, |
| const char *encoding, |
| const char *errors} |
| Encodes the \ctype{char} buffer of the given size by passing it to |
| the codec registered for \var{encoding} and returns a Python object. |
| \var{encoding} and \var{errors} have the same |
| meaning as the parameters of the same name in the string .encode() |
| method. The codec to be used is looked up using the Python codec |
| registry. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str, |
| const char *encoding, |
| const char *errors} |
| Encodes a string object using the codec registered |
| for \var{encoding} and returns the result as Python |
| object. \var{encoding} and \var{errors} have the same meaning as the |
| parameters of the same name in the string .encode() method. The codec |
| to be used is looked up using the Python codec registry. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Unicode Objects \label{unicodeObjects}} |
| \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} |
| |
| %--- Unicode Type ------------------------------------------------------- |
| |
| These are the basic Unicode object types used for the Unicode |
| implementation in Python: |
| |
| \begin{ctypedesc}{Py_UNICODE} |
| This type represents a 16-bit unsigned storage type which is used by |
| Python internally as basis for holding Unicode ordinals. On platforms |
| where \ctype{wchar_t} is available and also has 16-bits, |
| \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance |
| native platform compatibility. On all other platforms, |
| \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}{PyUnicodeObject} |
| This subtype of \ctype{PyObject} represents a Python Unicode object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyUnicode_Type} |
| This instance of \ctype{PyTypeObject} represents the Python Unicode type. |
| \end{cvardesc} |
| |
| %--- These are really C macros... is there a macrodesc TeX macro ? |
| |
| The following APIs are really C macros and can be used to do fast |
| checks and to access internal read-only data of Unicode objects: |
| |
| \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o} |
| Returns true if the object \var{o} is a Unicode object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o} |
| Returns the size of the object. o has to be a |
| PyUnicodeObject (not checked). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o} |
| Returns the size of the object's internal buffer in bytes. o has to be |
| a PyUnicodeObject (not checked). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o} |
| Returns a pointer to the internal Py_UNICODE buffer of the object. o |
| has to be a PyUnicodeObject (not checked). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o} |
| Returns a (const char *) pointer to the internal buffer of the object. |
| o has to be a PyUnicodeObject (not checked). |
| \end{cfuncdesc} |
| |
| % --- Unicode character properties --------------------------------------- |
| |
| Unicode provides many different character properties. The most often |
| needed ones are available through these macros which are mapped to C |
| functions depending on the Python configuration. |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a whitespace character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a lowercase character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is an uppercase character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a titlecase character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a linebreak character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a decimal character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a digit character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is a numeric character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is an alphabetic character. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch} |
| Returns 1/0 depending on whether \var{ch} is an alphanumeric character. |
| \end{cfuncdesc} |
| |
| These APIs can be used for fast direct character conversions: |
| |
| \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to lower case. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to upper case. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to title case. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to a decimal positive integer. |
| Returns -1 in case this is not possible. Does not raise exceptions. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to a single digit integer. |
| Returns -1 in case this is not possible. Does not raise exceptions. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch} |
| Returns the character \var{ch} converted to a (positive) double. |
| Returns -1.0 in case this is not possible. Does not raise exceptions. |
| \end{cfuncdesc} |
| |
| % --- Plain Py_UNICODE --------------------------------------------------- |
| |
| To create Unicode objects and access their basic sequence properties, |
| use these APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u, |
| int size} |
| |
| Create a Unicode Object from the Py_UNICODE buffer \var{u} of the |
| given size. \var{u} may be \NULL{} which causes the contents to be |
| undefined. It is the user's responsibility to fill in the needed data. |
| The buffer is copied into the new object. If the buffer is not \NULL{}, |
| the return value might be a shared object. Therefore, modification of |
| the resulting Unicode Object is only allowed when \var{u} is \NULL{}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} |
| Return a read-only pointer to the Unicode object's internal |
| \ctype{Py_UNICODE} buffer. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode} |
| Return the length of the Unicode object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj, |
| const char *encoding, |
| const char *errors} |
| |
| Coerce an encoded object obj to an Unicode object and return a |
| reference with incremented refcount. |
| |
| Coercion is done in the following way: |
| \begin{enumerate} |
| \item Unicode objects are passed back as-is with incremented |
| refcount. Note: these cannot be decoded; passing a non-NULL |
| value for encoding will result in a TypeError. |
| |
| \item String and other char buffer compatible objects are decoded |
| according to the given encoding and using the error handling |
| defined by errors. Both can be NULL to have the interface use |
| the default values (see the next section for details). |
| |
| \item All other objects cause an exception. |
| \end{enumerate} |
| The API returns NULL in case of an error. The caller is responsible |
| for decref'ing the returned objects. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj} |
| |
| Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'') |
| which is used throughout the interpreter whenever coercion to |
| Unicode is needed. |
| \end{cfuncdesc} |
| |
| % --- wchar_t support for platforms which support it --------------------- |
| |
| If the platform supports \ctype{wchar_t} and provides a header file |
| wchar.h, Python can interface directly to this type using the |
| following functions. Support is optimized if Python's own |
| \ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w, |
| int size} |
| Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the |
| given size. Returns \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, |
| wchar_t *w, |
| int size} |
| Copies the Unicode Object contents into the \ctype{whcar_t} buffer |
| \var{w}. At most \var{size} \ctype{whcar_t} characters are copied. |
| Returns the number of \ctype{whcar_t} characters copied or -1 in case |
| of an error. |
| \end{cfuncdesc} |
| |
| |
| \subsubsection{Builtin Codecs \label{builtinCodecs}} |
| |
| Python provides a set of builtin codecs which are written in C |
| for speed. All of these codecs are directly usable via the |
| following functions. |
| |
| Many of the following APIs take two arguments encoding and |
| errors. These parameters encoding and errors have the same semantics |
| as the ones of the builtin unicode() Unicode object constructor. |
| |
| Setting encoding to NULL causes the default encoding to be used which |
| is UTF-8. |
| |
| Error handling is set by errors which may also be set to NULL meaning |
| to use the default handling defined for the codec. Default error |
| handling for all builtin codecs is ``strict'' (ValueErrors are raised). |
| |
| The codecs all use a similar interface. Only deviation from the |
| following generic ones are documented for simplicity. |
| |
| % --- Generic Codecs ----------------------------------------------------- |
| |
| These are the generic codec APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s, |
| int size, |
| const char *encoding, |
| const char *errors} |
| Create a Unicode object by decoding \var{size} bytes of the encoded |
| string \var{s}. \var{encoding} and \var{errors} have the same meaning |
| as the parameters of the same name in the unicode() builtin |
| function. The codec to be used is looked up using the Python codec |
| registry. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s, |
| int size, |
| const char *encoding, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a |
| Python string object. \var{encoding} and \var{errors} have the same |
| meaning as the parameters of the same name in the Unicode .encode() |
| method. The codec to be used is looked up using the Python codec |
| registry. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, |
| const char *encoding, |
| const char *errors} |
| Encodes a Unicode object and returns the result as Python string |
| object. \var{encoding} and \var{errors} have the same meaning as the |
| parameters of the same name in the Unicode .encode() method. The codec |
| to be used is looked up using the Python codec registry. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- UTF-8 Codecs ------------------------------------------------------- |
| |
| These are the UTF-8 codec APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the UTF-8 |
| encoded string \var{s}. Returns \NULL{} in case an exception was |
| raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8 |
| and returns a Python string object. Returns \NULL{} in case an |
| exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} |
| Encodes a Unicode objects using UTF-8 and returns the result as Python |
| string object. Error handling is ``strict''. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- UTF-16 Codecs ------------------------------------------------------ */ |
| |
| These are the UTF-16 codec APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s, |
| int size, |
| const char *errors, |
| int *byteorder} |
| Decodes \var{length} bytes from a UTF-16 encoded buffer string and |
| returns the corresponding Unicode object. |
| |
| \var{errors} (if non-NULL) defines the error handling. It defaults |
| to ``strict''. |
| |
| If \var{byteorder} is non-\NULL{}, the decoder starts decoding using |
| the given byte order: |
| |
| \begin{verbatim} |
| *byteorder == -1: little endian |
| *byteorder == 0: native order |
| *byteorder == 1: big endian |
| \end{verbatim} |
| |
| and then switches according to all byte order marks (BOM) it finds in |
| the input data. BOM marks are not copied into the resulting Unicode |
| string. After completion, \var{*byteorder} is set to the current byte |
| order at the end of input data. |
| |
| If \var{byteorder} is \NULL{}, the codec starts in native order mode. |
| |
| Returns \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, |
| int size, |
| const char *errors, |
| int byteorder} |
| Returns a Python string object holding the UTF-16 encoded value of the |
| Unicode data in \var{s}. |
| |
| If \var{byteorder} is not \code{0}, output is written according to the |
| following byte order: |
| |
| \begin{verbatim} |
| byteorder == -1: little endian |
| byteorder == 0: native byte order (writes a BOM mark) |
| byteorder == 1: big endian |
| \end{verbatim} |
| |
| If byteorder is \code{0}, the output string will always start with the |
| Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is |
| prepended. |
| |
| Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16 |
| reduced to UCS-2. This trick makes it possible to add full UTF-16 |
| capabilities at a later point without comprimising the APIs. |
| |
| Returns \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode} |
| Returns a Python string using the UTF-16 encoding in native byte |
| order. The string always starts with a BOM mark. Error handling is |
| ``strict''. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| % --- Unicode-Escape Codecs ---------------------------------------------- |
| |
| These are the ``Unicode Esacpe'' codec APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe |
| encoded string \var{s}. Returns \NULL{} in case an exception was |
| raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape |
| and returns a Python string object. Returns \NULL{} in case an |
| exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} |
| Encodes a Unicode objects using Unicode-Escape and returns the result |
| as Python string object. Error handling is ``strict''. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- Raw-Unicode-Escape Codecs ------------------------------------------ |
| |
| These are the ``Raw Unicode Esacpe'' codec APIs: |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe |
| encoded string \var{s}. Returns \NULL{} in case an exception was |
| raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape |
| and returns a Python string object. Returns \NULL{} in case an |
| exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} |
| Encodes a Unicode objects using Raw-Unicode-Escape and returns the result |
| as Python string object. Error handling is ``strict''. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- Latin-1 Codecs ----------------------------------------------------- |
| |
| These are the Latin-1 codec APIs: |
| |
| Latin-1 corresponds to the first 256 Unicode ordinals and only these |
| are accepted by the codecs during encoding. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the Latin-1 |
| encoded string \var{s}. Returns \NULL{} in case an exception was |
| raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1 |
| and returns a Python string object. Returns \NULL{} in case an |
| exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} |
| Encodes a Unicode objects using Latin-1 and returns the result as |
| Python string object. Error handling is ``strict''. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- ASCII Codecs ------------------------------------------------------- |
| |
| These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is |
| accepted. All other codes generate errors. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the |
| \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception |
| was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using |
| \ASCII{} and returns a Python string object. Returns \NULL{} in case |
| an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} |
| Encodes a Unicode objects using \ASCII{} and returns the result as Python |
| string object. Error handling is ``strict''. Returns |
| \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- Character Map Codecs ----------------------------------------------- |
| |
| These are the mapping codec APIs: |
| |
| This codec is special in that it can be used to implement many |
| different codecs (and this is in fact what was done to obtain most of |
| the standard codecs included in the \module{encodings} package). The |
| codec uses mapping to encode and decode characters. |
| |
| Decoding mappings must map single string characters to single Unicode |
| characters, integers (which are then interpreted as Unicode ordinals) |
| or None (meaning "undefined mapping" and causing an error). |
| |
| Encoding mappings must map single Unicode characters to single string |
| characters, integers (which are then interpreted as Latin-1 ordinals) |
| or None (meaning "undefined mapping" and causing an error). |
| |
| The mapping objects provided must only support the __getitem__ mapping |
| interface. |
| |
| If a character lookup fails with a LookupError, the character is |
| copied as-is meaning that its ordinal value will be interpreted as |
| Unicode or Latin-1 ordinal resp. Because of this, mappings only need |
| to contain those mappings which map characters to different code |
| points. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s, |
| int size, |
| PyObject *mapping, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the encoded |
| string \var{s} using the given \var{mapping} object. Returns \NULL{} |
| in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s, |
| int size, |
| PyObject *mapping, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using the |
| given \var{mapping} object and returns a Python string object. |
| Returns \NULL{} in case an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, |
| PyObject *mapping} |
| Encodes a Unicode objects using the given \var{mapping} object and |
| returns the result as Python string object. Error handling is |
| ``strict''. Returns \NULL{} in case an exception was raised by the |
| codec. |
| \end{cfuncdesc} |
| |
| The following codec API is special in that maps Unicode to Unicode. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s, |
| int size, |
| PyObject *table, |
| const char *errors} |
| Translates a \ctype{Py_UNICODE} buffer of the given length by applying |
| a character mapping \var{table} to it and returns the resulting |
| Unicode object. Returns \NULL{} when an exception was raised by the |
| codec. |
| |
| The \var{mapping} table must map Unicode ordinal integers to Unicode |
| ordinal integers or None (causing deletion of the character). |
| |
| Mapping tables must only provide the __getitem__ interface, |
| e.g. dictionaries or sequences. Unmapped character ordinals (ones |
| which cause a LookupError) are left untouched and are copied as-is. |
| \end{cfuncdesc} |
| |
| % --- MBCS codecs for Windows -------------------------------------------- |
| |
| These are the MBCS codec APIs. They are currently only available on |
| Windows and use the Win32 MBCS converters to implement the |
| conversions. Note that MBCS (or DBCS) is a class of encodings, not |
| just one. The target encoding is defined by the user settings on the |
| machine running the codec. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, |
| int size, |
| const char *errors} |
| Creates a Unicode object by decoding \var{size} bytes of the MBCS |
| encoded string \var{s}. Returns \NULL{} in case an exception was |
| raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, |
| int size, |
| const char *errors} |
| Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS |
| and returns a Python string object. Returns \NULL{} in case an |
| exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} |
| Encodes a Unicode objects using MBCS and returns the result as Python |
| string object. Error handling is ``strict''. Returns \NULL{} in case |
| an exception was raised by the codec. |
| \end{cfuncdesc} |
| |
| % --- Methods & Slots ---------------------------------------------------- |
| |
| \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}} |
| |
| The following APIs are capable of handling Unicode objects and strings |
| on input (we refer to them as strings in the descriptions) and return |
| Unicode objects or integers as apporpriate. |
| |
| They all return \NULL{} or -1 in case an exception occurrs. |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, |
| PyObject *right} |
| Concat two strings giving a new Unicode string. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, |
| PyObject *sep, |
| int maxsplit} |
| Split a string giving a list of Unicode strings. |
| |
| If sep is NULL, splitting will be done at all whitespace |
| substrings. Otherwise, splits occur at the given separator. |
| |
| At most maxsplit splits will be done. If negative, no limit is set. |
| |
| Separators are not included in the resulting list. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, |
| int maxsplit} |
| Split a Unicode string at line breaks, returning a list of Unicode |
| strings. CRLF is considered to be one line break. The Line break |
| characters are not included in the resulting strings. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, |
| PyObject *table, |
| const char *errors} |
| Translate a string by applying a character mapping table to it and |
| return the resulting Unicode object. |
| |
| The mapping table must map Unicode ordinal integers to Unicode ordinal |
| integers or None (causing deletion of the character). |
| |
| Mapping tables must only provide the __getitem__ interface, |
| e.g. dictionaries or sequences. Unmapped character ordinals (ones |
| which cause a LookupError) are left untouched and are copied as-is. |
| |
| \var{errors} has the usual meaning for codecs. It may be \NULL{} |
| which indicates to use the default error handling. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, |
| PyObject *seq} |
| Join a sequence of strings using the given separator and return |
| the resulting Unicode string. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str, |
| PyObject *substr, |
| int start, |
| int end, |
| int direction} |
| Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at |
| the given tail end (\var{direction} == -1 means to do a prefix match, |
| \var{direction} == 1 a suffix match), 0 otherwise. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str, |
| PyObject *substr, |
| int start, |
| int end, |
| int direction} |
| Return the first position of \var{substr} in |
| \var{str}[\var{start}:\var{end}] using the given \var{direction} |
| (\var{direction} == 1 means to do a forward search, |
| \var{direction} == -1 a backward search), 0 otherwise. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str, |
| PyObject *substr, |
| int start, |
| int end} |
| Count the number of occurrences of \var{substr} in |
| \var{str}[\var{start}:\var{end}] |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str, |
| PyObject *substr, |
| PyObject *replstr, |
| int maxcount} |
| Replace at most \var{maxcount} occurrences of \var{substr} in |
| \var{str} with \var{replstr} and return the resulting Unicode object. |
| \var{maxcount} == -1 means: replace all occurrences. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} |
| Compare two strings and return -1, 0, 1 for less than, equal, |
| greater than resp. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, |
| PyObject *args} |
| Returns a new string object from \var{format} and \var{args}; this is |
| analogous to \code{\var{format} \%\ \var{args}}. The |
| \var{args} argument must be a tuple. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, |
| PyObject *element} |
| Checks whether \var{element} is contained in \var{container} and |
| returns true or false accordingly. |
| |
| \var{element} has to coerce to a one element Unicode string. \code{-1} is |
| returned in case of an error. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Buffer Objects \label{bufferObjects}} |
| \sectionauthor{Greg Stein}{gstein@lyra.org} |
| |
| \obindex{buffer} |
| Python objects implemented in C can export a group of functions called |
| the ``buffer\index{buffer interface} interface.'' These functions can |
| be used by an object to expose its data in a raw, byte-oriented |
| format. Clients of the object can use the buffer interface to access |
| the object data directly, without needing to copy it first. |
| |
| Two examples of objects that support |
| the buffer interface are strings and arrays. The string object exposes |
| the character contents in the buffer interface's byte-oriented |
| form. An array can also expose its contents, but it should be noted |
| that array elements may be multi-byte values. |
| |
| An example user of the buffer interface is the file object's |
| \method{write()} method. Any object that can export a series of bytes |
| through the buffer interface can be written to a file. There are a |
| number of format codes to \cfunction{PyArg_ParseTuple()} that operate |
| against an object's buffer interface, returning data from the target |
| object. |
| |
| More information on the buffer interface is provided in the section |
| ``Buffer Object Structures'' (section \ref{buffer-structs}), under |
| the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}. |
| |
| A ``buffer object'' is defined in the \file{bufferobject.h} header |
| (included by \file{Python.h}). These objects look very similar to |
| string objects at the Python programming level: they support slicing, |
| indexing, concatenation, and some other standard string |
| operations. However, their data can come from one of two sources: from |
| a block of memory, or from another object which exports the buffer |
| interface. |
| |
| Buffer objects are useful as a way to expose the data from another |
| object's buffer interface to the Python programmer. They can also be |
| used as a zero-copy slicing mechanism. Using their ability to |
| reference a block of memory, it is possible to expose any data to the |
| Python programmer quite easily. The memory could be a large, constant |
| array in a C extension, it could be a raw block of memory for |
| manipulation before passing to an operating system library, or it |
| could be used to pass around structured data in its native, in-memory |
| format. |
| |
| \begin{ctypedesc}{PyBufferObject} |
| This subtype of \ctype{PyObject} represents a buffer object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyBuffer_Type} |
| The instance of \ctype{PyTypeObject} which represents the Python |
| buffer type; it is the same object as \code{types.BufferType} in the |
| Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}. |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{Py_END_OF_BUFFER} |
| This constant may be passed as the \var{size} parameter to |
| \cfunction{PyBuffer_FromObject()} or |
| \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new |
| \ctype{PyBufferObject} should refer to \var{base} object from the |
| specified \var{offset} to the end of its exported buffer. Using this |
| enables the caller to avoid querying the \var{base} object for its |
| length. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p} |
| Return true if the argument has type \cdata{PyBuffer_Type}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base, |
| int offset, int size} |
| Return a new read-only buffer object. This raises |
| \exception{TypeError} if \var{base} doesn't support the read-only |
| buffer protocol or doesn't provide exactly one buffer segment, or it |
| raises \exception{ValueError} if \var{offset} is less than zero. The |
| buffer will hold a reference to the \var{base} object, and the |
| buffer's contents will refer to the \var{base} object's buffer |
| interface, starting as position \var{offset} and extending for |
| \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then |
| the new buffer's contents extend to the length of the |
| \var{base} object's exported buffer data. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base, |
| int offset, |
| int size} |
| Return a new writable buffer object. Parameters and exceptions are |
| similar to those for \cfunction{PyBuffer_FromObject()}. |
| If the \var{base} object does not export the writeable buffer |
| protocol, then \exception{TypeError} is raised. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size} |
| Return a new read-only buffer object that reads from a specified |
| location in memory, with a specified size. |
| The caller is responsible for ensuring that the memory buffer, passed |
| in as \var{ptr}, is not deallocated while the returned buffer object |
| exists. Raises \exception{ValueError} if \var{size} is less than |
| zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed |
| for the \var{size} parameter; \exception{ValueError} will be raised in |
| that case. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size} |
| Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer |
| is writable. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size} |
| Returns a new writable buffer object that maintains its own memory |
| buffer of \var{size} bytes. \exception{ValueError} is returned if |
| \var{size} is not zero or positive. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Tuple Objects \label{tupleObjects}} |
| |
| \obindex{tuple} |
| \begin{ctypedesc}{PyTupleObject} |
| This subtype of \ctype{PyObject} represents a Python tuple object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyTuple_Type} |
| This instance of \ctype{PyTypeObject} represents the Python tuple |
| type; it is the same object as \code{types.TupleType} in the Python |
| layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} |
| Return true if the argument is a tuple object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len} |
| Return a new tuple object of size \var{len}, or \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} |
| Takes a pointer to a tuple object, and returns the size |
| of that tuple. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos} |
| Returns the object at position \var{pos} in the tuple pointed |
| to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and |
| sets an \exception{IndexError} exception. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos} |
| Like \cfunction{PyTuple_GetItem()}, but does no checking of its |
| arguments. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, |
| int low, int high} |
| Takes a slice of the tuple pointed to by \var{p} from |
| \var{low} to \var{high} and returns it as a new tuple. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p, |
| int pos, PyObject *o} |
| Inserts a reference to object \var{o} at position \var{pos} of |
| the tuple pointed to by \var{p}. It returns \code{0} on success. |
| \strong{Note:} This function ``steals'' a reference to \var{o}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p, |
| int pos, PyObject *o} |
| Like \cfunction{PyTuple_SetItem()}, but does no error checking, and |
| should \emph{only} be used to fill in brand new tuples. |
| \strong{Note:} This function ``steals'' a reference to \var{o}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize} |
| Can be used to resize a tuple. \var{newsize} will be the new length |
| of the tuple. Because tuples are \emph{supposed} to be immutable, |
| this should only be used if there is only one reference to the object. |
| Do \emph{not} use this if the tuple may already be known to some other |
| part of the code. The tuple will always grow or shrink at the end. |
| Think of this as destroying the old tuple and creating a new one, only |
| more efficiently. Returns \code{0} on success. Client code should |
| never assume that the resulting value of \code{*\var{p}} will be the |
| same as before calling this function. If the object referenced by |
| \code{*\var{p}} is replaced, the original \code{*\var{p}} is |
| destroyed. On failure, returns \code{-1} and sets \code{*\var{p}} to |
| \NULL, and raises \exception{MemoryError} or \exception{SystemError}. |
| \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} |
| \end{cfuncdesc} |
| |
| |
| \subsection{List Objects \label{listObjects}} |
| |
| \obindex{list} |
| \begin{ctypedesc}{PyListObject} |
| This subtype of \ctype{PyObject} represents a Python list object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyList_Type} |
| This instance of \ctype{PyTypeObject} represents the Python list |
| type. This is the same object as \code{types.ListType}. |
| \withsubitem{(in module types)}{\ttindex{ListType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyListObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyList_New}{int len} |
| Returns a new list of length \var{len} on success, or \NULL{} on |
| failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Size}{PyObject *list} |
| Returns the length of the list object in \var{list}; this is |
| equivalent to \samp{len(\var{list})} on a list object. |
| \bifuncindex{len} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} |
| Macro form of \cfunction{PyList_Size()} without error checking. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index} |
| Returns the object at position \var{pos} in the list pointed |
| to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and |
| sets an \exception{IndexError} exception. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i} |
| Macro form of \cfunction{PyList_GetItem()} without error checking. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index, |
| PyObject *item} |
| Sets the item at index \var{index} in list to \var{item}. |
| Returns \code{0} on success or \code{-1} on failure. |
| \strong{Note:} This function ``steals'' a reference to \var{item} and |
| discards a reference to an item already in the list at the affected |
| position. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i, |
| PyObject *o} |
| Macro form of \cfunction{PyList_SetItem()} without error checking. |
| \strong{Note:} This function ``steals'' a reference to \var{item}, |
| and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a |
| reference to any item that it being replaced; any reference in |
| \var{list} at position \var{i} will be leaked. This is normally only |
| used to fill in new lists where there is no previous content. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index, |
| PyObject *item} |
| Inserts the item \var{item} into list \var{list} in front of index |
| \var{index}. Returns \code{0} if successful; returns \code{-1} and |
| raises an exception if unsuccessful. Analogous to |
| \code{\var{list}.insert(\var{index}, \var{item})}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item} |
| Appends the object \var{item} at the end of list \var{list}. Returns |
| \code{0} if successful; returns \code{-1} and sets an exception if |
| unsuccessful. Analogous to \code{\var{list}.append(\var{item})}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list, |
| int low, int high} |
| Returns a list of the objects in \var{list} containing the objects |
| \emph{between} \var{low} and \var{high}. Returns NULL and sets an |
| exception if unsuccessful. |
| Analogous to \code{\var{list}[\var{low}:\var{high}]}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list, |
| int low, int high, |
| PyObject *itemlist} |
| Sets the slice of \var{list} between \var{low} and \var{high} to the |
| contents of \var{itemlist}. Analogous to |
| \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. Returns |
| \code{0} on success, \code{-1} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list} |
| Sorts the items of \var{list} in place. Returns \code{0} on success, |
| \code{-1} on failure. This is equivalent to |
| \samp{\var{list}.sort()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list} |
| Reverses the items of \var{list} in place. Returns \code{0} on |
| success, \code{-1} on failure. This is the equivalent of |
| \samp{\var{list}.reverse()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list} |
| Returns a new tuple object containing the contents of \var{list}; |
| equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple} |
| \end{cfuncdesc} |
| |
| |
| \section{Mapping Objects \label{mapObjects}} |
| |
| \obindex{mapping} |
| |
| |
| \subsection{Dictionary Objects \label{dictObjects}} |
| |
| \obindex{dictionary} |
| \begin{ctypedesc}{PyDictObject} |
| This subtype of \ctype{PyObject} represents a Python dictionary object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyDict_Type} |
| This instance of \ctype{PyTypeObject} represents the Python dictionary |
| type. This is exposed to Python programs as \code{types.DictType} and |
| \code{types.DictionaryType}. |
| \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyDictObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_New}{} |
| Returns a new empty dictionary, or \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p} |
| Empties an existing dictionary of all key-value pairs. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} |
| Returns a new dictionary that contains the same key-value pairs as p. |
| Empties an existing dictionary of all key-value pairs. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key, |
| PyObject *val} |
| Inserts \var{value} into the dictionary \var{p} with a key of \var{key}. |
| \var{key} must be hashable; if it isn't, \exception{TypeError} will be |
| raised. |
| Returns \code{0} on success or \code{-1} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, |
| char *key, |
| PyObject *val} |
| Inserts \var{value} into the dictionary \var{p} using \var{key} |
| as a key. \var{key} should be a \ctype{char*}. The key object is |
| created using \code{PyString_FromString(\var{key})}. |
| Returns \code{0} on success or \code{-1} on failure. |
| \ttindex{PyString_FromString()} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key} |
| Removes the entry in dictionary \var{p} with key \var{key}. |
| \var{key} must be hashable; if it isn't, \exception{TypeError} is |
| raised. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key} |
| Removes the entry in dictionary \var{p} which has a key |
| specified by the string \var{key}. |
| Returns \code{0} on success or \code{-1} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key} |
| Returns the object from dictionary \var{p} which has a key |
| \var{key}. Returns \NULL{} if the key \var{key} is not present, but |
| \emph{without} setting an exception. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key} |
| This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is |
| specified as a \ctype{char*}, rather than a \ctype{PyObject*}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p} |
| Returns a \ctype{PyListObject} containing all the items |
| from the dictionary, as in the dictinoary method \method{items()} (see |
| the \citetitle[../lib/lib.html]{Python Library Reference}). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p} |
| Returns a \ctype{PyListObject} containing all the keys |
| from the dictionary, as in the dictionary method \method{keys()} (see the |
| \citetitle[../lib/lib.html]{Python Library Reference}). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p} |
| Returns a \ctype{PyListObject} containing all the values |
| from the dictionary \var{p}, as in the dictionary method |
| \method{values()} (see the \citetitle[../lib/lib.html]{Python Library |
| Reference}). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p} |
| Returns the number of items in the dictionary. This is equivalent to |
| \samp{len(\var{p})} on a dictionary.\bifuncindex{len} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos, |
| PyObject **pkey, PyObject **pvalue} |
| Iterate over all key-value pairs in the dictionary \var{p}. The |
| \ctype{int} referred to by \var{ppos} must be initialized to \code{0} |
| prior to the first call to this function to start the iteration; the |
| function returns true for each pair in the dictionary, and false once |
| all pairs have been reported. The parameters \var{pkey} and |
| \var{pvalue} should either point to \ctype{PyObject*} variables that |
| will be filled in with each key and value, respectively, or may be |
| \NULL. |
| |
| For example: |
| |
| \begin{verbatim} |
| PyObject *key, *value; |
| int pos = 0; |
| |
| while (PyDict_Next(self->dict, &pos, &key, &value)) { |
| /* do something interesting with the values... */ |
| ... |
| } |
| \end{verbatim} |
| |
| The dictionary \var{p} should not be mutated during iteration. It is |
| safe (since Python 2.1) to modify the values of the keys as you |
| iterate over the dictionary, for example: |
| |
| \begin{verbatim} |
| PyObject *key, *value; |
| int pos = 0; |
| |
| while (PyDict_Next(self->dict, &pos, &key, &value)) { |
| int i = PyInt_AS_LONG(value) + 1; |
| PyObject *o = PyInt_FromLong(i); |
| if (o == NULL) |
| return -1; |
| if (PyDict_SetItem(self->dict, key, o) < 0) { |
| Py_DECREF(o); |
| return -1; |
| } |
| Py_DECREF(o); |
| } |
| \end{verbatim} |
| \end{cfuncdesc} |
| |
| |
| \section{Other Objects \label{otherObjects}} |
| |
| \subsection{File Objects \label{fileObjects}} |
| |
| \obindex{file} |
| Python's built-in file objects are implemented entirely on the |
| \ctype{FILE*} support from the C standard library. This is an |
| implementation detail and may change in future releases of Python. |
| |
| \begin{ctypedesc}{PyFileObject} |
| This subtype of \ctype{PyObject} represents a Python file object. |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{PyTypeObject}{PyFile_Type} |
| This instance of \ctype{PyTypeObject} represents the Python file |
| type. This is exposed to Python programs as \code{types.FileType}. |
| \withsubitem{(in module types)}{\ttindex{FileType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyFileObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode} |
| On success, returns a new file object that is opened on the |
| file given by \var{filename}, with a file mode given by \var{mode}, |
| where \var{mode} has the same semantics as the standard C routine |
| \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, |
| char *name, char *mode, |
| int (*close)(FILE*)} |
| Creates a new \ctype{PyFileObject} from the already-open standard C |
| file pointer, \var{fp}. The function \var{close} will be called when |
| the file should be closed. Returns \NULL{} on failure. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p} |
| Returns the file object associated with \var{p} as a \ctype{FILE*}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n} |
| Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this |
| function reads one line from the object \var{p}. \var{p} may be a |
| file object or any object with a \method{readline()} method. If |
| \var{n} is \code{0}, exactly one line is read, regardless of the |
| length of the line. If \var{n} is greater than \code{0}, no more than |
| \var{n} bytes will be read from the file; a partial line can be |
| returned. In both cases, an empty string is returned if the end of |
| the file is reached immediately. If \var{n} is less than \code{0}, |
| however, one line is read regardless of length, but |
| \exception{EOFError} is raised if the end of the file is reached |
| immediately. |
| \withsubitem{(built-in exception)}{\ttindex{EOFError}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p} |
| Returns the name of the file specified by \var{p} as a string object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} |
| Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()} |
| only. This should only be called immediately after file object |
| creation. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag} |
| This function exists for internal use by the interpreter. |
| Sets the \member{softspace} attribute of \var{p} to \var{newflag} and |
| \withsubitem{(file attribute)}{\ttindex{softspace}}returns the |
| previous value. \var{p} does not have to be a file object |
| for this function to work properly; any object is supported (thought |
| its only interesting if the \member{softspace} attribute can be set). |
| This function clears any errors, and will return \code{0} as the |
| previous value if the attribute either does not exist or if there were |
| errors in retrieving it. There is no way to detect errors from this |
| function, but doing so should not be needed. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p, |
| int flags} |
| Writes object \var{obj} to file object \var{p}. The only supported |
| flag for \var{flags} is \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; |
| if given, the \function{str()} of the object is written instead of the |
| \function{repr()}. Returns \code{0} on success or \code{-1} on |
| failure; the appropriate exception will be set. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p, |
| int flags} |
| Writes string \var{s} to file object \var{p}. Returns \code{0} on |
| success or \code{-1} on failure; the appropriate exception will be |
| set. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Instance Objects \label{instanceObjects}} |
| |
| \obindex{instance} |
| There are very few functions specific to instance objects. |
| |
| \begin{cvardesc}{PyTypeObject}{PyInstance_Type} |
| Type object for class instances. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} |
| Returns true if \var{obj} is an instance. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, |
| PyObject *arg, |
| PyObject *kw} |
| Create a new instance of a specific class. The parameters \var{arg} |
| and \var{kw} are used as the positional and keyword parameters to |
| the object's constructor. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, |
| PyObject *dict} |
| Create a new instance of a specific class without calling it's |
| constructor. \var{class} is the class of new object. The |
| \var{dict} parameter will be used as the object's \member{__dict__}; |
| if \NULL, a new dictionary will be created for the instance. |
| \end{cfuncdesc} |
| |
| |
| \subsection{Module Objects \label{moduleObjects}} |
| |
| \obindex{module} |
| There are only a few functions special to module objects. |
| |
| \begin{cvardesc}{PyTypeObject}{PyModule_Type} |
| This instance of \ctype{PyTypeObject} represents the Python module |
| type. This is exposed to Python programs as \code{types.ModuleType}. |
| \withsubitem{(in module types)}{\ttindex{ModuleType}} |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p} |
| Returns true if its argument is a module object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name} |
| Return a new module object with the \member{__name__} attribute set to |
| \var{name}. Only the module's \member{__doc__} and |
| \member{__name__} attributes are filled in; the caller is responsible |
| for providing a \member{__file__} attribute. |
| \withsubitem{(module attribute)}{ |
| \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module} |
| Return the dictionary object that implements \var{module}'s namespace; |
| this object is the same as the \member{__dict__} attribute of the |
| module object. This function never fails. |
| \withsubitem{(module attribute)}{\ttindex{__dict__}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module} |
| Return \var{module}'s \member{__name__} value. If the module does not |
| provide one, or if it is not a string, \exception{SystemError} is |
| raised and \NULL{} is returned. |
| \withsubitem{(module attribute)}{\ttindex{__name__}} |
| \withsubitem{(built-in exception)}{\ttindex{SystemError}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module} |
| Return the name of the file from which \var{module} was loaded using |
| \var{module}'s \member{__file__} attribute. If this is not defined, |
| or if it is not a string, raise \exception{SystemError} and return |
| \NULL. |
| \withsubitem{(module attribute)}{\ttindex{__file__}} |
| \withsubitem{(built-in exception)}{\ttindex{SystemError}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module, |
| char *name, PyObject *value} |
| Add an object to \var{module} as \var{name}. This is a convenience |
| function which can be used from the module's initialization function. |
| This steals a reference to \var{value}. Returns \code{-1} on error, |
| \code{0} on success. |
| \versionadded{2.0} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module, |
| char *name, int value} |
| Add an integer constant to \var{module} as \var{name}. This convenience |
| function can be used from the module's initialization function. |
| Returns \code{-1} on error, \code{0} on success. |
| \versionadded{2.0} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module, |
| char *name, char *value} |
| Add a string constant to \var{module} as \var{name}. This convenience |
| function can be used from the module's initialization function. The |
| string \var{value} must be null-terminated. Returns \code{-1} on |
| error, \code{0} on success. |
| \versionadded{2.0} |
| \end{cfuncdesc} |
| |
| |
| \subsection{CObjects \label{cObjects}} |
| |
| \obindex{CObject} |
| Refer to \emph{Extending and Embedding the Python Interpreter}, |
| section 1.12 (``Providing a C API for an Extension Module''), for more |
| information on using these objects. |
| |
| |
| \begin{ctypedesc}{PyCObject} |
| This subtype of \ctype{PyObject} represents an opaque value, useful for |
| C extension modules who need to pass an opaque value (as a |
| \ctype{void*} pointer) through Python code to other C code. It is |
| often used to make a C function pointer defined in one module |
| available to other modules, so the regular import mechanism can be |
| used to access C APIs defined in dynamically loaded modules. |
| \end{ctypedesc} |
| |
| \begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p} |
| Returns true if its argument is a \ctype{PyCObject}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, |
| void (*destr)(void *)} |
| Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The |
| \var{destr} function will be called when the object is reclaimed, unless |
| it is \NULL. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, |
| void* desc, void (*destr)(void *, void *) } |
| Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The |
| \var{destr} function will be called when the object is reclaimed. The |
| \var{desc} argument can be used to pass extra callback data for the |
| destructor function. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self} |
| Returns the object \ctype{void *} that the |
| \ctype{PyCObject} \var{self} was created with. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self} |
| Returns the description \ctype{void *} that the |
| \ctype{PyCObject} \var{self} was created with. |
| \end{cfuncdesc} |
| |
| |
| \chapter{Initialization, Finalization, and Threads |
| \label{initialization}} |
| |
| \begin{cfuncdesc}{void}{Py_Initialize}{} |
| Initialize the Python interpreter. In an application embedding |
| Python, this should be called before using any other Python/C API |
| functions; with the exception of |
| \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, |
| \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()}, |
| \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()}, |
| and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}. |
| This initializes the table of loaded modules (\code{sys.modules}), and |
| \withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}creates the |
| fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, |
| \module{__main__}\refbimodindex{__main__} and |
| \module{sys}\refbimodindex{sys}. It also initializes the module |
| search\indexiii{module}{search}{path} path (\code{sys.path}). |
| It does not set \code{sys.argv}; use |
| \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This |
| is a no-op when called for a second time (without calling |
| \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is no |
| return value; it is a fatal error if the initialization fails. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{Py_IsInitialized}{} |
| Return true (nonzero) when the Python interpreter has been |
| initialized, false (zero) if not. After \cfunction{Py_Finalize()} is |
| called, this returns false until \cfunction{Py_Initialize()} is called |
| again. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_Finalize}{} |
| Undo all initializations made by \cfunction{Py_Initialize()} and |
| subsequent use of Python/C API functions, and destroy all |
| sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were |
| created and not yet destroyed since the last call to |
| \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated |
| by the Python interpreter. This is a no-op when called for a second |
| time (without calling \cfunction{Py_Initialize()} again first). There |
| is no return value; errors during finalization are ignored. |
| |
| This function is provided for a number of reasons. An embedding |
| application might want to restart Python without having to restart the |
| application itself. An application that has loaded the Python |
| interpreter from a dynamically loadable library (or DLL) might want to |
| free all memory allocated by Python before unloading the DLL. During a |
| hunt for memory leaks in an application a developer might want to free |
| all memory allocated by Python before exiting from the application. |
| |
| \strong{Bugs and caveats:} The destruction of modules and objects in |
| modules is done in random order; this may cause destructors |
| (\method{__del__()} methods) to fail when they depend on other objects |
| (even functions) or modules. Dynamically loaded extension modules |
| loaded by Python are not unloaded. Small amounts of memory allocated |
| by the Python interpreter may not be freed (if you find a leak, please |
| report it). Memory tied up in circular references between objects is |
| not freed. Some memory allocated by extension modules may not be |
| freed. Some extension may not work properly if their initialization |
| routine is called more than once; this can happen if an applcation |
| calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more |
| than once. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{} |
| Create a new sub-interpreter. This is an (almost) totally separate |
| environment for the execution of Python code. In particular, the new |
| interpreter has separate, independent versions of all imported |
| modules, including the fundamental modules |
| \module{__builtin__}\refbimodindex{__builtin__}, |
| \module{__main__}\refbimodindex{__main__} and |
| \module{sys}\refbimodindex{sys}. The table of loaded modules |
| (\code{sys.modules}) and the module search path (\code{sys.path}) are |
| also separate. The new environment has no \code{sys.argv} variable. |
| It has new standard I/O stream file objects \code{sys.stdin}, |
| \code{sys.stdout} and \code{sys.stderr} (however these refer to the |
| same underlying \ctype{FILE} structures in the C library). |
| \withsubitem{(in module sys)}{ |
| \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}} |
| |
| The return value points to the first thread state created in the new |
| sub-interpreter. This thread state is made the current thread state. |
| Note that no actual thread is created; see the discussion of thread |
| states below. If creation of the new interpreter is unsuccessful, |
| \NULL{} is returned; no exception is set since the exception state |
| is stored in the current thread state and there may not be a current |
| thread state. (Like all other Python/C API functions, the global |
| interpreter lock must be held before calling this function and is |
| still held when it returns; however, unlike most other Python/C API |
| functions, there needn't be a current thread state on entry.) |
| |
| Extension modules are shared between (sub-)interpreters as follows: |
| the first time a particular extension is imported, it is initialized |
| normally, and a (shallow) copy of its module's dictionary is |
| squirreled away. When the same extension is imported by another |
| (sub-)interpreter, a new module is initialized and filled with the |
| contents of this copy; the extension's \code{init} function is not |
| called. Note that this is different from what happens when an |
| extension is imported after the interpreter has been completely |
| re-initialized by calling |
| \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and |
| \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case, |
| the extension's \code{init\var{module}} function \emph{is} called |
| again. |
| |
| \strong{Bugs and caveats:} Because sub-interpreters (and the main |
| interpreter) are part of the same process, the insulation between them |
| isn't perfect --- for example, using low-level file operations like |
| \withsubitem{(in module os)}{\ttindex{close()}} |
| \function{os.close()} they can (accidentally or maliciously) affect each |
| other's open files. Because of the way extensions are shared between |
| (sub-)interpreters, some extensions may not work properly; this is |
| especially likely when the extension makes use of (static) global |
| variables, or when the extension manipulates its module's dictionary |
| after its initialization. It is possible to insert objects created in |
| one sub-interpreter into a namespace of another sub-interpreter; this |
| should be done with great care to avoid sharing user-defined |
| functions, methods, instances or classes between sub-interpreters, |
| since import operations executed by such objects may affect the |
| wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is |
| a hard-to-fix bug that will be addressed in a future release.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate} |
| Destroy the (sub-)interpreter represented by the given thread state. |
| The given thread state must be the current thread state. See the |
| discussion of thread states below. When the call returns, the current |
| thread state is \NULL{}. All thread states associated with this |
| interpreted are destroyed. (The global interpreter lock must be held |
| before calling this function and is still held when it returns.) |
| \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will destroy all |
| sub-interpreters that haven't been explicitly destroyed at that point. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} |
| This function should be called before |
| \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called |
| for the first time, if it is called at all. It tells the interpreter |
| the value of the \code{argv[0]} argument to the |
| \cfunction{main()}\ttindex{main()} function of the program. This is |
| used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other |
| functions below to find the Python run-time libraries relative to the |
| interpreter executable. The default value is \code{'python'}. The |
| argument should point to a zero-terminated character string in static |
| storage whose contents will not change for the duration of the |
| program's execution. No code in the Python interpreter will change |
| the contents of this storage. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{Py_GetProgramName}{} |
| Return the program name set with |
| \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the |
| default. The returned string points into static storage; the caller |
| should not modify its value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{Py_GetPrefix}{} |
| Return the \emph{prefix} for installed platform-independent files. This |
| is derived through a number of complicated rules from the program name |
| set with \cfunction{Py_SetProgramName()} and some environment variables; |
| for example, if the program name is \code{'/usr/local/bin/python'}, |
| the prefix is \code{'/usr/local'}. The returned string points into |
| static storage; the caller should not modify its value. This |
| corresponds to the \makevar{prefix} variable in the top-level |
| \file{Makefile} and the \longprogramopt{prefix} argument to the |
| \program{configure} script at build time. The value is available to |
| Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See |
| also the next function. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{} |
| Return the \emph{exec-prefix} for installed platform-\emph{de}pendent |
| files. This is derived through a number of complicated rules from the |
| program name set with \cfunction{Py_SetProgramName()} and some environment |
| variables; for example, if the program name is |
| \code{'/usr/local/bin/python'}, the exec-prefix is |
| \code{'/usr/local'}. The returned string points into static storage; |
| the caller should not modify its value. This corresponds to the |
| \makevar{exec_prefix} variable in the top-level \file{Makefile} and the |
| \longprogramopt{exec-prefix} argument to the |
| \program{configure} script at build time. The value is available to |
| Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}. |
| |
| Background: The exec-prefix differs from the prefix when platform |
| dependent files (such as executables and shared libraries) are |
| installed in a different directory tree. In a typical installation, |
| platform dependent files may be installed in the |
| \file{/usr/local/plat} subtree while platform independent may be |
| installed in \file{/usr/local}. |
| |
| Generally speaking, a platform is a combination of hardware and |
| software families, e.g. Sparc machines running the Solaris 2.x |
| operating system are considered the same platform, but Intel machines |
| running Solaris 2.x are another platform, and Intel machines running |
| Linux are yet another platform. Different major revisions of the same |
| operating system generally also form different platforms. Non-\UNIX{} |
| operating systems are a different story; the installation strategies |
| on those systems are so different that the prefix and exec-prefix are |
| meaningless, and set to the empty string. Note that compiled Python |
| bytecode files are platform independent (but not independent from the |
| Python version by which they were compiled!). |
| |
| System administrators will know how to configure the \program{mount} or |
| \program{automount} programs to share \file{/usr/local} between platforms |
| while having \file{/usr/local/plat} be a different filesystem for each |
| platform. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{} |
| Return the full program name of the Python executable; this is |
| computed as a side-effect of deriving the default module search path |
| from the program name (set by |
| \cfunction{Py_SetProgramName()}\ttindex{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}. |
| \withsubitem{(in module sys)}{\ttindex{executable}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{char*}{Py_GetPath}{} |
| \indexiii{module}{search}{path} |
| Return the default module search path; this is computed from the |
| program name (set by \cfunction{Py_SetProgramName()} above) and some |
| environment variables. The returned string consists of a series of |
| directory names separated by a platform dependent delimiter character. |
| The delimiter character is \character{:} on \UNIX{}, \character{;} on |
| DOS/Windows, and \character{\e 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}\withsubitem{(in module sys)}{\ttindex{path}}, |
| which may be modified to change the future search path for loaded |
| modules. |
| |
| % XXX should give the exact rules |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{const char*}{Py_GetVersion}{} |
| Return the version of this Python interpreter. This is a string that |
| looks something like |
| |
| \begin{verbatim} |
| "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" |
| \end{verbatim} |
| |
| The first word (up to the first space character) is the current Python |
| version; the first three characters are the major and minor version |
| separated by a period. The returned string points into static storage; |
| the caller should not modify its value. The value is available to |
| Python code as the list \code{sys.version}. |
| \withsubitem{(in module sys)}{\ttindex{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}. |
| \withsubitem{(in module sys)}{\ttindex{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}. |
| \withsubitem{(in module sys)}{\ttindex{copyright}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{const char*}{Py_GetCompiler}{} |
| Return an indication of the compiler used to build the current Python |
| version, in square brackets, for example: |
| |
| \begin{verbatim} |
| "[GCC 2.7.2.2]" |
| \end{verbatim} |
| |
| The returned string points into static storage; the caller should not |
| modify its value. The value is available to Python code as part of |
| the variable \code{sys.version}. |
| \withsubitem{(in module sys)}{\ttindex{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}. |
| \withsubitem{(in module sys)}{\ttindex{version}} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv} |
| Set \code{sys.argv} based on \var{argc} and \var{argv}. These |
| parameters are similar to those passed to the program's |
| \cfunction{main()}\ttindex{main()} function with the difference that |
| the first entry should refer to the script file to be executed rather |
| than the executable hosting the Python interpreter. If there isn't a |
| script that will be run, the first entry in \var{argv} can be an empty |
| string. If this function fails to initialize \code{sys.argv}, a fatal |
| condition is signalled using |
| \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}. |
| \withsubitem{(in module sys)}{\ttindex{argv}} |
| % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; |
| % check w/ Guido. |
| \end{cfuncdesc} |
| |
| % XXX Other PySys thingies (doesn't really belong in this chapter) |
| |
| \section{Thread State and the Global Interpreter Lock |
| \label{threads}} |
| |
| \index{global interpreter lock} |
| \index{interpreter lock} |
| \index{lock, interpreter} |
| |
| The Python interpreter is not fully thread safe. In order to support |
| multi-threaded Python programs, there's a global lock that must be |
| held by the current thread before it can safely access Python objects. |
| Without the lock, even the simplest operations could cause problems in |
| a multi-threaded program: for example, when two threads simultaneously |
| increment the reference count of the same object, the reference count |
| could end up being incremented only once instead of twice. |
| |
| Therefore, the rule exists that only the thread that has acquired the |
| global interpreter lock may operate on Python objects or call Python/C |
| API functions. In order to support multi-threaded Python programs, |
| the interpreter regularly releases and reacquires the lock --- by |
| default, every ten bytecode instructions (this can be changed with |
| \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}} |
| \function{sys.setcheckinterval()}). The lock is also released and |
| reacquired around potentially blocking I/O operations like reading or |
| writing a file, so that other threads can run while the thread that |
| requests the I/O is waiting for the I/O operation to complete. |
| |
| The Python interpreter needs to keep some bookkeeping information |
| separate per thread --- for this it uses a data structure called |
| \ctype{PyThreadState}\ttindex{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 |
| \withsubitem{(in module sys)}{\ttindex{exc_info()}} |
| \function{sys.exc_info()} to access the exception last raised in the |
| current thread. |
| |
| There's one global variable left, however: the pointer to the current |
| \ctype{PyThreadState}\ttindex{PyThreadState} structure. While most |
| thread packages have a way to store ``per-thread global data,'' |
| Python's internal platform independent thread abstraction doesn't |
| support this yet. Therefore, the current thread state must be |
| manipulated explicitly. |
| |
| This is easy enough in most cases. Most code manipulating the global |
| interpreter lock has the following simple structure: |
| |
| \begin{verbatim} |
| Save the thread state in a local variable. |
| Release the interpreter lock. |
| ...Do some blocking I/O operation... |
| Reacquire the interpreter lock. |
| Restore the thread state from the local variable. |
| \end{verbatim} |
| |
| This is so common that a pair of macros exists to simplify it: |
| |
| \begin{verbatim} |
| Py_BEGIN_ALLOW_THREADS |
| ...Do some blocking I/O operation... |
| Py_END_ALLOW_THREADS |
| \end{verbatim} |
| |
| The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro |
| opens a new block and declares a hidden local variable; the |
| \code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes |
| the block. Another advantage of using these two macros is that when |
| Python is compiled without thread support, they are defined empty, |
| thus saving the thread state and lock manipulations. |
| |
| When thread support is enabled, the block above expands to the |
| following code: |
| |
| \begin{verbatim} |
| PyThreadState *_save; |
| |
| _save = PyEval_SaveThread(); |
| ...Do some blocking I/O operation... |
| PyEval_RestoreThread(_save); |
| \end{verbatim} |
| |
| Using even lower level primitives, we can get roughly the same effect |
| as follows: |
| |
| \begin{verbatim} |
| PyThreadState *_save; |
| |
| _save = PyThreadState_Swap(NULL); |
| PyEval_ReleaseLock(); |
| ...Do some blocking I/O operation... |
| PyEval_AcquireLock(); |
| PyThreadState_Swap(_save); |
| \end{verbatim} |
| |
| There are some subtle differences; in particular, |
| \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves |
| and restores the value of the global variable |
| \cdata{errno}\ttindex{errno}, since the lock manipulation does not |
| guarantee that \cdata{errno} is left alone. Also, when thread support |
| is disabled, |
| \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and |
| \cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this |
| case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and |
| \cfunction{PyEval_AcquireLock()}\ttindex{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). |
| Conversely, 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 \member{interp} member; |
| this must be done by a thread that is created by Python or by the main |
| thread after Python is initialized). |
| |
| |
| \begin{ctypedesc}{PyInterpreterState} |
| This data structure represents the state shared by a number of |
| cooperating threads. Threads belonging to the same interpreter |
| share their module administration and a few other internal items. |
| There are no public members in this structure. |
| |
| Threads belonging to different interpreters initially share nothing, |
| except process state like available memory, open file descriptors and |
| such. The global interpreter lock is also shared by all threads, |
| regardless of to which interpreter they belong. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}{PyThreadState} |
| This data structure represents the state of a single thread. The only |
| public data member is \ctype{PyInterpreterState *}\member{interp}, |
| which points to this thread's interpreter state. |
| \end{ctypedesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_InitThreads}{} |
| Initialize and acquire the global interpreter lock. It should be |
| called in the main thread before creating a second thread or engaging |
| in any other thread operations such as |
| \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or |
| \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}. |
| It is not needed before calling |
| \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or |
| \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}. |
| |
| This is a no-op when called for a second time. It is safe to call |
| this function before calling |
| \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. |
| |
| When only the main thread exists, no lock operations are needed. This |
| is a common situation (most Python programs do not use threads), and |
| the lock operations slow the interpreter down a bit. Therefore, the |
| lock is not created initially. This situation is equivalent to having |
| acquired the lock: when there is only a single thread, all object |
| accesses are safe. Therefore, when this function initializes the |
| lock, it also acquires it. Before the Python |
| \module{thread}\refbimodindex{thread} module creates a new thread, |
| knowing that either it has the lock or the lock hasn't been created |
| yet, it calls \cfunction{PyEval_InitThreads()}. When this call |
| returns, it is guaranteed that the lock has been created and that it |
| has acquired it. |
| |
| It is \strong{not} safe to call this function when it is unknown which |
| thread (if any) currently has the global interpreter lock. |
| |
| This function is not available when thread support is disabled at |
| compile time. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_AcquireLock}{} |
| Acquire the global interpreter lock. The lock must have been created |
| earlier. If this thread already has the lock, a deadlock ensues. |
| This function is not available when thread support is disabled at |
| compile time. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} |
| Release the global interpreter lock. The lock must have been created |
| earlier. This function is not available when thread support is |
| disabled at compile time. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} |
| Acquire the global interpreter lock and then set the current thread |
| state to \var{tstate}, which should not be \NULL{}. The lock must |
| have been created earlier. If this thread already has the lock, |
| deadlock ensues. This function is not available when thread support |
| is disabled at compile time. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} |
| Reset the current thread state to \NULL{} and release the global |
| interpreter lock. The lock must have been created earlier and must be |
| held by the current thread. The \var{tstate} argument, which must not |
| be \NULL{}, is only used to check that it represents the current |
| thread state --- if it isn't, a fatal error is reported. This |
| function is not available when thread support is disabled at compile |
| time. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{} |
| Release the interpreter lock (if it has been created and thread |
| support is enabled) and reset the thread state to \NULL{}, |
| returning the previous thread state (which is not \NULL{}). If |
| the lock has been created, the current thread must have acquired it. |
| (This function is available even when thread support is disabled at |
| compile time.) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} |
| Acquire the interpreter lock (if it has been created and thread |
| support is enabled) and set the thread state to \var{tstate}, which |
| must not be \NULL{}. If the lock has been created, the current |
| thread must not have acquired it, otherwise deadlock ensues. (This |
| function is available even when thread support is disabled at compile |
| time.) |
| \end{cfuncdesc} |
| |
| The following macros are normally used without a trailing semicolon; |
| look for example usage in the Python source distribution. |
| |
| \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS} |
| This macro expands to |
| \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}. |
| Note that it contains an opening brace; it must be matched with a |
| following \code{Py_END_ALLOW_THREADS} macro. See above for further |
| discussion of this macro. It is a no-op when thread support is |
| disabled at compile time. |
| \end{csimplemacrodesc} |
| |
| \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS} |
| This macro expands to |
| \samp{PyEval_RestoreThread(_save); \}}. |
| Note that it contains a closing brace; it must be matched with an |
| earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further |
| discussion of this macro. It is a no-op when thread support is |
| disabled at compile time. |
| \end{csimplemacrodesc} |
| |
| \begin{csimplemacrodesc}{Py_BLOCK_THREADS} |
| This macro expands to \samp{PyEval_RestoreThread(_save);}: 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{csimplemacrodesc} |
| |
| \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS} |
| This macro expands to \samp{_save = PyEval_SaveThread();}: 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{csimplemacrodesc} |
| |
| All of the following functions are only available when thread support |
| is enabled at compile time, and must be called only when the |
| interpreter lock has been created. |
| |
| \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{} |
| Create a new interpreter state object. The interpreter lock need not |
| be held, but may be held if it is necessary to serialize calls to this |
| function. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp} |
| Reset all information in an interpreter state object. The interpreter |
| lock must be held. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp} |
| Destroy an interpreter state object. The interpreter lock need not be |
| held. The interpreter state must have been reset with a previous |
| call to \cfunction{PyInterpreterState_Clear()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp} |
| Create a new thread state object belonging to the given interpreter |
| object. The interpreter lock need not be held, but may be held if it |
| is necessary to serialize calls to this function. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate} |
| Reset all information in a thread state object. The interpreter lock |
| must be held. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate} |
| Destroy a thread state object. The interpreter lock need not be |
| held. The thread state must have been reset with a previous |
| call to \cfunction{PyThreadState_Clear()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{} |
| Return the current thread state. The interpreter lock must be held. |
| When the current thread state is \NULL{}, this issues a fatal |
| error (so that the caller needn't check for \NULL{}). |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate} |
| Swap the current thread state with the thread state given by the |
| argument \var{tstate}, which may be \NULL{}. The interpreter lock |
| must be held. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{} |
| Return a dictionary in which extensions can store thread-specific |
| state information. Each extension should use a unique key to use to |
| store state in the dictionary. If this function returns \NULL, an |
| exception has been raised and the caller should allow it to |
| propogate. |
| \end{cfuncdesc} |
| |
| |
| \section{Profiling and Tracing \label{profiling}} |
| |
| \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| |
| The Python interpreter provides some low-level support for attaching |
| profiling and execution tracing facilities. These are used for |
| profiling, debugging, and coverage analysis tools. |
| |
| Starting with Python 2.2, the implementation of this facility was |
| substantially revised, and an interface from C was added. This C |
| interface allows the profiling or tracing code to avoid the overhead |
| of calling through Python-level callable objects, making a direct C |
| function call instead. The essential attributes of the facility have |
| not changed; the interface allows trace functions to be installed |
| per-thread, and the basic events reported to the trace function are |
| the same as had been reported to the Python-level trace functions in |
| previous versions. |
| |
| \begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj, |
| PyFrameObject *frame, int what, |
| PyObject *arg)} |
| The type of the trace function registered using |
| \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}. |
| The first parameter is the object passed to the registration |
| function, |
| \end{ctypedesc} |
| |
| \begin{cvardesc}{int}{PyTrace_CALL} |
| The value of the \var{what} parameter to a \ctype{Py_tracefunc} |
| function when a new function or method call is being reported. |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{PyTrace_EXCEPT} |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{PyTrace_LINE} |
| The value passed as the \var{what} parameter to a trace function |
| (but not a profiling function) when a line-number event is being |
| reported. |
| \end{cvardesc} |
| |
| \begin{cvardesc}{int}{PyTrace_RETURN} |
| The value for the \var{what} parameter to \ctype{Py_tracefunc} |
| functions when a call is returning without propogating an exception. |
| \end{cvardesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj} |
| Set the profiler function to \var{func}. The \var{obj} parameter is |
| passed to the function as its first parameter, and may be any Python |
| object, or \NULL. If the profile function needs to maintain state, |
| using a different value for \var{obj} for each thread provides a |
| convenient and thread-safe place to store it. The profile function |
| is called for all monitored events except the line-number events. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj} |
| Set the the tracing function to \var{func}. This is similar to |
| \cfunction{PyEval_SetProfile()}, except the tracing function does |
| receive line-number events. |
| \end{cfuncdesc} |
| |
| |
| \section{Advanced Debugger Support \label{advanced-debugging}} |
| \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| |
| These functions are only intended to be used by advanced debugging |
| tools. |
| |
| \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{} |
| Return the interpreter state object at the head of the list of all |
| such objects. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp} |
| Return the next interpreter state object after \var{interp} from the |
| list of all such objects. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp} |
| Return the a pointer to the first \ctype{PyThreadState} object in the |
| list of threads associated with the interpreter \var{interp}. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate} |
| Return the next thread state object after \var{tstate} from the list |
| of all such objects belonging to the same \ctype{PyInterpreterState} |
| object. |
| \versionadded{2.2} |
| \end{cfuncdesc} |
| |
| |
| \chapter{Memory Management \label{memory}} |
| \sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr} |
| |
| |
| \section{Overview \label{memoryOverview}} |
| |
| Memory management in Python involves a private heap containing all |
| Python objects and data structures. The management of this private |
| heap is ensured internally by the \emph{Python memory manager}. The |
| Python memory manager has different components which deal with various |
| dynamic storage management aspects, like sharing, segmentation, |
| preallocation or caching. |
| |
| At the lowest level, a raw memory allocator ensures that there is |
| enough room in the private heap for storing all Python-related data |
| by interacting with the memory manager of the operating system. On top |
| of the raw memory allocator, several object-specific allocators |
| operate on the same heap and implement distinct memory management |
| policies adapted to the peculiarities of every object type. For |
| example, integer objects are managed differently within the heap than |
| strings, tuples or dictionaries because integers imply different |
| storage requirements and speed/space tradeoffs. The Python memory |
| manager thus delegates some of the work to the object-specific |
| allocators, but ensures that the latter operate within the bounds of |
| the private heap. |
| |
| It is important to understand that the management of the Python heap |
| is performed by the interpreter itself and that the user has no |
| control on it, even if she regularly manipulates object pointers to |
| memory blocks inside that heap. The allocation of heap space for |
| Python objects and other internal buffers is performed on demand by |
| the Python memory manager through the Python/C API functions listed in |
| this document. |
| |
| To avoid memory corruption, extension writers should never try to |
| operate on Python objects with the functions exported by the C |
| library: \cfunction{malloc()}\ttindex{malloc()}, |
| \cfunction{calloc()}\ttindex{calloc()}, |
| \cfunction{realloc()}\ttindex{realloc()} and |
| \cfunction{free()}\ttindex{free()}. This will result in |
| mixed calls between the C allocator and the Python memory manager |
| with fatal consequences, because they implement different algorithms |
| and operate on different heaps. However, one may safely allocate and |
| release memory blocks with the C library allocator for individual |
| purposes, as shown in the following example: |
| |
| \begin{verbatim} |
| PyObject *res; |
| char *buf = (char *) malloc(BUFSIZ); /* for I/O */ |
| |
| if (buf == NULL) |
| return PyErr_NoMemory(); |
| ...Do some I/O operation involving buf... |
| res = PyString_FromString(buf); |
| free(buf); /* malloc'ed */ |
| return res; |
| \end{verbatim} |
| |
| In this example, the memory request for the I/O buffer is handled by |
| the C library allocator. The Python memory manager is involved only |
| in the allocation of the string object returned as a result. |
| |
| In most situations, however, it is recommended to allocate memory from |
| the Python heap specifically because the latter is under control of |
| the Python memory manager. For example, this is required when the |
| interpreter is extended with new object types written in C. Another |
| reason for using the Python heap is the desire to \emph{inform} the |
| Python memory manager about the memory needs of the extension module. |
| Even when the requested memory is used exclusively for internal, |
| highly-specific purposes, delegating all memory requests to the Python |
| memory manager causes the interpreter to have a more accurate image of |
| its memory footprint as a whole. Consequently, under certain |
| circumstances, the Python memory manager may or may not trigger |
| appropriate actions, like garbage collection, memory compaction or |
| other preventive procedures. Note that by using the C library |
| allocator as shown in the previous example, the allocated memory for |
| the I/O buffer escapes completely the Python memory manager. |
| |
| |
| \section{Memory Interface \label{memoryInterface}} |
| |
| The following function sets, modeled after the ANSI C standard, are |
| available for allocating and releasing memory from the Python heap: |
| |
| |
| \begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n} |
| Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to |
| the allocated memory, or \NULL{} if the request fails. Requesting zero |
| bytes returns a non-\NULL{} pointer. |
| The memory will not have been initialized in any way. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n} |
| Resizes the memory block pointed to by \var{p} to \var{n} bytes. The |
| contents will be unchanged to the minimum of the old and the new |
| sizes. If \var{p} is \NULL{}, the call is equivalent to |
| \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the |
| memory block is resized but is not freed, and the returned pointer is |
| non-\NULL{}. Unless \var{p} is \NULL{}, it must have been returned by |
| a previous call to \cfunction{PyMem_Malloc()} or |
| \cfunction{PyMem_Realloc()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyMem_Free}{void *p} |
| Frees the memory block pointed to by \var{p}, which must have been |
| returned by a previous call to \cfunction{PyMem_Malloc()} or |
| \cfunction{PyMem_Realloc()}. Otherwise, or if |
| \cfunction{PyMem_Free(p)} has been called before, undefined behaviour |
| occurs. If \var{p} is \NULL{}, no operation is performed. |
| \end{cfuncdesc} |
| |
| The following type-oriented macros are provided for convenience. Note |
| that \var{TYPE} refers to any C type. |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n} |
| Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} * |
| sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to |
| \ctype{\var{TYPE}*}. |
| The memory will not have been initialized in any way. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} |
| Same as \cfunction{PyMem_Realloc()}, but the memory block is resized |
| to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer |
| cast to \ctype{\var{TYPE}*}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyMem_Del}{void *p} |
| Same as \cfunction{PyMem_Free()}. |
| \end{cfuncdesc} |
| |
| In addition, the following macro sets are provided for calling the |
| Python memory allocator directly, without involving the C API functions |
| listed above. However, note that their use does not preserve binary |
| compatibility accross Python versions and is therefore deprecated in |
| extension modules. |
| |
| \cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}. |
| |
| \cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}. |
| |
| |
| \section{Examples \label{memoryExamples}} |
| |
| Here is the example from section \ref{memoryOverview}, rewritten so |
| that the I/O buffer is allocated from the Python heap by using the |
| first function set: |
| |
| \begin{verbatim} |
| PyObject *res; |
| char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ |
| |
| if (buf == NULL) |
| return PyErr_NoMemory(); |
| /* ...Do some I/O operation involving buf... */ |
| res = PyString_FromString(buf); |
| PyMem_Free(buf); /* allocated with PyMem_Malloc */ |
| return res; |
| \end{verbatim} |
| |
| The same code using the type-oriented function set: |
| |
| \begin{verbatim} |
| PyObject *res; |
| char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ |
| |
| if (buf == NULL) |
| return PyErr_NoMemory(); |
| /* ...Do some I/O operation involving buf... */ |
| res = PyString_FromString(buf); |
| PyMem_Del(buf); /* allocated with PyMem_New */ |
| return res; |
| \end{verbatim} |
| |
| Note that in the two examples above, the buffer is always |
| manipulated via functions belonging to the same set. Indeed, it |
| is required to use the same memory API family for a given |
| memory block, so that the risk of mixing different allocators is |
| reduced to a minimum. The following code sequence contains two errors, |
| one of which is labeled as \emph{fatal} because it mixes two different |
| allocators operating on different heaps. |
| |
| \begin{verbatim} |
| char *buf1 = PyMem_New(char, BUFSIZ); |
| char *buf2 = (char *) malloc(BUFSIZ); |
| char *buf3 = (char *) PyMem_Malloc(BUFSIZ); |
| ... |
| PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ |
| free(buf2); /* Right -- allocated via malloc() */ |
| free(buf1); /* Fatal -- should be PyMem_Del() */ |
| \end{verbatim} |
| |
| In addition to the functions aimed at handling raw memory blocks from |
| the Python heap, objects in Python are allocated and released with |
| \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and |
| \cfunction{PyObject_Del()}, or with their corresponding macros |
| \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and |
| \cfunction{PyObject_DEL()}. |
| |
| These will be explained in the next chapter on defining and |
| implementing new object types in C. |
| |
| |
| \chapter{Defining New Object Types \label{newTypes}} |
| |
| |
| \section{Allocating Objects on the Heap |
| \label{allocating-objects}} |
| |
| \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op, |
| PyTypeObject *type} |
| Initialize a newly-allocated object \var{op} with its type and |
| initial reference. Returns the initialized object. If \var{type} |
| indicates that the object participates in the cyclic garbage |
| detector, it it added to the detector's set of observed objects. |
| Other fields of the object are not affected. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op, |
| PyTypeObject *type, int size} |
| This does everything \cfunction{PyObject_Init()} does, and also |
| initializes the length information for a variable-size object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type} |
| Allocate a new Python object using the C structure type \var{TYPE} |
| and the Python type object \var{type}. Fields not defined by the |
| Python object header are not initialized; the object's reference |
| count will be one. The size of the memory |
| allocation is determined from the \member{tp_basicsize} field of the |
| type object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type, |
| int size} |
| Allocate a new Python object using the C structure type \var{TYPE} |
| and the Python type object \var{type}. Fields not defined by the |
| Python object header are not initialized. The allocated memory |
| allows for the \var{TYPE} structure plus \var{size} fields of the |
| size given by the \member{tp_itemsize} field of \var{type}. This is |
| useful for implementing objects like tuples, which are able to |
| determine their size at construction time. Embedding the array of |
| fields into the same allocation decreases the number of allocations, |
| improving the memory management efficiency. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op} |
| Releases memory allocated to an object using |
| \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This |
| is normally called from the \member{tp_dealloc} handler specified in |
| the object's type. The fields of the object should not be accessed |
| after this call as the memory is no longer a valid Python object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type} |
| Macro version of \cfunction{PyObject_New()}, to gain performance at |
| the expense of safety. This does not check \var{type} for a \NULL{} |
| value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type, |
| int size} |
| Macro version of \cfunction{PyObject_NewVar()}, to gain performance |
| at the expense of safety. This does not check \var{type} for a |
| \NULL{} value. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op} |
| Macro version of \cfunction{PyObject_Del()}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name, |
| PyMethodDef *methods} |
| Create a new module object based on a name and table of functions, |
| returning the new module object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name, |
| PyMethodDef *methods, |
| char *doc} |
| Create a new module object based on a name and table of functions, |
| returning the new module object. If \var{doc} is non-\NULL, it will |
| be used to define the docstring for the module. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name, |
| PyMethodDef *methods, |
| char *doc, PyObject *self, |
| int apiver} |
| Create a new module object based on a name and table of functions, |
| returning the new module object. If \var{doc} is non-\NULL, it will |
| be used to define the docstring for the module. If \var{self} is |
| non-\NULL, it will passed to the functions of the module as their |
| (otherwise \NULL) first parameter. (This was added as an |
| experimental feature, and there are no known uses in the current |
| version of Python.) For \var{apiver}, the only value which should |
| be passed is defined by the constant \constant{PYTHON_API_VERSION}. |
| |
| \strong{Note:} Most uses of this function should probably be using |
| the \cfunction{Py_InitModule3()} instead; only use this if you are |
| sure you need it. |
| \end{cfuncdesc} |
| |
| DL_IMPORT |
| |
| \begin{cvardesc}{PyObject}{_Py_NoneStruct} |
| Object which is visible in Python as \code{None}. This should only |
| be accessed using the \code{Py_None} macro, which evaluates to a |
| pointer to this object. |
| \end{cvardesc} |
| |
| |
| \section{Common Object Structures \label{common-structs}} |
| |
| PyObject, PyVarObject |
| |
| PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD |
| |
| Typedefs: |
| unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, |
| intintargfunc, intobjargproc, intintobjargproc, objobjargproc, |
| destructor, printfunc, getattrfunc, getattrofunc, setattrfunc, |
| setattrofunc, cmpfunc, reprfunc, hashfunc |
| |
| \begin{ctypedesc}{PyCFunction} |
| Type of the functions used to implement most Python callables in C. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}{PyMethodDef} |
| Structure used to describe a method of an extension type. This |
| structure has four fields: |
| |
| \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning} |
| \lineiii{ml_name}{char *}{name of the method} |
| \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation} |
| \lineiii{ml_flags}{int}{flag bits indicating how the call should be |
| constructed} |
| \lineiii{ml_doc}{char *}{points to the contents of the docstring} |
| \end{tableiii} |
| \end{ctypedesc} |
| |
| \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table, |
| PyObject *ob, char *name} |
| Return a bound method object for an extension type implemented in C. |
| This function also handles the special attribute \member{__methods__}, |
| returning a list of all the method names defined in \var{table}. |
| \end{cfuncdesc} |
| |
| |
| \section{Mapping Object Structures \label{mapping-structs}} |
| |
| \begin{ctypedesc}{PyMappingMethods} |
| Structure used to hold pointers to the functions used to implement the |
| mapping protocol for an extension type. |
| \end{ctypedesc} |
| |
| |
| \section{Number Object Structures \label{number-structs}} |
| |
| \begin{ctypedesc}{PyNumberMethods} |
| Structure used to hold pointers to the functions an extension type |
| uses to implement the number protocol. |
| \end{ctypedesc} |
| |
| |
| \section{Sequence Object Structures \label{sequence-structs}} |
| |
| \begin{ctypedesc}{PySequenceMethods} |
| Structure used to hold pointers to the functions which an object uses |
| to implement the sequence protocol. |
| \end{ctypedesc} |
| |
| |
| \section{Buffer Object Structures \label{buffer-structs}} |
| \sectionauthor{Greg J. Stein}{greg@lyra.org} |
| |
| The buffer interface exports a model where an object can expose its |
| internal data as a set of chunks of data, where each chunk is |
| specified as a pointer/length pair. These chunks are called |
| \dfn{segments} and are presumed to be non-contiguous in memory. |
| |
| If an object does not export the buffer interface, then its |
| \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure |
| should be \NULL{}. Otherwise, the \member{tp_as_buffer} will point to |
| a \ctype{PyBufferProcs} structure. |
| |
| \strong{Note:} It is very important that your |
| \ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for |
| the value of the \member{tp_flags} member rather than \code{0}. This |
| tells the Python runtime that your \ctype{PyBufferProcs} structure |
| contains the \member{bf_getcharbuffer} slot. Older versions of Python |
| did not have this member, so a new Python interpreter using an old |
| extension needs to be able to test for its presence before using it. |
| |
| \begin{ctypedesc}{PyBufferProcs} |
| Structure used to hold the function pointers which define an |
| implementation of the buffer protocol. |
| |
| The first slot is \member{bf_getreadbuffer}, of type |
| \ctype{getreadbufferproc}. If this slot is \NULL{}, then the object |
| does not support reading from the internal data. This is |
| non-sensical, so implementors should fill this in, but callers should |
| test that the slot contains a non-\NULL{} value. |
| |
| The next slot is \member{bf_getwritebuffer} having type |
| \ctype{getwritebufferproc}. This slot may be \NULL{} if the object |
| does not allow writing into its returned buffers. |
| |
| The third slot is \member{bf_getsegcount}, with type |
| \ctype{getsegcountproc}. This slot must not be \NULL{} and is used to |
| inform the caller how many segments the object contains. Simple |
| objects such as \ctype{PyString_Type} and |
| \ctype{PyBuffer_Type} objects contain a single segment. |
| |
| The last slot is \member{bf_getcharbuffer}, of type |
| \ctype{getcharbufferproc}. This slot will only be present if the |
| \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the |
| \member{tp_flags} field of the object's \ctype{PyTypeObject}. Before using |
| this slot, the caller should test whether it is present by using the |
| \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function. |
| If present, it may be \NULL, indicating that the object's contents |
| cannot be used as \emph{8-bit characters}. |
| The slot function may also raise an error if the object's contents |
| cannot be interpreted as 8-bit characters. For example, if the object |
| is an array which is configured to hold floating point values, an |
| exception may be raised if a caller attempts to use |
| \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters. |
| This notion of exporting the internal buffers as ``text'' is used to |
| distinguish between objects that are binary in nature, and those which |
| have character-based content. |
| |
| \strong{Note:} The current policy seems to state that these characters |
| may be multi-byte characters. This implies that a buffer size of |
| \var{N} does not mean there are \var{N} characters present. |
| \end{ctypedesc} |
| |
| \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER} |
| Flag bit set in the type structure to indicate that the |
| \member{bf_getcharbuffer} slot is known. This being set does not |
| indicate that the object supports the buffer interface or that the |
| \member{bf_getcharbuffer} slot is non-\NULL. |
| \end{datadesc} |
| |
| \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc) |
| (PyObject *self, int segment, void **ptrptr)} |
| Return a pointer to a readable segment of the buffer. This function |
| is allowed to raise an exception, in which case it must return |
| \code{-1}. The \var{segment} which is passed must be zero or |
| positive, and strictly less than the number of segments returned by |
| the \member{bf_getsegcount} slot function. On success, it returns the |
| length of the buffer memory, and sets \code{*\var{ptrptr}} to a |
| pointer to that memory. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc) |
| (PyObject *self, int segment, void **ptrptr)} |
| Return a pointer to a writable memory buffer in \code{*\var{ptrptr}}, |
| and the length of that segment as the function return value. |
| The memory buffer must correspond to buffer segment \var{segment}. |
| Must return \code{-1} and set an exception on error. |
| \exception{TypeError} should be raised if the object only supports |
| read-only buffers, and \exception{SystemError} should be raised when |
| \var{segment} specifies a segment that doesn't exist. |
| % Why doesn't it raise ValueError for this one? |
| % GJS: because you shouldn't be calling it with an invalid |
| % segment. That indicates a blatant programming error in the C |
| % code. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc) |
| (PyObject *self, int *lenp)} |
| Return the number of memory segments which comprise the buffer. If |
| \var{lenp} is not \NULL, the implementation must report the sum of the |
| sizes (in bytes) of all segments in \code{*\var{lenp}}. |
| The function cannot fail. |
| \end{ctypedesc} |
| |
| \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc) |
| (PyObject *self, int segment, const char **ptrptr)} |
| \end{ctypedesc} |
| |
| |
| \section{Supporting the Iterator Protocol |
| \label{supporting-iteration}} |
| |
| |
| \section{Supporting Cyclic Garbarge Collection |
| \label{supporting-cycle-detection}} |
| |
| Python's support for detecting and collecting garbage which involves |
| circular references requires support from object types which are |
| ``containers'' for other objects which may also be containers. Types |
| which do not store references to other objects, or which only store |
| references to atomic types (such as numbers or strings), do not need |
| to provide any explicit support for garbage collection. |
| |
| To create a container type, the \member{tp_flags} field of the type |
| object must include the \constant{Py_TPFLAGS_GC} and provide an |
| implementation of the \member{tp_traverse} handler. The computed |
| value of the \member{tp_basicsize} field must include |
| \constant{PyGC_HEAD_SIZE} as well. If instances of the type are |
| mutable, a \member{tp_clear} implementation must also be provided. |
| |
| \begin{datadesc}{Py_TPFLAGS_GC} |
| Objects with a type with this flag set must conform with the rules |
| documented here. For convenience these objects will be referred to |
| as container objects. |
| \end{datadesc} |
| |
| \begin{datadesc}{PyGC_HEAD_SIZE} |
| Extra memory needed for the garbage collector. Container objects |
| must include this in the calculation of their tp_basicsize. If the |
| collector is disabled at compile time then this is \code{0}. |
| \end{datadesc} |
| |
| Constructors for container types must conform to two rules: |
| |
| \begin{enumerate} |
| \item The memory for the object must be allocated using |
| \cfunction{PyObject_New()} or \cfunction{PyObject_VarNew()}. |
| |
| \item Once all the fields which may contain references to other |
| containers are initialized, it must call |
| \cfunction{PyObject_GC_Init()}. |
| \end{enumerate} |
| |
| \begin{cfuncdesc}{void}{PyObject_GC_Init}{PyObject *op} |
| Adds the object \var{op} to the set of container objects tracked by |
| the collector. The collector can run at unexpected times so objects |
| must be valid while being tracked. This should be called once all |
| the fields followed by the \member{tp_traverse} handler become valid, |
| usually near the end of the constructor. |
| \end{cfuncdesc} |
| |
| Similarly, the deallocator for the object must conform to a similar |
| pair of rules: |
| |
| \begin{enumerate} |
| \item Before fields which refer to other containers are invalidated, |
| \cfunction{PyObject_GC_Fini()} must be called. |
| |
| \item The object's memory must be deallocated using |
| \cfunction{PyObject_Del()}. |
| \end{enumerate} |
| |
| \begin{cfuncdesc}{void}{PyObject_GC_Fini}{PyObject *op} |
| Remove the object \var{op} from the set of container objects tracked |
| by the collector. Note that \cfunction{PyObject_GC_Init()} can be |
| called again on this object to add it back to the set of tracked |
| objects. The deallocator (\member{tp_dealloc} handler) should call |
| this for the object before any of the fields used by the |
| \member{tp_traverse} handler become invalid. |
| |
| \strong{Note:} Any container which may be referenced from another |
| object reachable by the collector must itself be tracked by the |
| collector, so it is generally not safe to call this function |
| anywhere but in the object's deallocator. |
| \end{cfuncdesc} |
| |
| The \member{tp_traverse} handler accepts a function parameter of this |
| type: |
| |
| \begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)} |
| Type of the visitor function passed to the \member{tp_traverse} |
| handler. The function should be called with an object to traverse |
| as \var{object} and the third parameter to the \member{tp_traverse} |
| handler as \var{arg}. |
| \end{ctypedesc} |
| |
| The \member{tp_traverse} handler must have the following type: |
| |
| \begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self, |
| visitproc visit, void *arg)} |
| Traversal function for a container object. Implementations must |
| call the \var{visit} function for each object directly contained by |
| \var{self}, with the parameters to \var{visit} being the contained |
| object and the \var{arg} value passed to the handler. If |
| \var{visit} returns a non-zero value then an error has occurred and |
| that value should be returned immediately. |
| \end{ctypedesc} |
| |
| The \member{tp_clear} handler must be of the \ctype{inquiry} type, or |
| \NULL{} if the object is immutable. |
| |
| \begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)} |
| Drop references that may have created reference cycles. Immutable |
| objects do not have to define this method since they can never |
| directly create reference cycles. Note that the object must still |
| be valid after calling this method (don't just call |
| \cfunction{Py_DECREF()} on a reference). The collector will call |
| this method if it detects that this object is involved in a |
| reference cycle. |
| \end{ctypedesc} |
| |
| |
| \subsection{Example Cycle Collector Support |
| \label{example-cycle-support}} |
| |
| This example shows only enough of the implementation of an extension |
| type to show how the garbage collector support needs to be added. It |
| shows the definition of the object structure, the |
| \member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc} |
| implementations, the type structure, and a constructor --- the module |
| initialization needed to export the constructor to Python is not shown |
| as there are no special considerations there for the collector. To |
| make this interesting, assume that the module exposes ways for the |
| \member{container} field of the object to be modified. Note that |
| since no checks are made on the type of the object used to initialize |
| \member{container}, we have to assume that it may be a container. |
| |
| \begin{verbatim} |
| #include "Python.h" |
| |
| typedef struct { |
| PyObject_HEAD |
| PyObject *container; |
| } MyObject; |
| |
| static int |
| my_traverse(MyObject *self, visitproc visit, void *arg) |
| { |
| if (self->container != NULL) |
| return visit(self->container, arg); |
| else |
| return 0; |
| } |
| |
| static int |
| my_clear(MyObject *self) |
| { |
| Py_XDECREF(self->container); |
| self->container = NULL; |
| |
| return 0; |
| } |
| |
| static void |
| my_dealloc(MyObject *self) |
| { |
| PyObject_GC_Fini((PyObject *) self); |
| Py_XDECREF(self->container); |
| PyObject_Del(self); |
| } |
| \end{verbatim} |
| |
| \begin{verbatim} |
| statichere PyTypeObject |
| MyObject_Type = { |
| PyObject_HEAD_INIT(NULL) |
| 0, |
| "MyObject", |
| sizeof(MyObject) + PyGC_HEAD_SIZE, |
| 0, |
| (destructor)my_dealloc, /* tp_dealloc */ |
| 0, /* tp_print */ |
| 0, /* tp_getattr */ |
| 0, /* tp_setattr */ |
| 0, /* tp_compare */ |
| 0, /* tp_repr */ |
| 0, /* tp_as_number */ |
| 0, /* tp_as_sequence */ |
| 0, /* tp_as_mapping */ |
| 0, /* tp_hash */ |
| 0, /* tp_call */ |
| 0, /* tp_str */ |
| 0, /* tp_getattro */ |
| 0, /* tp_setattro */ |
| 0, /* tp_as_buffer */ |
| Py_TPFLAGS_DEFAULT | Py_TPFLAGS_GC, |
| 0, /* tp_doc */ |
| (traverseproc)my_traverse, /* tp_traverse */ |
| (inquiry)my_clear, /* tp_clear */ |
| 0, /* tp_richcompare */ |
| 0, /* tp_weaklistoffset */ |
| }; |
| |
| /* This constructor should be made accessible from Python. */ |
| static PyObject * |
| new_object(PyObject *unused, PyObject *args) |
| { |
| PyObject *container = NULL; |
| MyObject *result = NULL; |
| |
| if (PyArg_ParseTuple(args, "|O:new_object", &container)) { |
| result = PyObject_New(MyObject, &MyObject_Type); |
| if (result != NULL) { |
| result->container = container; |
| PyObject_GC_Init(); |
| } |
| } |
| return (PyObject *) result; |
| } |
| \end{verbatim} |
| |
| |
| % \chapter{Debugging \label{debugging}} |
| % |
| % XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. |
| |
| |
| \appendix |
| \chapter{Reporting Bugs} |
| \input{reportingbugs} |
| |
| \chapter{History and License} |
| \input{license} |
| |
| \input{api.ind} % Index -- must be last |
| |
| \end{document} |