a later chapter.
-\chapter{Basic Utilities}
+\chapter{The Very High Level Layer}
-XXX These utilities should be moved to some other section...
+The functions in this chapter will let you execute Python source code
+given in a file or a buffer, but they will not let you interact in a
+more detailed way with the interpreter.
-\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
-Print a fatal error message and kill the process. No cleanup is
-performed. This function should only be invoked when a condition is
-detected that would make it dangerous to continue using the Python
-interpreter; e.g., when the object administration appears to be
-corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is
-called which will attempt to produce a \file{core} file.
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_Exit}{int status}
-Exit the current process. This calls \code{Py_Finalize()} and then
-calls the standard \C{} library function \code{exit(\var{status})}.
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
-Register a cleanup function to be called by \cfunction{Py_Finalize()}.
-The cleanup function will be called with no arguments and should
-return no value. At most 32 cleanup functions can be registered.
-When the registration is successful, \cfunction{Py_AtExit()} returns
-\code{0}; on failure, it returns \code{-1}. The cleanup function
-registered last is called first. Each cleanup function will be called
-at most once. Since Python's internal finallization will have
-completed before the cleanup function, no Python APIs should be called
-by \var{func}.
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
\end{cfuncdesc}
\end{cfuncdesc}
-\section{Importing modules}
+\section{Process Control}
+
+\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
+Print a fatal error message and kill the process. No cleanup is
+performed. This function should only be invoked when a condition is
+detected that would make it dangerous to continue using the Python
+interpreter; e.g., when the object administration appears to be
+corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is
+called which will attempt to produce a \file{core} file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Exit}{int status}
+Exit the current process. This calls \code{Py_Finalize()} and then
+calls the standard \C{} library function \code{exit(\var{status})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
+Register a cleanup function to be called by \cfunction{Py_Finalize()}.
+The cleanup function will be called with no arguments and should
+return no value. At most 32 cleanup functions can be registered.
+When the registration is successful, \cfunction{Py_AtExit()} returns
+\code{0}; on failure, it returns \code{-1}. The cleanup function
+registered last is called first. Each cleanup function will be called
+at most once. Since Python's internal finallization will have
+completed before the cleanup function, no Python APIs should be called
+by \var{func}.
+\end{cfuncdesc}
+
+
+\section{Importing Modules}
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \code{PyImport_ImportModuleEx}
\end{cvardesc}
-\chapter{Debugging}
-
-XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
-
-
-\chapter{The Very High Level Layer}
-
-The functions in this chapter will let you execute Python source code
-given in a file or a buffer, but they will not let you interact in a
-more detailed way with the interpreter.
-
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
-\end{cfuncdesc}
-
-
\chapter{Abstract Objects Layer}
The functions in this chapter interact with Python objects regardless
if you receive an object from a Python program and you are not sure
that it has the right type, you must perform a type check first;
e.g. to check that an object is a dictionary, use
-\code{PyDict_Check()}.
+\cfunction{PyDict_Check()}. The chapter is structured like the
+``family tree'' of Python object types.
-\chapter{Defining New Object Types}
+\section{Fundamental Objects}
+
+This section describes Python type objects and the singleton object
+\code{None}.
+
+
+\subsection{Type Objects}
+
+\begin{ctypedesc}{PyTypeObject}
+
+\end{ctypedesc}
+
+\begin{cvardesc}{PyObject *}{PyType_Type}
+
+\end{cvardesc}
+
+
+\subsection{The None Object}
+
+\begin{cvardesc}{PyObject *}{Py_None}
+XXX macro
+\end{cvardesc}
+
+
+\section{Sequence Objects}
+
+Generic operations on sequence objects were discussed in the previous
+chapter; this section deals with the specific kinds of sequence
+objects that are intrinsic to the Python language.
+
+
+\subsection{String Objects}
+
+\begin{ctypedesc}{PyStringObject}
+This subtype of \code{PyObject} represents a Python string object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyString_Type}
+This instance of \code{PyTypeObject} represents the Python string type.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
+\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
+\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
+
\end{cfuncdesc}
-\chapter{Initialization, Finalization, and Threads}
+\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-\begin{cfuncdesc}{void}{Py_Initialize}{}
-Initialize the Python interpreter. In an application embedding
-Python, this should be called before using any other Python/C API
-functions; with the exception of \code{Py_SetProgramName()},
-\code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
-\code{PyEval_AcquireLock()}. This initializes the table of loaded
-modules (\code{sys.modules}), and creates the fundamental modules
-\code{__builtin__}, \code{__main__} and \code{sys}. It also
-initializes the module search path (\code{sys.path}). It does not set
-\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
-when called for a second time (without calling \code{Py_Finalize()}
-first). There is no return value; it is a fatal error if the
-initialization fails.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{Py_IsInitialized}{}
-\strong{(NEW in 1.5a4!)}
-Return true (nonzero) when the Python interpreter has been
-initialized, false (zero) if not. After \code{Py_Finalize()} is
-called, this returns false until \code{Py_Initialize()} is called
-again.
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_Finalize}{}
-\strong{(NEW in 1.5a3!)}
-Undo all initializations made by \code{Py_Initialize()} and subsequent
-use of Python/C API functions, and destroy all sub-interpreters (see
-\code{Py_NewInterpreter()} below) that were created and not yet
-destroyed since the last call to \code{Py_Initialize()}. Ideally,
-this frees all memory allocated by the Python interpreter. This is a
-no-op when called for a second time (without calling
-\code{Py_Initialize()} again first). There is no return value; errors
-during finalization are ignored.
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
-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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
-\emph{Bugs and caveats:} The destruction of modules and objects in
-modules is done in random order; this may cause destructors
-(\code{__del__} methods) to fail when they depend on other objects
-(even functions) or modules. Dynamically loaded extension modules
-loaded by Python are not unloaded. Small amounts of memory allocated
-by the Python interpreter may not be freed (if you find a leak, please
-report it). Memory tied up in circular references between objects is
-not freed. Some memory allocated by extension modules may not be
-freed. Some extension may not work properly if their initialization
-routine is called more than once; this can happen if an applcation
-calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
-\strong{(NEW in 1.5a3!)}
-Create a new sub-interpreter. This is an (almost) totally separate
-environment for the execution of Python code. In particular, the new
-interpreter has separate, independent versions of all imported
-modules, including the fundamental modules \code{__builtin__},
-\code{__main__} and \code{sys}. The table of loaded modules
-(\code{sys.modules}) and the module search path (\code{sys.path}) are
-also separate. The new environment has no \code{sys.argv} variable.
-It has new standard I/O stream file objects \code{sys.stdin},
-\code{sys.stdout} and \code{sys.stderr} (however these refer to the
-same underlying \code{FILE} structures in the \C{} library).
+\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
-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.)
+\end{cfuncdesc}
-Extension modules are shared between (sub-)interpreters as follows:
-the first time a particular extension is imported, it is initialized
-normally, and a (shallow) copy of its module's dictionary is
-squirreled away. When the same extension is imported by another
-(sub-)interpreter, a new module is initialized and filled with the
-contents of this copy; the extension's \code{init} function is not
-called. Note that this is different from what happens when as
-extension is imported after the interpreter has been completely
-re-initialized by calling \code{Py_Finalize()} and
-\code{Py_Initialize()}; in that case, the extension's \code{init}
-function \emph{is} called again.
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
-\emph{Bugs and caveats:} Because sub-interpreters (and the main
-interpreter) are part of the same process, the insulation between them
-isn't perfect -- for example, using low-level file operations like
-\code{os.close()} they can (accidentally or maliciously) affect each
-other's open files. Because of the way extensions are shared between
-(sub-)interpreters, some extensions may not work properly; this is
-especially likely when the extension makes use of (static) global
-variables, or when the extension manipulates its module's dictionary
-after its initialization. It is possible to insert objects created in
-one sub-interpreter into a namespace of another sub-interpreter; this
-should be done with great care to avoid sharing user-defined
-functions, methods, instances or classes between sub-interpreters,
-since import operations executed by such objects may affect the
-wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
-a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Destroy the (sub-)interpreter represented by the given thread state.
-The given thread state must be the current thread state. See the
-discussion of thread states below. When the call returns, the current
-thread state is \NULL{}. All thread states associated with this
-interpreted are destroyed. (The global interpreter lock must be held
-before calling this function and is still held when it returns.)
-\code{Py_Finalize()} will destroy all sub-interpreters that haven't
-been explicitly destroyed at that point.
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
-\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
-\strong{(NEW in 1.5a3!)}
-This function should be called before \code{Py_Initialize()} is called
-for the first time, if it is called at all. It tells the interpreter
-the value of the \code{argv[0]} argument to the \code{main()} function
-of the program. This is used by \code{Py_GetPath()} and some other
-functions below to find the Python run-time libraries relative to the
-interpreter executable. The default value is \code{"python"}. The
-argument should point to a zero-terminated character string in static
-storage whose contents will not change for the duration of the
-program's execution. No code in the Python interpreter will change
-the contents of this storage.
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
-Return the program name set with \code{Py_SetProgramName()}, or the
-default. The returned string points into static storage; the caller
-should not modify its value.
+\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
-Return the ``prefix'' for installed platform-independent files. This
-is derived through a number of complicated rules from the program name
-set with \code{Py_SetProgramName()} and some environment variables;
-for example, if the program name is \code{"/usr/local/bin/python"},
-the prefix is \code{"/usr/local"}. The returned string points into
-static storage; the caller should not modify its value. This
-corresponds to the \code{prefix} variable in the top-level
-\code{Makefile} and the \code{--prefix} argument to the
-\code{configure} script at build time. The value is available to
-Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
-also the next function.
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
-Return the ``exec-prefix'' for installed platform-\emph{de}pendent
-files. This is derived through a number of complicated rules from the
-program name set with \code{Py_SetProgramName()} and some environment
-variables; for example, if the program name is
-\code{"/usr/local/bin/python"}, the exec-prefix is
-\code{"/usr/local"}. The returned string points into static storage;
-the caller should not modify its value. This corresponds to the
-\code{exec_prefix} variable in the top-level \code{Makefile} and the
-\code{--exec_prefix} argument to the \code{configure} script at build
-time. The value is available to Python code as
-\code{sys.exec_prefix}. It is only useful on \UNIX{}.
-Background: The exec-prefix differs from the prefix when platform
-dependent files (such as executables and shared libraries) are
-installed in a different directory tree. In a typical installation,
-platform dependent files may be installed in the
-\code{"/usr/local/plat"} subtree while platform independent may be
-installed in \code{"/usr/local"}.
+\subsection{Tuple Objects}
-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!).
+\begin{ctypedesc}{PyTupleObject}
+This subtype of \code{PyObject} represents a Python tuple object.
+\end{ctypedesc}
-System administrators will know how to configure the \code{mount} or
-\code{automount} programs to share \code{"/usr/local"} between platforms
-while having \code{"/usr/local/plat"} be a different filesystem for each
-platform.
-\end{cfuncdesc}
+\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
+This instance of \code{PyTypeObject} represents the Python tuple type.
+\end{cvardesc}
-\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
-\strong{(NEW in 1.5a3!)}
-Return the full program name of the Python executable; this is
-computed as a side-effect of deriving the default module search path
-from the program name (set by \code{Py_SetProgramName()} above). The
-returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as
-\code{sys.executable}.
+\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
+Return true if the argument is a tuple object.
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetPath}{}
-Return the default module search path; this is computed from the
-program name (set by \code{Py_SetProgramName()} above) and some
-environment variables. The returned string consists of a series of
-directory names separated by a platform dependent delimiter character.
-The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
-DOS/Windows, and \code{'\\n'} (the ASCII newline character) on
-Macintosh. The returned string points into static storage; the caller
-should not modify its value. The value is available to Python code
-as the list \code{sys.path}, which may be modified to change the
-future search path for loaded modules.
+\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
+Return a new tuple object of size \code{s}
+\end{cfuncdesc}
-% XXX should give the exact rules
+\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
+akes a pointer to a tuple object, and returns the size
+of that tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
-Return the version of this Python interpreter. This is a string that
-looks something like
+\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
+returns the object at position \code{pos} in the tuple pointed
+to by \code{p}.
+\end{cfuncdesc}
-\begin{verbatim}
-"1.5a3 (#67, Aug 1 1997, 22:34:28) [GCC 2.7.2.2]"
-\end{verbatim}
+\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
+does the same, but does no checking of it's
+arguments.
+\end{cfuncdesc}
-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}.
+\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
+ int low,
+ int high}
+takes a slice of the tuple pointed to by \code{p} from
+\code{low} to \code{high} and returns it as a new tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{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}.
+\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
+ int pos,
+ PyObject *o}
+inserts a reference to object \code{o} at position \code{pos} of
+the tuple pointed to by \code{p}. It returns 0 on success.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
-Return the official copyright string for the current Python version,
-for example
+\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
+ int pos,
+ PyObject *o}
-\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
+does the same, but does no error checking, and
+should \emph{only} be used to fill in brand new tuples.
+\end{cfuncdesc}
-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}.
+\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
+ int new,
+ int last_is_sticky}
+can be used to resize a tuple. Because tuples are
+\emph{supposed} to be immutable, this should only be used if there is only
+one module referencing the object. Do \emph{not} use this if the tuple may
+already be known to some other part of the code. \code{last_is_sticky} is
+a flag - if set, the tuple will grow or shrink at the front, otherwise
+it will grow or shrink at the end. Think of this as destroying the old
+tuple and creating a new one, only more efficiently.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
-Return an indication of the compiler used to build the current Python
-version, in square brackets, for example
-\code{"[GCC 2.7.2.2]"}
+\subsection{List Objects}
-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}.
+\begin{ctypedesc}{PyListObject}
+This subtype of \code{PyObject} represents a Python list object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyList_Type}
+This instance of \code{PyTypeObject} represents the Python list type.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
+returns true if it's argument is a \code{PyListObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
-Return information about the sequence number and build date and time
-of the current Python interpreter instance, for example
+\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
-\begin{verbatim}
-"#67, Aug 1 1997, 22:34:28"
-\end{verbatim}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
-The returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as part of
-the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
-% XXX
+\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+
\end{cfuncdesc}
-% XXX Other PySys thingies (doesn't really belong in this chapter)
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
-\section{Thread State and the Global Interpreter Lock}
+\end{cfuncdesc}
-The Python interpreter is not fully thread safe. In order to support
-multi-threaded Python programs, there's a global lock that must be
-held by the current thread before it can safely access Python objects.
-Without the lock, even the simplest operations could cause problems in
-a multi-threaded proram: for example, when two threads simultaneously
-increment the reference count of the same object, the reference count
-could end up being incremented only once instead of twice.
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
-Therefore, the rule exists that only the thread that has acquired the
-global interpreter lock may operate on Python objects or call Python/C
-API functions. In order to support multi-threaded Python programs,
-the interpreter regularly release and reacquires the lock -- by
-default, every ten bytecode instructions (this can be changed with
-\code{sys.setcheckinterval()}). The lock is also released and
-reacquired around potentially blocking I/O operations like reading or
-writing a file, so that other threads can run while the thread that
-requests the I/O is waiting for the I/O operation to complete.
+\end{cfuncdesc}
-The Python interpreter needs to keep some bookkeeping information
-separate per thread -- for this it uses a data structure called
-PyThreadState. This is new in Python 1.5; in earlier versions, such
-state was stored in global variables, and switching threads could
-cause problems. In particular, exception handling is now thread safe,
-when the application uses \code{sys.exc_info()} to access the exception
-last raised in the current thread.
-
-There's one global variable left, however: the pointer to the current
-PyThreadState structure. While most thread packages have a way to
-store ``per-thread global data'', Python's internal platform
-independent thread abstraction doesn't support this (yet). Therefore,
-the current thread state must be manipulated explicitly.
-
-This is easy enough in most cases. Most code manipulating the global
-interpreter lock has the following simple structure:
-
-\begin{verbatim}
-Save the thread state in a local variable.
-Release the interpreter lock.
-...Do some blocking I/O operation...
-Reacquire the interpreter lock.
-Restore the thread state from the local variable.
-\end{verbatim}
-
-This is so common that a pair of macros exists to simplify it:
-
-\begin{verbatim}
-Py_BEGIN_ALLOW_THREADS
-...Do some blocking I/O operation...
-Py_END_ALLOW_THREADS
-\end{verbatim}
-
-The BEGIN macro opens a new block and declares a hidden local
-variable; the END macro closes the block. Another advantage of using
-these two macros is that when Python is compiled without thread
-support, they are defined empty, thus saving the thread state and lock
-manipulations.
-
-When thread support is enabled, the block above expands to the
-following code:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyEval_SaveThread();
- ...Do some blocking I/O operation...
- PyEval_RestoreThread(_save);
-}
-\end{verbatim}
-
-Using even lower level primitives, we can get roughly the same effect
-as follows:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyThreadState_Swap(NULL);
- PyEval_ReleaseLock();
- ...Do some blocking I/O operation...
- PyEval_AcquireLock();
- PyThreadState_Swap(_save);
-}
-\end{verbatim}
-
-There are some subtle differences; in particular,
-\code{PyEval_RestoreThread()} saves and restores the value of the
-global variable \code{errno}, since the lock manipulation does not
-guarantee that \code{errno} is left alone. Also, when thread support
-is disabled, \code{PyEval_SaveThread()} and
-\code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
-\code{PyEval_ReleaseLock()} and \code{PyEval_AcquireLock()} are not
-available. (This is done so that dynamically loaded extensions
-compiled with thread support enabled can be loaded by an interpreter
-that was compiled with disabled thread support.)
-
-The global interpreter lock is used to protect the pointer to the
-current thread state. When releasing the lock and saving the thread
-state, the current thread state pointer must be retrieved before the
-lock is released (since another thread could immediately acquire the
-lock and store its own thread state in the global variable).
-Reversely, when acquiring the lock and restoring the thread state, the
-lock must be acquired before storing the thread state pointer.
+\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
-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.
+\end{cfuncdesc}
-When creating a thread data structure, you need to provide an
-interpreter state data structure. The interpreter state data
-structure hold global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}). Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \code{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
+\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
-XXX More?
+\end{cfuncdesc}
-\begin{ctypedesc}{PyInterpreterState}
-\strong{(NEW in 1.5a3!)}
-This data structure represents the state shared by a number of
-cooperating threads. Threads belonging to the same interpreter
-share their module administration and a few other internal items.
-There are no public members in this structure.
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
-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}
+\end{cfuncdesc}
-\begin{ctypedesc}{PyThreadState}
-\strong{(NEW in 1.5a3!)}
-This data structure represents the state of a single thread. The only
-public data member is \code{PyInterpreterState *interp}, which points
-to this thread's interpreter state.
-\end{ctypedesc}
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
-\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
-Initialize and acquire the global interpreter lock. It should be
-called in the main thread before creating a second thread or engaging
-in any other thread operations such as \code{PyEval_ReleaseLock()} or
-\code{PyEval_ReleaseThread(tstate)}. It is not needed before
-calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
+\end{cfuncdesc}
-This is a no-op when called for a second time. It is safe to call
-this function before calling \code{Py_Initialize()}.
+\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
-When only the main thread exists, no lock operations are needed. This
-is a common situation (most Python programs do not use threads), and
-the lock operations slow the interpreter down a bit. Therefore, the
-lock is not created initially. This situation is equivalent to having
-acquired the lock: when there is only a single thread, all object
-accesses are safe. Therefore, when this function initializes the
-lock, it also acquires it. Before the Python \code{thread} module
-creates a new thread, knowing that either it has the lock or the lock
-hasn't been created yet, it calls \code{PyEval_InitThreads()}. When
-this call returns, it is guaranteed that the lock has been created and
-that it has acquired it.
+\end{cfuncdesc}
-It is \strong{not} safe to call this function when it is unknown which
-thread (if any) currently has the global interpreter lock.
+\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
-This function is not available when thread support is disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
-\strong{(NEW in 1.5a3!)}
-Acquire the global interpreter lock. The lock must have been created
-earlier. If this thread already has the lock, a deadlock ensues.
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
-\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
-\strong{(NEW in 1.5a3!)}
-Release the global interpreter lock. The lock must have been created
-earlier. This function is not available when thread support is
-disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Acquire the global interpreter lock and then set the current thread
-state to \var{tstate}, which should not be \NULL{}. The lock must
-have been created earlier. If this thread already has the lock,
-deadlock ensues. This function is not available when thread support
-is disabled at
-compile time.
-\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Reset the current thread state to \NULL{} and release the global
-interpreter lock. The lock must have been created earlier and must be
-held by the current thread. The \var{tstate} argument, which must not
-be \NULL{}, is only used to check that it represents the current
-thread state -- if it isn't, a fatal error is reported. This function
-is not available when thread support is disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
-\strong{(Different return type in 1.5a3!)}
-Release the interpreter lock (if it has been created and thread
-support is enabled) and reset the thread state to \NULL{},
-returning the previous thread state (which is not \NULL{}). If
-the lock has been created, the current thread must have acquired it.
-(This function is available even when thread support is disabled at
-compile time.)
-\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
-\strong{(Different argument type in 1.5a3!)}
-Acquire the interpreter lock (if it has been created and thread
-support is enabled) and set the thread state to \var{tstate}, which
-must not be \NULL{}. If the lock has been created, the current
-thread must not have acquired it, otherwise deadlock ensues. (This
-function is available even when thread support is disabled at compile
-time.)
-\end{cfuncdesc}
+\section{Mapping Objects}
-% XXX These aren't really C types, but the ctypedesc macro is the simplest!
-\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
-This macro expands to
-\code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
-Note that it contains an opening brace; it must be matched with a
-following \code{Py_END_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
+\subsection{Dictionary Objects}
-\begin{ctypedesc}{Py_END_ALLOW_THREADS}
-This macro expands to
-\code{PyEval_RestoreThread(_save); \} }.
-Note that it contains a closing brace; it must be matched with an
-earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
+\begin{ctypedesc}{PyDictObject}
+This subtype of \code{PyObject} represents a Python dictionary object.
\end{ctypedesc}
-\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
-This macro expands to \code{PyEval_RestoreThread(_save);} i.e. it
-is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
-brace. It is a no-op when thread support is disabled at compile
-time.
-\end{ctypedesc}
+\begin{cvardesc}{PyTypeObject}{PyDict_Type}
+This instance of \code{PyTypeObject} represents the Python dictionary type.
+\end{cvardesc}
-\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
-This macro expands to \code{_save = PyEval_SaveThread();} i.e. it is
-equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
-and variable declaration. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
+\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
+returns true if it's argument is a PyDictObject
+\end{cfuncdesc}
-All of the following functions are only available when thread support
-is enabled at compile time, and must be called only when the
-interpreter lock has been created. They are all new in 1.5a3.
+\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
+returns a new empty dictionary.
+\end{cfuncdesc}
-\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
-Create a new interpreter state object. The interpreter lock must be
-held.
+\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
+empties an existing dictionary and deletes it.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
-Reset all information in an interpreter state object. The interpreter
-lock must be held.
+\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
+ PyObject *key,
+ PyObject *val}
+inserts \code{value} into the dictionary with a key of
+\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
+be hashable.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
-Destroy an interpreter state object. The interpreter lock need not be
-held. The interpreter state must have been reset with a previous
-call to \code{PyInterpreterState_Clear()}.
+\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
+ char *key,
+ PyObject *val}
+inserts \code{value} into the dictionary using \code{key}
+as a key. \code{key} should be a char *
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
-Create a new thread state object belonging to the given interpreter
-object. The interpreter lock must be held.
+\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
+removes the entry in dictionary \code{p} with key \code{key}.
+\code{key} is a PyObject.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
-Reset all information in a thread state object. The interpreter lock
-must be held.
+\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
+removes the entry in dictionary \code{p} which has a key
+specified by the \code{char *}\code{key}.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
-Destroy a thread state object. The interpreter lock need not be
-held. The thread state must have been reset with a previous
-call to \code{PyThreadState_Clear()}.
+\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
+returns the object from dictionary \code{p} which has a key
+\code{key}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
+does the same, but \code{key} is specified as a
+\code{char *}, rather than a \code{PyObject *}.
\end{cfuncdesc}
-\begin{cfuncdesc}{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{}).
+\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
+returns a PyListObject containing all the items
+from the dictionary, as in the mapping method \code{items()} (see the Reference
+Guide)
\end{cfuncdesc}
-\begin{cfuncdesc}{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.
+\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
+returns a PyListObject containing all the keys
+from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
\end{cfuncdesc}
+\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
+returns a PyListObject containing all the values
+from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
+\end{cfuncdesc}
-\section{Defining New Object Types}
+\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
+returns the number of items in the dictionary.
+\end{cfuncdesc}
-XXX To be done:
+\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
+ int ppos,
+ PyObject **pkey,
+ PyObject **pvalue}
-PyObject, PyVarObject
+\end{cfuncdesc}
-PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-Typedefs:
-unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
-intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
-getreadbufferproc, getwritebufferproc, getsegcountproc,
-destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
-setattrofunc, cmpfunc, reprfunc, hashfunc
+\section{Numeric Objects}
-PyNumberMethods
+\subsection{Plain Integer Objects}
-PySequenceMethods
+\begin{ctypedesc}{PyIntObject}
+This subtype of \code{PyObject} represents a Python integer object.
+\end{ctypedesc}
-PyMappingMethods
+\begin{cvardesc}{PyTypeObject}{PyInt_Type}
+This instance of \code{PyTypeObject} represents the Python plain
+integer type.
+\end{cvardesc}
-PyBufferProcs
+\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
-PyTypeObject
+\end{cfuncdesc}
-DL_IMPORT
+\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
+creates a new integer object with a value of \code{ival}.
-PyType_Type
+The current implementation keeps an array of integer objects for all
+integers between -1 and 100, when you create an int in that range you
+actually just get back a reference to the existing object. So it should
+be possible to change the value of 1. I suspect the behaviour of python
+in this case is undefined. :-)
+\end{cfuncdesc}
-Py*_Check
+\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
+returns the value of the object \code{io}.
+\end{cfuncdesc}
-Py_None, _Py_NoneStruct
+\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
+will first attempt to cast the object to a PyIntObject, if
+it is not already one, and the return it's value.
+\end{cfuncdesc}
-_PyObject_New, _PyObject_NewVar
+\begin{cfuncdesc}{long}{PyInt_GetMax}{}
+returns the systems idea of the largest int it can handle
+(LONG_MAX, as defined in the system header files)
+\end{cfuncdesc}
-PyObject_NEW, PyObject_NEW_VAR
+\subsection{Long Integer Objects}
-\chapter{Specific Data Types}
+\begin{ctypedesc}{PyLongObject}
+This subtype of \code{PyObject} represents a Python long integer object.
+\end{ctypedesc}
-This chapter describes the functions that deal with specific types of
-Python objects. It is structured like the ``family tree'' of Python
-object types.
+\begin{cvardesc}{PyTypeObject}{PyLong_Type}
+This instance of \code{PyTypeObject} represents the Python long integer type.
+\end{cvardesc}
+\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
+returns true if it's argument is a \code{PyLongObject}
+\end{cfuncdesc}
-\section{Fundamental Objects}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
-This section describes Python type objects and the singleton object
-\code{None}.
+\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
-\subsection{Type Objects}
+\end{cfuncdesc}
-\begin{ctypedesc}{PyTypeObject}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
-\end{ctypedesc}
+\end{cfuncdesc}
-\begin{cvardesc}{PyObject *}{PyType_Type}
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
-\end{cvardesc}
+\end{cfuncdesc}
+\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
-\subsection{The None Object}
+\end{cfuncdesc}
-\begin{cvardesc}{PyObject *}{Py_None}
-XXX macro
-\end{cvardesc}
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
+\end{cfuncdesc}
-\section{Sequence Objects}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
-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.
+\end{cfuncdesc}
-\subsection{String Objects}
+\subsection{Floating Point Objects}
-\begin{ctypedesc}{PyStringObject}
-This subtype of \code{PyObject} represents a Python string object.
+\begin{ctypedesc}{PyFloatObject}
+This subtype of \code{PyObject} represents a Python floating point object.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-This instance of \code{PyTypeObject} represents the Python string type.
+\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
+This instance of \code{PyTypeObject} represents the Python floating
+point type.
\end{cvardesc}
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-
+\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
+returns true if it's argument is a \code{PyFloatObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-\end{cfuncdesc}
+\subsection{Complex Number Objects}
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
+\begin{ctypedesc}{Py_complex}
+typedef struct {
+ double real;
+ double imag;
+}
+\end{ctypedesc}
-\end{cfuncdesc}
+\begin{ctypedesc}{PyComplexObject}
+This subtype of \code{PyObject} represents a Python complex number object.
+\end{ctypedesc}
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
+\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
+This instance of \code{PyTypeObject} represents the Python complex
+number type.
+\end{cvardesc}
+\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
+returns true if it's argument is a \code{PyComplexObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
+\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
+\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
-\subsection{Tuple Objects}
-
-\begin{ctypedesc}{PyTupleObject}
-This subtype of \code{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
-This instance of \code{PyTypeObject} represents the Python tuple type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
-Return true if the argument is a tuple object.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
-Return a new tuple object of size \code{s}
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
-akes a pointer to a tuple object, and returns the size
-of that tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
-returns the object at position \code{pos} in the tuple pointed
-to by \code{p}.
-\end{cfuncdesc}
+\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
-does the same, but does no checking of it's
-arguments.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
- int low,
- int high}
-takes a slice of the tuple pointed to by \code{p} from
-\code{low} to \code{high} and returns it as a new tuple.
-\end{cfuncdesc}
+\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
- int pos,
- PyObject *o}
-inserts a reference to object \code{o} at position \code{pos} of
-the tuple pointed to by \code{p}. It returns 0 on success.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
- int pos,
- PyObject *o}
+\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-does the same, but does no error checking, and
-should \emph{only} be used to fill in brand new tuples.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
- int new,
- int last_is_sticky}
-can be used to resize a tuple. Because tuples are
-\emph{supposed} to be immutable, this should only be used if there is only
-one module referencing the object. Do \emph{not} use this if the tuple may
-already be known to some other part of the code. \code{last_is_sticky} is
-a flag - if set, the tuple will grow or shrink at the front, otherwise
-it will grow or shrink at the end. Think of this as destroying the old
-tuple and creating a new one, only more efficiently.
-\end{cfuncdesc}
-\subsection{List Objects}
+\section{Other Objects}
-\begin{ctypedesc}{PyListObject}
-This subtype of \code{PyObject} represents a Python list object.
+\subsection{File Objects}
+
+\begin{ctypedesc}{PyFileObject}
+This subtype of \code{PyObject} represents a Python file object.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
-This instance of \code{PyTypeObject} represents the Python list type.
+\begin{cvardesc}{PyTypeObject}{PyFile_Type}
+This instance of \code{PyTypeObject} represents the Python file type.
\end{cvardesc}
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-returns true if it's argument is a \code{PyListObject}
+\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
+returns true if it's argument is a \code{PyFileObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
+\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
+creates a new PyFileObject pointing to the file
+specified in \code{name} with the mode specified in \code{mode}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
+ char *name, char *mode, int (*close})
+creates a new PyFileObject from the already-open \code{fp}.
+The function \code{close} will be called when the file should be closed.
+\end{cfuncdesc}
+\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
+returns the file object associated with \code{p} as a \code{FILE *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
+\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
+undocumented as yet
+\end{cfuncdesc}
+\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
+returns the name of the file specified by \code{p} as a
+PyStringObject
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
+on systems with \code{setvbuf} only
+\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
+same as the file object method \code{softspace}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
+writes object \code{obj} to file object \code{p}
+\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
+writes string \code{s} to file object \code{p}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
-\end{cfuncdesc}
+\subsection{CObjects}
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
+XXX
-\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
+\chapter{Initialization, Finalization, and Threads}
+\begin{cfuncdesc}{void}{Py_Initialize}{}
+Initialize the Python interpreter. In an application embedding
+Python, this should be called before using any other Python/C API
+functions; with the exception of \code{Py_SetProgramName()},
+\code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
+\code{PyEval_AcquireLock()}. This initializes the table of loaded
+modules (\code{sys.modules}), and creates the fundamental modules
+\code{__builtin__}, \code{__main__} and \code{sys}. It also
+initializes the module search path (\code{sys.path}). It does not set
+\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
+when called for a second time (without calling \code{Py_Finalize()}
+first). There is no return value; it is a fatal error if the
+initialization fails.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
-
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+\strong{(NEW in 1.5a4!)}
+Return true (nonzero) when the Python interpreter has been
+initialized, false (zero) if not. After \code{Py_Finalize()} is
+called, this returns false until \code{Py_Initialize()} is called
+again.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
+\begin{cfuncdesc}{void}{Py_Finalize}{}
+\strong{(NEW in 1.5a3!)}
+Undo all initializations made by \code{Py_Initialize()} and subsequent
+use of Python/C API functions, and destroy all sub-interpreters (see
+\code{Py_NewInterpreter()} below) that were created and not yet
+destroyed since the last call to \code{Py_Initialize()}. Ideally,
+this frees all memory allocated by the Python interpreter. This is a
+no-op when called for a second time (without calling
+\code{Py_Initialize()} again first). There is no return value; errors
+during finalization are ignored.
+
+This function is provided for a number of reasons. An embedding
+application might want to restart Python without having to restart the
+application itself. An application that has loaded the Python
+interpreter from a dynamically loadable library (or DLL) might want to
+free all memory allocated by Python before unloading the DLL. During a
+hunt for memory leaks in an application a developer might want to free
+all memory allocated by Python before exiting from the application.
+\emph{Bugs and caveats:} The destruction of modules and objects in
+modules is done in random order; this may cause destructors
+(\code{__del__} methods) to fail when they depend on other objects
+(even functions) or modules. Dynamically loaded extension modules
+loaded by Python are not unloaded. Small amounts of memory allocated
+by the Python interpreter may not be freed (if you find a leak, please
+report it). Memory tied up in circular references between objects is
+not freed. Some memory allocated by extension modules may not be
+freed. Some extension may not work properly if their initialization
+routine is called more than once; this can happen if an applcation
+calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
+\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
+\strong{(NEW in 1.5a3!)}
+Create a new sub-interpreter. This is an (almost) totally separate
+environment for the execution of Python code. In particular, the new
+interpreter has separate, independent versions of all imported
+modules, including the fundamental modules \code{__builtin__},
+\code{__main__} and \code{sys}. The table of loaded modules
+(\code{sys.modules}) and the module search path (\code{sys.path}) are
+also separate. The new environment has no \code{sys.argv} variable.
+It has new standard I/O stream file objects \code{sys.stdin},
+\code{sys.stdout} and \code{sys.stderr} (however these refer to the
+same underlying \code{FILE} structures in the \C{} library).
-\end{cfuncdesc}
+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.)
-\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
+Extension modules are shared between (sub-)interpreters as follows:
+the first time a particular extension is imported, it is initialized
+normally, and a (shallow) copy of its module's dictionary is
+squirreled away. When the same extension is imported by another
+(sub-)interpreter, a new module is initialized and filled with the
+contents of this copy; the extension's \code{init} function is not
+called. Note that this is different from what happens when as
+extension is imported after the interpreter has been completely
+re-initialized by calling \code{Py_Finalize()} and
+\code{Py_Initialize()}; in that case, the extension's \code{init}
+function \emph{is} called again.
+\emph{Bugs and caveats:} Because sub-interpreters (and the main
+interpreter) are part of the same process, the insulation between them
+isn't perfect -- for example, using low-level file operations like
+\code{os.close()} they can (accidentally or maliciously) affect each
+other's open files. Because of the way extensions are shared between
+(sub-)interpreters, some extensions may not work properly; this is
+especially likely when the extension makes use of (static) global
+variables, or when the extension manipulates its module's dictionary
+after its initialization. It is possible to insert objects created in
+one sub-interpreter into a namespace of another sub-interpreter; this
+should be done with great care to avoid sharing user-defined
+functions, methods, instances or classes between sub-interpreters,
+since import operations executed by such objects may affect the
+wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
+a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
-
+\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Destroy the (sub-)interpreter represented by the given thread state.
+The given thread state must be the current thread state. See the
+discussion of thread states below. When the call returns, the current
+thread state is \NULL{}. All thread states associated with this
+interpreted are destroyed. (The global interpreter lock must be held
+before calling this function and is still held when it returns.)
+\code{Py_Finalize()} will destroy all sub-interpreters that haven't
+been explicitly destroyed at that point.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
+\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+\strong{(NEW in 1.5a3!)}
+This function should be called before \code{Py_Initialize()} is called
+for the first time, if it is called at all. It tells the interpreter
+the value of the \code{argv[0]} argument to the \code{main()} function
+of the program. This is used by \code{Py_GetPath()} and some other
+functions below to find the Python run-time libraries relative to the
+interpreter executable. The default value is \code{"python"}. The
+argument should point to a zero-terminated character string in static
+storage whose contents will not change for the duration of the
+program's execution. No code in the Python interpreter will change
+the contents of this storage.
+\end{cfuncdesc}
+\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
+Return the program name set with \code{Py_SetProgramName()}, or the
+default. The returned string points into static storage; the caller
+should not modify its value.
\end{cfuncdesc}
+\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
+Return the ``prefix'' for installed platform-independent files. This
+is derived through a number of complicated rules from the program name
+set with \code{Py_SetProgramName()} and some environment variables;
+for example, if the program name is \code{"/usr/local/bin/python"},
+the prefix is \code{"/usr/local"}. The returned string points into
+static storage; the caller should not modify its value. This
+corresponds to the \code{prefix} variable in the top-level
+\code{Makefile} and the \code{--prefix} argument to the
+\code{configure} script at build time. The value is available to
+Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
+also the next function.
+\end{cfuncdesc}
-\section{Mapping Objects}
+\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
+Return the ``exec-prefix'' for installed platform-\emph{de}pendent
+files. This is derived through a number of complicated rules from the
+program name set with \code{Py_SetProgramName()} and some environment
+variables; for example, if the program name is
+\code{"/usr/local/bin/python"}, the exec-prefix is
+\code{"/usr/local"}. The returned string points into static storage;
+the caller should not modify its value. This corresponds to the
+\code{exec_prefix} variable in the top-level \code{Makefile} and the
+\code{--exec_prefix} argument to the \code{configure} script at build
+time. The value is available to Python code as
+\code{sys.exec_prefix}. It is only useful on \UNIX{}.
-\subsection{Dictionary Objects}
+Background: The exec-prefix differs from the prefix when platform
+dependent files (such as executables and shared libraries) are
+installed in a different directory tree. In a typical installation,
+platform dependent files may be installed in the
+\code{"/usr/local/plat"} subtree while platform independent may be
+installed in \code{"/usr/local"}.
-\begin{ctypedesc}{PyDictObject}
-This subtype of \code{PyObject} represents a Python dictionary object.
-\end{ctypedesc}
+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!).
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
-This instance of \code{PyTypeObject} represents the Python dictionary type.
-\end{cvardesc}
+System administrators will know how to configure the \code{mount} or
+\code{automount} programs to share \code{"/usr/local"} between platforms
+while having \code{"/usr/local/plat"} be a different filesystem for each
+platform.
+\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-returns true if it's argument is a PyDictObject
+\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
+\strong{(NEW in 1.5a3!)}
+Return the full program name of the Python executable; this is
+computed as a side-effect of deriving the default module search path
+from the program name (set by \code{Py_SetProgramName()} above). The
+returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as
+\code{sys.executable}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
-returns a new empty dictionary.
+\begin{cfuncdesc}{char *}{Py_GetPath}{}
+Return the default module search path; this is computed from the
+program name (set by \code{Py_SetProgramName()} above) and some
+environment variables. The returned string consists of a series of
+directory names separated by a platform dependent delimiter character.
+The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
+DOS/Windows, and \code{'\\n'} (the ASCII newline character) on
+Macintosh. The returned string points into static storage; the caller
+should not modify its value. The value is available to Python code
+as the list \code{sys.path}, which may be modified to change the
+future search path for loaded modules.
+
+% XXX should give the exact rules
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
-empties an existing dictionary and deletes it.
+\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
+Return the version of this Python interpreter. This is a string that
+looks something like
+
+\begin{verbatim}
+"1.5a3 (#67, Aug 1 1997, 22:34:28) [GCC 2.7.2.2]"
+\end{verbatim}
+
+The first word (up to the first space character) is the current Python
+version; the first three characters are the major and minor version
+separated by a period. The returned string points into static storage;
+the caller should not modify its value. The value is available to
+Python code as the list \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
- PyObject *key,
- PyObject *val}
-inserts \code{value} into the dictionary with a key of
-\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
-be hashable.
+\begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
+Return the platform identifier for the current platform. On \UNIX{},
+this is formed from the ``official'' name of the operating system,
+converted to lower case, followed by the major revision number; e.g.,
+for Solaris 2.x, which is also known as SunOS 5.x, the value is
+\code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
+is \code{"win"}. The returned string points into static storage;
+the caller should not modify its value. The value is available to
+Python code as \code{sys.platform}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
- char *key,
- PyObject *val}
-inserts \code{value} into the dictionary using \code{key}
-as a key. \code{key} should be a char *
-\end{cfuncdesc}
+\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
+Return the official copyright string for the current Python version,
+for example
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
-removes the entry in dictionary \code{p} with key \code{key}.
-\code{key} is a PyObject.
-\end{cfuncdesc}
+\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
-removes the entry in dictionary \code{p} which has a key
-specified by the \code{char *}\code{key}.
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as the list
+\code{sys.copyright}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
-returns the object from dictionary \code{p} which has a key
-\code{key}.
-\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{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
-does the same, but \code{key} is specified as a
-\code{char *}, rather than a \code{PyObject *}.
-\end{cfuncdesc}
+\code{"[GCC 2.7.2.2]"}
-\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
-returns a PyListObject containing all the items
-from the dictionary, as in the mapping method \code{items()} (see the Reference
-Guide)
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as part of
+the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
-returns a PyListObject containing all the keys
-from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
-\end{cfuncdesc}
+\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
+Return information about the sequence number and build date and time
+of the current Python interpreter instance, for example
-\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
-returns a PyListObject containing all the values
-from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
-\end{cfuncdesc}
+\begin{verbatim}
+"#67, Aug 1 1997, 22:34:28"
+\end{verbatim}
-\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
-returns the number of items in the dictionary.
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as part of
+the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
- int ppos,
- PyObject **pkey,
- PyObject **pvalue}
-
+\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
+% XXX
\end{cfuncdesc}
+% XXX Other PySys thingies (doesn't really belong in this chapter)
-\section{Numeric Objects}
+\section{Thread State and the Global Interpreter Lock}
-\subsection{Plain Integer Objects}
+The Python interpreter is not fully thread safe. In order to support
+multi-threaded Python programs, there's a global lock that must be
+held by the current thread before it can safely access Python objects.
+Without the lock, even the simplest operations could cause problems in
+a multi-threaded proram: for example, when two threads simultaneously
+increment the reference count of the same object, the reference count
+could end up being incremented only once instead of twice.
-\begin{ctypedesc}{PyIntObject}
-This subtype of \code{PyObject} represents a Python integer object.
-\end{ctypedesc}
+Therefore, the rule exists that only the thread that has acquired the
+global interpreter lock may operate on Python objects or call Python/C
+API functions. In order to support multi-threaded Python programs,
+the interpreter regularly release and reacquires the lock -- by
+default, every ten bytecode instructions (this can be changed with
+\code{sys.setcheckinterval()}). The lock is also released and
+reacquired around potentially blocking I/O operations like reading or
+writing a file, so that other threads can run while the thread that
+requests the I/O is waiting for the I/O operation to complete.
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
-This instance of \code{PyTypeObject} represents the Python plain
-integer type.
-\end{cvardesc}
+The Python interpreter needs to keep some bookkeeping information
+separate per thread -- for this it uses a data structure called
+PyThreadState. This is new in Python 1.5; in earlier versions, such
+state was stored in global variables, and switching threads could
+cause problems. In particular, exception handling is now thread safe,
+when the application uses \code{sys.exc_info()} to access the exception
+last raised in the current thread.
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
+There's one global variable left, however: the pointer to the current
+PyThreadState structure. While most thread packages have a way to
+store ``per-thread global data'', Python's internal platform
+independent thread abstraction doesn't support this (yet). Therefore,
+the current thread state must be manipulated explicitly.
-\end{cfuncdesc}
+This is easy enough in most cases. Most code manipulating the global
+interpreter lock has the following simple structure:
-\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
-creates a new integer object with a value of \code{ival}.
+\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}
-The current implementation keeps an array of integer objects for all
-integers between -1 and 100, when you create an int in that range you
-actually just get back a reference to the existing object. So it should
-be possible to change the value of 1. I suspect the behaviour of python
-in this case is undefined. :-)
-\end{cfuncdesc}
+This is so common that a pair of macros exists to simplify it:
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
-returns the value of the object \code{io}.
-\end{cfuncdesc}
+\begin{verbatim}
+Py_BEGIN_ALLOW_THREADS
+...Do some blocking I/O operation...
+Py_END_ALLOW_THREADS
+\end{verbatim}
-\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
-will first attempt to cast the object to a PyIntObject, if
-it is not already one, and the return it's value.
-\end{cfuncdesc}
+The BEGIN macro opens a new block and declares a hidden local
+variable; the END macro closes the block. Another advantage of using
+these two macros is that when Python is compiled without thread
+support, they are defined empty, thus saving the thread state and lock
+manipulations.
-\begin{cfuncdesc}{long}{PyInt_GetMax}{}
-returns the systems idea of the largest int it can handle
-(LONG_MAX, as defined in the system header files)
-\end{cfuncdesc}
+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}
-\subsection{Long Integer Objects}
+Using even lower level primitives, we can get roughly the same effect
+as follows:
-\begin{ctypedesc}{PyLongObject}
-This subtype of \code{PyObject} represents a Python long integer object.
-\end{ctypedesc}
+\begin{verbatim}
+{
+ PyThreadState *_save;
+ _save = PyThreadState_Swap(NULL);
+ PyEval_ReleaseLock();
+ ...Do some blocking I/O operation...
+ PyEval_AcquireLock();
+ PyThreadState_Swap(_save);
+}
+\end{verbatim}
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
-This instance of \code{PyTypeObject} represents the Python long integer type.
-\end{cvardesc}
+There are some subtle differences; in particular,
+\code{PyEval_RestoreThread()} saves and restores the value of the
+global variable \code{errno}, since the lock manipulation does not
+guarantee that \code{errno} is left alone. Also, when thread support
+is disabled, \code{PyEval_SaveThread()} and
+\code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
+\code{PyEval_ReleaseLock()} and \code{PyEval_AcquireLock()} are not
+available. (This is done so that dynamically loaded extensions
+compiled with thread support enabled can be loaded by an interpreter
+that was compiled with disabled thread support.)
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-returns true if it's argument is a \code{PyLongObject}
-\end{cfuncdesc}
+The global interpreter lock is used to protect the pointer to the
+current thread state. When releasing the lock and saving the thread
+state, the current thread state pointer must be retrieved before the
+lock is released (since another thread could immediately acquire the
+lock and store its own thread state in the global variable).
+Reversely, when acquiring the lock and restoring the thread state, the
+lock must be acquired before storing the thread state pointer.
-\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
+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.
-\end{cfuncdesc}
+When creating a thread data structure, you need to provide an
+interpreter state data structure. The interpreter state data
+structure hold global data that is shared by all threads in an
+interpreter, for example the module administration
+(\code{sys.modules}). Depending on your needs, you can either create
+a new interpreter state data structure, or share the interpreter state
+data structure used by the Python main thread (to access the latter,
+you must obtain the thread state and access its \code{interp} member;
+this must be done by a thread that is created by Python or by the main
+thread after Python is initialized).
-\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
+XXX More?
-\end{cfuncdesc}
+\begin{ctypedesc}{PyInterpreterState}
+\strong{(NEW in 1.5a3!)}
+This data structure represents the state shared by a number of
+cooperating threads. Threads belonging to the same interpreter
+share their module administration and a few other internal items.
+There are no public members in this structure.
-\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
+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}
-\end{cfuncdesc}
+\begin{ctypedesc}{PyThreadState}
+\strong{(NEW in 1.5a3!)}
+This data structure represents the state of a single thread. The only
+public data member is \code{PyInterpreterState *interp}, which points
+to this thread's interpreter state.
+\end{ctypedesc}
+
+\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
+Initialize and acquire the global interpreter lock. It should be
+called in the main thread before creating a second thread or engaging
+in any other thread operations such as \code{PyEval_ReleaseLock()} or
+\code{PyEval_ReleaseThread(tstate)}. It is not needed before
+calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
+This is a no-op when called for a second time. It is safe to call
+this function before calling \code{Py_Initialize()}.
-\end{cfuncdesc}
+When only the main thread exists, no lock operations are needed. This
+is a common situation (most Python programs do not use threads), and
+the lock operations slow the interpreter down a bit. Therefore, the
+lock is not created initially. This situation is equivalent to having
+acquired the lock: when there is only a single thread, all object
+accesses are safe. Therefore, when this function initializes the
+lock, it also acquires it. Before the Python \code{thread} module
+creates a new thread, knowing that either it has the lock or the lock
+hasn't been created yet, it calls \code{PyEval_InitThreads()}. When
+this call returns, it is guaranteed that the lock has been created and
+that it has acquired it.
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
+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}{double}{PyLong_AsDouble}{PyObject *}
-
+\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+\strong{(NEW in 1.5a3!)}
+Acquire the global interpreter lock. The lock must have been created
+earlier. If this thread already has the lock, a deadlock ensues.
+This function is not available when thread support is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
-
+\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+\strong{(NEW in 1.5a3!)}
+Release the global interpreter lock. The lock must have been created
+earlier. This function is not available when thread support is
+disabled at
+compile time.
\end{cfuncdesc}
-
-\subsection{Floating Point Objects}
-
-\begin{ctypedesc}{PyFloatObject}
-This subtype of \code{PyObject} represents a Python floating point object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
-This instance of \code{PyTypeObject} represents the Python floating
-point type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-returns true if it's argument is a \code{PyFloatObject}
+\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Acquire the global interpreter lock and then set the current thread
+state to \var{tstate}, which should not be \NULL{}. The lock must
+have been created earlier. If this thread already has the lock,
+deadlock ensues. This function is not available when thread support
+is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
-
+\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Reset the current thread state to \NULL{} and release the global
+interpreter lock. The lock must have been created earlier and must be
+held by the current thread. The \var{tstate} argument, which must not
+be \NULL{}, is only used to check that it represents the current
+thread state -- if it isn't, a fatal error is reported. This function
+is not available when thread support is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
-
+\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
+\strong{(Different return type in 1.5a3!)}
+Release the interpreter lock (if it has been created and thread
+support is enabled) and reset the thread state to \NULL{},
+returning the previous thread state (which is not \NULL{}). If
+the lock has been created, the current thread must have acquired it.
+(This function is available even when thread support is disabled at
+compile time.)
\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
-
+\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
+\strong{(Different argument type in 1.5a3!)}
+Acquire the interpreter lock (if it has been created and thread
+support is enabled) and set the thread state to \var{tstate}, which
+must not be \NULL{}. If the lock has been created, the current
+thread must not have acquired it, otherwise deadlock ensues. (This
+function is available even when thread support is disabled at compile
+time.)
\end{cfuncdesc}
+% XXX These aren't really C types, but the ctypedesc macro is the simplest!
+\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
+This macro expands to
+\code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
+Note that it contains an opening brace; it must be matched with a
+following \code{Py_END_ALLOW_THREADS} macro. See above for further
+discussion of this macro. It is a no-op when thread support is
+disabled at compile time.
+\end{ctypedesc}
-\subsection{Complex Number Objects}
+\begin{ctypedesc}{Py_END_ALLOW_THREADS}
+This macro expands to
+\code{PyEval_RestoreThread(_save); \} }.
+Note that it contains a closing brace; it must be matched with an
+earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
+discussion of this macro. It is a no-op when thread support is
+disabled at compile time.
+\end{ctypedesc}
-\begin{ctypedesc}{Py_complex}
-typedef struct {
- double real;
- double imag;
-}
+\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
+This macro expands to \code{PyEval_RestoreThread(_save);} i.e. it
+is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
+brace. It is a no-op when thread support is disabled at compile
+time.
\end{ctypedesc}
-\begin{ctypedesc}{PyComplexObject}
-This subtype of \code{PyObject} represents a Python complex number object.
+\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
+This macro expands to \code{_save = PyEval_SaveThread();} i.e. it is
+equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
+and variable declaration. It is a no-op when thread support is
+disabled at compile time.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
-This instance of \code{PyTypeObject} represents the Python complex
-number type.
-\end{cvardesc}
+All of the following functions are only available when thread support
+is enabled at compile time, and must be called only when the
+interpreter lock has been created. They are all new in 1.5a3.
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-returns true if it's argument is a \code{PyComplexObject}
+\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
+Create a new interpreter state object. The interpreter lock must be
+held.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
-
+\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}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
-
+\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
+Destroy an interpreter state object. The interpreter lock need not be
+held. The interpreter state must have been reset with a previous
+call to \code{PyInterpreterState_Clear()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
-
+\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
+Create a new thread state object belonging to the given interpreter
+object. The interpreter lock must be held.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
-
+\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}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
-
+\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
+Destroy a thread state object. The interpreter lock need not be
+held. The thread state must have been reset with a previous
+call to \code{PyThreadState_Clear()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
-
+\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}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
-
+\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 *}{PyComplex_FromDoubles}{double real, double imag}
-
-\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
+\section{Defining New Object Types}
-\end{cfuncdesc}
+XXX To be done:
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
+PyObject, PyVarObject
-\end{cfuncdesc}
+PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
+Typedefs:
+unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
+getreadbufferproc, getwritebufferproc, getsegcountproc,
+destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
+setattrofunc, cmpfunc, reprfunc, hashfunc
-\end{cfuncdesc}
+PyNumberMethods
+PySequenceMethods
+PyMappingMethods
-\section{Other Objects}
+PyBufferProcs
-\subsection{File Objects}
+PyTypeObject
-\begin{ctypedesc}{PyFileObject}
-This subtype of \code{PyObject} represents a Python file object.
-\end{ctypedesc}
+DL_IMPORT
-\begin{cvardesc}{PyTypeObject}{PyFile_Type}
-This instance of \code{PyTypeObject} represents the Python file type.
-\end{cvardesc}
+PyType_Type
-\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
-returns true if it's argument is a \code{PyFileObject}
-\end{cfuncdesc}
+Py*_Check
-\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
-creates a new PyFileObject pointing to the file
-specified in \code{name} with the mode specified in \code{mode}
-\end{cfuncdesc}
+Py_None, _Py_NoneStruct
-\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
- char *name, char *mode, int (*close})
-creates a new PyFileObject from the already-open \code{fp}.
-The function \code{close} will be called when the file should be closed.
-\end{cfuncdesc}
+_PyObject_New, _PyObject_NewVar
-\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
-returns the file object associated with \code{p} as a \code{FILE *}
-\end{cfuncdesc}
+PyObject_NEW, PyObject_NEW_VAR
-\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
-undocumented as yet
-\end{cfuncdesc}
-\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
-returns the name of the file specified by \code{p} as a
-PyStringObject
-\end{cfuncdesc}
+\chapter{Defining New Object Types}
-\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
-on systems with \code{setvbuf} only
+\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
-same as the file object method \code{softspace}
+\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
-writes object \code{obj} to file object \code{p}
+\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
-writes string \code{s} to file object \code{p}
+\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
\end{cfuncdesc}
-\subsection{CObjects}
+\chapter{Debugging}
-XXX
+XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
\input{api.ind} % Index -- must be last
a later chapter.
-\chapter{Basic Utilities}
+\chapter{The Very High Level Layer}
-XXX These utilities should be moved to some other section...
+The functions in this chapter will let you execute Python source code
+given in a file or a buffer, but they will not let you interact in a
+more detailed way with the interpreter.
-\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
-Print a fatal error message and kill the process. No cleanup is
-performed. This function should only be invoked when a condition is
-detected that would make it dangerous to continue using the Python
-interpreter; e.g., when the object administration appears to be
-corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is
-called which will attempt to produce a \file{core} file.
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_Exit}{int status}
-Exit the current process. This calls \code{Py_Finalize()} and then
-calls the standard \C{} library function \code{exit(\var{status})}.
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
-Register a cleanup function to be called by \cfunction{Py_Finalize()}.
-The cleanup function will be called with no arguments and should
-return no value. At most 32 cleanup functions can be registered.
-When the registration is successful, \cfunction{Py_AtExit()} returns
-\code{0}; on failure, it returns \code{-1}. The cleanup function
-registered last is called first. Each cleanup function will be called
-at most once. Since Python's internal finallization will have
-completed before the cleanup function, no Python APIs should be called
-by \var{func}.
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
\end{cfuncdesc}
\end{cfuncdesc}
-\section{Importing modules}
+\section{Process Control}
+
+\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
+Print a fatal error message and kill the process. No cleanup is
+performed. This function should only be invoked when a condition is
+detected that would make it dangerous to continue using the Python
+interpreter; e.g., when the object administration appears to be
+corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is
+called which will attempt to produce a \file{core} file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Exit}{int status}
+Exit the current process. This calls \code{Py_Finalize()} and then
+calls the standard \C{} library function \code{exit(\var{status})}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
+Register a cleanup function to be called by \cfunction{Py_Finalize()}.
+The cleanup function will be called with no arguments and should
+return no value. At most 32 cleanup functions can be registered.
+When the registration is successful, \cfunction{Py_AtExit()} returns
+\code{0}; on failure, it returns \code{-1}. The cleanup function
+registered last is called first. Each cleanup function will be called
+at most once. Since Python's internal finallization will have
+completed before the cleanup function, no Python APIs should be called
+by \var{func}.
+\end{cfuncdesc}
+
+
+\section{Importing Modules}
\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name}
This is a simplified interface to \code{PyImport_ImportModuleEx}
\end{cvardesc}
-\chapter{Debugging}
-
-XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
-
-
-\chapter{The Very High Level Layer}
-
-The functions in this chapter will let you execute Python source code
-given in a file or a buffer, but they will not let you interact in a
-more detailed way with the interpreter.
-
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
-\end{cfuncdesc}
-
-
\chapter{Abstract Objects Layer}
The functions in this chapter interact with Python objects regardless
if you receive an object from a Python program and you are not sure
that it has the right type, you must perform a type check first;
e.g. to check that an object is a dictionary, use
-\code{PyDict_Check()}.
+\cfunction{PyDict_Check()}. The chapter is structured like the
+``family tree'' of Python object types.
-\chapter{Defining New Object Types}
+\section{Fundamental Objects}
+
+This section describes Python type objects and the singleton object
+\code{None}.
+
+
+\subsection{Type Objects}
+
+\begin{ctypedesc}{PyTypeObject}
+
+\end{ctypedesc}
+
+\begin{cvardesc}{PyObject *}{PyType_Type}
+
+\end{cvardesc}
+
+
+\subsection{The None Object}
+
+\begin{cvardesc}{PyObject *}{Py_None}
+XXX macro
+\end{cvardesc}
+
+
+\section{Sequence Objects}
+
+Generic operations on sequence objects were discussed in the previous
+chapter; this section deals with the specific kinds of sequence
+objects that are intrinsic to the Python language.
+
+
+\subsection{String Objects}
+
+\begin{ctypedesc}{PyStringObject}
+This subtype of \code{PyObject} represents a Python string object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyString_Type}
+This instance of \code{PyTypeObject} represents the Python string type.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
+\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
+\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
+
\end{cfuncdesc}
-\chapter{Initialization, Finalization, and Threads}
+\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-\begin{cfuncdesc}{void}{Py_Initialize}{}
-Initialize the Python interpreter. In an application embedding
-Python, this should be called before using any other Python/C API
-functions; with the exception of \code{Py_SetProgramName()},
-\code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
-\code{PyEval_AcquireLock()}. This initializes the table of loaded
-modules (\code{sys.modules}), and creates the fundamental modules
-\code{__builtin__}, \code{__main__} and \code{sys}. It also
-initializes the module search path (\code{sys.path}). It does not set
-\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
-when called for a second time (without calling \code{Py_Finalize()}
-first). There is no return value; it is a fatal error if the
-initialization fails.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{Py_IsInitialized}{}
-\strong{(NEW in 1.5a4!)}
-Return true (nonzero) when the Python interpreter has been
-initialized, false (zero) if not. After \code{Py_Finalize()} is
-called, this returns false until \code{Py_Initialize()} is called
-again.
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_Finalize}{}
-\strong{(NEW in 1.5a3!)}
-Undo all initializations made by \code{Py_Initialize()} and subsequent
-use of Python/C API functions, and destroy all sub-interpreters (see
-\code{Py_NewInterpreter()} below) that were created and not yet
-destroyed since the last call to \code{Py_Initialize()}. Ideally,
-this frees all memory allocated by the Python interpreter. This is a
-no-op when called for a second time (without calling
-\code{Py_Initialize()} again first). There is no return value; errors
-during finalization are ignored.
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
-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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
-\emph{Bugs and caveats:} The destruction of modules and objects in
-modules is done in random order; this may cause destructors
-(\code{__del__} methods) to fail when they depend on other objects
-(even functions) or modules. Dynamically loaded extension modules
-loaded by Python are not unloaded. Small amounts of memory allocated
-by the Python interpreter may not be freed (if you find a leak, please
-report it). Memory tied up in circular references between objects is
-not freed. Some memory allocated by extension modules may not be
-freed. Some extension may not work properly if their initialization
-routine is called more than once; this can happen if an applcation
-calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
-\strong{(NEW in 1.5a3!)}
-Create a new sub-interpreter. This is an (almost) totally separate
-environment for the execution of Python code. In particular, the new
-interpreter has separate, independent versions of all imported
-modules, including the fundamental modules \code{__builtin__},
-\code{__main__} and \code{sys}. The table of loaded modules
-(\code{sys.modules}) and the module search path (\code{sys.path}) are
-also separate. The new environment has no \code{sys.argv} variable.
-It has new standard I/O stream file objects \code{sys.stdin},
-\code{sys.stdout} and \code{sys.stderr} (however these refer to the
-same underlying \code{FILE} structures in the \C{} library).
+\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
-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.)
+\end{cfuncdesc}
-Extension modules are shared between (sub-)interpreters as follows:
-the first time a particular extension is imported, it is initialized
-normally, and a (shallow) copy of its module's dictionary is
-squirreled away. When the same extension is imported by another
-(sub-)interpreter, a new module is initialized and filled with the
-contents of this copy; the extension's \code{init} function is not
-called. Note that this is different from what happens when as
-extension is imported after the interpreter has been completely
-re-initialized by calling \code{Py_Finalize()} and
-\code{Py_Initialize()}; in that case, the extension's \code{init}
-function \emph{is} called again.
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
-\emph{Bugs and caveats:} Because sub-interpreters (and the main
-interpreter) are part of the same process, the insulation between them
-isn't perfect -- for example, using low-level file operations like
-\code{os.close()} they can (accidentally or maliciously) affect each
-other's open files. Because of the way extensions are shared between
-(sub-)interpreters, some extensions may not work properly; this is
-especially likely when the extension makes use of (static) global
-variables, or when the extension manipulates its module's dictionary
-after its initialization. It is possible to insert objects created in
-one sub-interpreter into a namespace of another sub-interpreter; this
-should be done with great care to avoid sharing user-defined
-functions, methods, instances or classes between sub-interpreters,
-since import operations executed by such objects may affect the
-wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
-a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Destroy the (sub-)interpreter represented by the given thread state.
-The given thread state must be the current thread state. See the
-discussion of thread states below. When the call returns, the current
-thread state is \NULL{}. All thread states associated with this
-interpreted are destroyed. (The global interpreter lock must be held
-before calling this function and is still held when it returns.)
-\code{Py_Finalize()} will destroy all sub-interpreters that haven't
-been explicitly destroyed at that point.
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
-\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
-\strong{(NEW in 1.5a3!)}
-This function should be called before \code{Py_Initialize()} is called
-for the first time, if it is called at all. It tells the interpreter
-the value of the \code{argv[0]} argument to the \code{main()} function
-of the program. This is used by \code{Py_GetPath()} and some other
-functions below to find the Python run-time libraries relative to the
-interpreter executable. The default value is \code{"python"}. The
-argument should point to a zero-terminated character string in static
-storage whose contents will not change for the duration of the
-program's execution. No code in the Python interpreter will change
-the contents of this storage.
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
-Return the program name set with \code{Py_SetProgramName()}, or the
-default. The returned string points into static storage; the caller
-should not modify its value.
+\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
-Return the ``prefix'' for installed platform-independent files. This
-is derived through a number of complicated rules from the program name
-set with \code{Py_SetProgramName()} and some environment variables;
-for example, if the program name is \code{"/usr/local/bin/python"},
-the prefix is \code{"/usr/local"}. The returned string points into
-static storage; the caller should not modify its value. This
-corresponds to the \code{prefix} variable in the top-level
-\code{Makefile} and the \code{--prefix} argument to the
-\code{configure} script at build time. The value is available to
-Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
-also the next function.
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
+
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
-Return the ``exec-prefix'' for installed platform-\emph{de}pendent
-files. This is derived through a number of complicated rules from the
-program name set with \code{Py_SetProgramName()} and some environment
-variables; for example, if the program name is
-\code{"/usr/local/bin/python"}, the exec-prefix is
-\code{"/usr/local"}. The returned string points into static storage;
-the caller should not modify its value. This corresponds to the
-\code{exec_prefix} variable in the top-level \code{Makefile} and the
-\code{--exec_prefix} argument to the \code{configure} script at build
-time. The value is available to Python code as
-\code{sys.exec_prefix}. It is only useful on \UNIX{}.
-Background: The exec-prefix differs from the prefix when platform
-dependent files (such as executables and shared libraries) are
-installed in a different directory tree. In a typical installation,
-platform dependent files may be installed in the
-\code{"/usr/local/plat"} subtree while platform independent may be
-installed in \code{"/usr/local"}.
+\subsection{Tuple Objects}
-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!).
+\begin{ctypedesc}{PyTupleObject}
+This subtype of \code{PyObject} represents a Python tuple object.
+\end{ctypedesc}
-System administrators will know how to configure the \code{mount} or
-\code{automount} programs to share \code{"/usr/local"} between platforms
-while having \code{"/usr/local/plat"} be a different filesystem for each
-platform.
-\end{cfuncdesc}
+\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
+This instance of \code{PyTypeObject} represents the Python tuple type.
+\end{cvardesc}
-\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
-\strong{(NEW in 1.5a3!)}
-Return the full program name of the Python executable; this is
-computed as a side-effect of deriving the default module search path
-from the program name (set by \code{Py_SetProgramName()} above). The
-returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as
-\code{sys.executable}.
+\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
+Return true if the argument is a tuple object.
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{Py_GetPath}{}
-Return the default module search path; this is computed from the
-program name (set by \code{Py_SetProgramName()} above) and some
-environment variables. The returned string consists of a series of
-directory names separated by a platform dependent delimiter character.
-The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
-DOS/Windows, and \code{'\\n'} (the ASCII newline character) on
-Macintosh. The returned string points into static storage; the caller
-should not modify its value. The value is available to Python code
-as the list \code{sys.path}, which may be modified to change the
-future search path for loaded modules.
+\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
+Return a new tuple object of size \code{s}
+\end{cfuncdesc}
-% XXX should give the exact rules
+\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
+akes a pointer to a tuple object, and returns the size
+of that tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
-Return the version of this Python interpreter. This is a string that
-looks something like
+\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
+returns the object at position \code{pos} in the tuple pointed
+to by \code{p}.
+\end{cfuncdesc}
-\begin{verbatim}
-"1.5a3 (#67, Aug 1 1997, 22:34:28) [GCC 2.7.2.2]"
-\end{verbatim}
+\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
+does the same, but does no checking of it's
+arguments.
+\end{cfuncdesc}
-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}.
+\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
+ int low,
+ int high}
+takes a slice of the tuple pointed to by \code{p} from
+\code{low} to \code{high} and returns it as a new tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{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}.
+\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
+ int pos,
+ PyObject *o}
+inserts a reference to object \code{o} at position \code{pos} of
+the tuple pointed to by \code{p}. It returns 0 on success.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
-Return the official copyright string for the current Python version,
-for example
+\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
+ int pos,
+ PyObject *o}
-\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
+does the same, but does no error checking, and
+should \emph{only} be used to fill in brand new tuples.
+\end{cfuncdesc}
-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}.
+\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
+ int new,
+ int last_is_sticky}
+can be used to resize a tuple. Because tuples are
+\emph{supposed} to be immutable, this should only be used if there is only
+one module referencing the object. Do \emph{not} use this if the tuple may
+already be known to some other part of the code. \code{last_is_sticky} is
+a flag - if set, the tuple will grow or shrink at the front, otherwise
+it will grow or shrink at the end. Think of this as destroying the old
+tuple and creating a new one, only more efficiently.
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
-Return an indication of the compiler used to build the current Python
-version, in square brackets, for example
-\code{"[GCC 2.7.2.2]"}
+\subsection{List Objects}
-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}.
+\begin{ctypedesc}{PyListObject}
+This subtype of \code{PyObject} represents a Python list object.
+\end{ctypedesc}
+
+\begin{cvardesc}{PyTypeObject}{PyList_Type}
+This instance of \code{PyTypeObject} represents the Python list type.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
+returns true if it's argument is a \code{PyListObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
-Return information about the sequence number and build date and time
-of the current Python interpreter instance, for example
+\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
-\begin{verbatim}
-"#67, Aug 1 1997, 22:34:28"
-\end{verbatim}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
-The returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as part of
-the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
-% XXX
+\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+
\end{cfuncdesc}
-% XXX Other PySys thingies (doesn't really belong in this chapter)
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
-\section{Thread State and the Global Interpreter Lock}
+\end{cfuncdesc}
-The Python interpreter is not fully thread safe. In order to support
-multi-threaded Python programs, there's a global lock that must be
-held by the current thread before it can safely access Python objects.
-Without the lock, even the simplest operations could cause problems in
-a multi-threaded proram: for example, when two threads simultaneously
-increment the reference count of the same object, the reference count
-could end up being incremented only once instead of twice.
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
-Therefore, the rule exists that only the thread that has acquired the
-global interpreter lock may operate on Python objects or call Python/C
-API functions. In order to support multi-threaded Python programs,
-the interpreter regularly release and reacquires the lock -- by
-default, every ten bytecode instructions (this can be changed with
-\code{sys.setcheckinterval()}). The lock is also released and
-reacquired around potentially blocking I/O operations like reading or
-writing a file, so that other threads can run while the thread that
-requests the I/O is waiting for the I/O operation to complete.
+\end{cfuncdesc}
-The Python interpreter needs to keep some bookkeeping information
-separate per thread -- for this it uses a data structure called
-PyThreadState. This is new in Python 1.5; in earlier versions, such
-state was stored in global variables, and switching threads could
-cause problems. In particular, exception handling is now thread safe,
-when the application uses \code{sys.exc_info()} to access the exception
-last raised in the current thread.
-
-There's one global variable left, however: the pointer to the current
-PyThreadState structure. While most thread packages have a way to
-store ``per-thread global data'', Python's internal platform
-independent thread abstraction doesn't support this (yet). Therefore,
-the current thread state must be manipulated explicitly.
-
-This is easy enough in most cases. Most code manipulating the global
-interpreter lock has the following simple structure:
-
-\begin{verbatim}
-Save the thread state in a local variable.
-Release the interpreter lock.
-...Do some blocking I/O operation...
-Reacquire the interpreter lock.
-Restore the thread state from the local variable.
-\end{verbatim}
-
-This is so common that a pair of macros exists to simplify it:
-
-\begin{verbatim}
-Py_BEGIN_ALLOW_THREADS
-...Do some blocking I/O operation...
-Py_END_ALLOW_THREADS
-\end{verbatim}
-
-The BEGIN macro opens a new block and declares a hidden local
-variable; the END macro closes the block. Another advantage of using
-these two macros is that when Python is compiled without thread
-support, they are defined empty, thus saving the thread state and lock
-manipulations.
-
-When thread support is enabled, the block above expands to the
-following code:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyEval_SaveThread();
- ...Do some blocking I/O operation...
- PyEval_RestoreThread(_save);
-}
-\end{verbatim}
-
-Using even lower level primitives, we can get roughly the same effect
-as follows:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyThreadState_Swap(NULL);
- PyEval_ReleaseLock();
- ...Do some blocking I/O operation...
- PyEval_AcquireLock();
- PyThreadState_Swap(_save);
-}
-\end{verbatim}
-
-There are some subtle differences; in particular,
-\code{PyEval_RestoreThread()} saves and restores the value of the
-global variable \code{errno}, since the lock manipulation does not
-guarantee that \code{errno} is left alone. Also, when thread support
-is disabled, \code{PyEval_SaveThread()} and
-\code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
-\code{PyEval_ReleaseLock()} and \code{PyEval_AcquireLock()} are not
-available. (This is done so that dynamically loaded extensions
-compiled with thread support enabled can be loaded by an interpreter
-that was compiled with disabled thread support.)
-
-The global interpreter lock is used to protect the pointer to the
-current thread state. When releasing the lock and saving the thread
-state, the current thread state pointer must be retrieved before the
-lock is released (since another thread could immediately acquire the
-lock and store its own thread state in the global variable).
-Reversely, when acquiring the lock and restoring the thread state, the
-lock must be acquired before storing the thread state pointer.
+\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
-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.
+\end{cfuncdesc}
-When creating a thread data structure, you need to provide an
-interpreter state data structure. The interpreter state data
-structure hold global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}). Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \code{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
+\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
-XXX More?
+\end{cfuncdesc}
-\begin{ctypedesc}{PyInterpreterState}
-\strong{(NEW in 1.5a3!)}
-This data structure represents the state shared by a number of
-cooperating threads. Threads belonging to the same interpreter
-share their module administration and a few other internal items.
-There are no public members in this structure.
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
-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}
+\end{cfuncdesc}
-\begin{ctypedesc}{PyThreadState}
-\strong{(NEW in 1.5a3!)}
-This data structure represents the state of a single thread. The only
-public data member is \code{PyInterpreterState *interp}, which points
-to this thread's interpreter state.
-\end{ctypedesc}
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
-\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
-Initialize and acquire the global interpreter lock. It should be
-called in the main thread before creating a second thread or engaging
-in any other thread operations such as \code{PyEval_ReleaseLock()} or
-\code{PyEval_ReleaseThread(tstate)}. It is not needed before
-calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
+\end{cfuncdesc}
-This is a no-op when called for a second time. It is safe to call
-this function before calling \code{Py_Initialize()}.
+\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
-When only the main thread exists, no lock operations are needed. This
-is a common situation (most Python programs do not use threads), and
-the lock operations slow the interpreter down a bit. Therefore, the
-lock is not created initially. This situation is equivalent to having
-acquired the lock: when there is only a single thread, all object
-accesses are safe. Therefore, when this function initializes the
-lock, it also acquires it. Before the Python \code{thread} module
-creates a new thread, knowing that either it has the lock or the lock
-hasn't been created yet, it calls \code{PyEval_InitThreads()}. When
-this call returns, it is guaranteed that the lock has been created and
-that it has acquired it.
+\end{cfuncdesc}
-It is \strong{not} safe to call this function when it is unknown which
-thread (if any) currently has the global interpreter lock.
+\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
-This function is not available when thread support is disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
-\strong{(NEW in 1.5a3!)}
-Acquire the global interpreter lock. The lock must have been created
-earlier. If this thread already has the lock, a deadlock ensues.
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
-\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
-\strong{(NEW in 1.5a3!)}
-Release the global interpreter lock. The lock must have been created
-earlier. This function is not available when thread support is
-disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Acquire the global interpreter lock and then set the current thread
-state to \var{tstate}, which should not be \NULL{}. The lock must
-have been created earlier. If this thread already has the lock,
-deadlock ensues. This function is not available when thread support
-is disabled at
-compile time.
-\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
-\strong{(NEW in 1.5a3!)}
-Reset the current thread state to \NULL{} and release the global
-interpreter lock. The lock must have been created earlier and must be
-held by the current thread. The \var{tstate} argument, which must not
-be \NULL{}, is only used to check that it represents the current
-thread state -- if it isn't, a fatal error is reported. This function
-is not available when thread support is disabled at
-compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
-\strong{(Different return type in 1.5a3!)}
-Release the interpreter lock (if it has been created and thread
-support is enabled) and reset the thread state to \NULL{},
-returning the previous thread state (which is not \NULL{}). If
-the lock has been created, the current thread must have acquired it.
-(This function is available even when thread support is disabled at
-compile time.)
-\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
-\strong{(Different argument type in 1.5a3!)}
-Acquire the interpreter lock (if it has been created and thread
-support is enabled) and set the thread state to \var{tstate}, which
-must not be \NULL{}. If the lock has been created, the current
-thread must not have acquired it, otherwise deadlock ensues. (This
-function is available even when thread support is disabled at compile
-time.)
-\end{cfuncdesc}
+\section{Mapping Objects}
-% XXX These aren't really C types, but the ctypedesc macro is the simplest!
-\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
-This macro expands to
-\code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
-Note that it contains an opening brace; it must be matched with a
-following \code{Py_END_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
+\subsection{Dictionary Objects}
-\begin{ctypedesc}{Py_END_ALLOW_THREADS}
-This macro expands to
-\code{PyEval_RestoreThread(_save); \} }.
-Note that it contains a closing brace; it must be matched with an
-earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
+\begin{ctypedesc}{PyDictObject}
+This subtype of \code{PyObject} represents a Python dictionary object.
\end{ctypedesc}
-\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
-This macro expands to \code{PyEval_RestoreThread(_save);} i.e. it
-is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
-brace. It is a no-op when thread support is disabled at compile
-time.
-\end{ctypedesc}
+\begin{cvardesc}{PyTypeObject}{PyDict_Type}
+This instance of \code{PyTypeObject} represents the Python dictionary type.
+\end{cvardesc}
-\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
-This macro expands to \code{_save = PyEval_SaveThread();} i.e. it is
-equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
-and variable declaration. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
+\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
+returns true if it's argument is a PyDictObject
+\end{cfuncdesc}
-All of the following functions are only available when thread support
-is enabled at compile time, and must be called only when the
-interpreter lock has been created. They are all new in 1.5a3.
+\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
+returns a new empty dictionary.
+\end{cfuncdesc}
-\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
-Create a new interpreter state object. The interpreter lock must be
-held.
+\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
+empties an existing dictionary and deletes it.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
-Reset all information in an interpreter state object. The interpreter
-lock must be held.
+\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
+ PyObject *key,
+ PyObject *val}
+inserts \code{value} into the dictionary with a key of
+\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
+be hashable.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
-Destroy an interpreter state object. The interpreter lock need not be
-held. The interpreter state must have been reset with a previous
-call to \code{PyInterpreterState_Clear()}.
+\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
+ char *key,
+ PyObject *val}
+inserts \code{value} into the dictionary using \code{key}
+as a key. \code{key} should be a char *
\end{cfuncdesc}
-\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
-Create a new thread state object belonging to the given interpreter
-object. The interpreter lock must be held.
+\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
+removes the entry in dictionary \code{p} with key \code{key}.
+\code{key} is a PyObject.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
-Reset all information in a thread state object. The interpreter lock
-must be held.
+\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
+removes the entry in dictionary \code{p} which has a key
+specified by the \code{char *}\code{key}.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
-Destroy a thread state object. The interpreter lock need not be
-held. The thread state must have been reset with a previous
-call to \code{PyThreadState_Clear()}.
+\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
+returns the object from dictionary \code{p} which has a key
+\code{key}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
+does the same, but \code{key} is specified as a
+\code{char *}, rather than a \code{PyObject *}.
\end{cfuncdesc}
-\begin{cfuncdesc}{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{}).
+\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
+returns a PyListObject containing all the items
+from the dictionary, as in the mapping method \code{items()} (see the Reference
+Guide)
\end{cfuncdesc}
-\begin{cfuncdesc}{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.
+\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
+returns a PyListObject containing all the keys
+from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
\end{cfuncdesc}
+\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
+returns a PyListObject containing all the values
+from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
+\end{cfuncdesc}
-\section{Defining New Object Types}
+\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
+returns the number of items in the dictionary.
+\end{cfuncdesc}
-XXX To be done:
+\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
+ int ppos,
+ PyObject **pkey,
+ PyObject **pvalue}
-PyObject, PyVarObject
+\end{cfuncdesc}
-PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-Typedefs:
-unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
-intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
-getreadbufferproc, getwritebufferproc, getsegcountproc,
-destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
-setattrofunc, cmpfunc, reprfunc, hashfunc
+\section{Numeric Objects}
-PyNumberMethods
+\subsection{Plain Integer Objects}
-PySequenceMethods
+\begin{ctypedesc}{PyIntObject}
+This subtype of \code{PyObject} represents a Python integer object.
+\end{ctypedesc}
-PyMappingMethods
+\begin{cvardesc}{PyTypeObject}{PyInt_Type}
+This instance of \code{PyTypeObject} represents the Python plain
+integer type.
+\end{cvardesc}
-PyBufferProcs
+\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
-PyTypeObject
+\end{cfuncdesc}
-DL_IMPORT
+\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
+creates a new integer object with a value of \code{ival}.
-PyType_Type
+The current implementation keeps an array of integer objects for all
+integers between -1 and 100, when you create an int in that range you
+actually just get back a reference to the existing object. So it should
+be possible to change the value of 1. I suspect the behaviour of python
+in this case is undefined. :-)
+\end{cfuncdesc}
-Py*_Check
+\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
+returns the value of the object \code{io}.
+\end{cfuncdesc}
-Py_None, _Py_NoneStruct
+\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
+will first attempt to cast the object to a PyIntObject, if
+it is not already one, and the return it's value.
+\end{cfuncdesc}
-_PyObject_New, _PyObject_NewVar
+\begin{cfuncdesc}{long}{PyInt_GetMax}{}
+returns the systems idea of the largest int it can handle
+(LONG_MAX, as defined in the system header files)
+\end{cfuncdesc}
-PyObject_NEW, PyObject_NEW_VAR
+\subsection{Long Integer Objects}
-\chapter{Specific Data Types}
+\begin{ctypedesc}{PyLongObject}
+This subtype of \code{PyObject} represents a Python long integer object.
+\end{ctypedesc}
-This chapter describes the functions that deal with specific types of
-Python objects. It is structured like the ``family tree'' of Python
-object types.
+\begin{cvardesc}{PyTypeObject}{PyLong_Type}
+This instance of \code{PyTypeObject} represents the Python long integer type.
+\end{cvardesc}
+\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
+returns true if it's argument is a \code{PyLongObject}
+\end{cfuncdesc}
-\section{Fundamental Objects}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
-This section describes Python type objects and the singleton object
-\code{None}.
+\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
-\subsection{Type Objects}
+\end{cfuncdesc}
-\begin{ctypedesc}{PyTypeObject}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
-\end{ctypedesc}
+\end{cfuncdesc}
-\begin{cvardesc}{PyObject *}{PyType_Type}
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
-\end{cvardesc}
+\end{cfuncdesc}
+\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
-\subsection{The None Object}
+\end{cfuncdesc}
-\begin{cvardesc}{PyObject *}{Py_None}
-XXX macro
-\end{cvardesc}
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
+\end{cfuncdesc}
-\section{Sequence Objects}
+\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
-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.
+\end{cfuncdesc}
-\subsection{String Objects}
+\subsection{Floating Point Objects}
-\begin{ctypedesc}{PyStringObject}
-This subtype of \code{PyObject} represents a Python string object.
+\begin{ctypedesc}{PyFloatObject}
+This subtype of \code{PyObject} represents a Python floating point object.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-This instance of \code{PyTypeObject} represents the Python string type.
+\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
+This instance of \code{PyTypeObject} represents the Python floating
+point type.
\end{cvardesc}
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-
+\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
+returns true if it's argument is a \code{PyFloatObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-\end{cfuncdesc}
+\subsection{Complex Number Objects}
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
+\begin{ctypedesc}{Py_complex}
+typedef struct {
+ double real;
+ double imag;
+}
+\end{ctypedesc}
-\end{cfuncdesc}
+\begin{ctypedesc}{PyComplexObject}
+This subtype of \code{PyObject} represents a Python complex number object.
+\end{ctypedesc}
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
+\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
+This instance of \code{PyTypeObject} represents the Python complex
+number type.
+\end{cvardesc}
+\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
+returns true if it's argument is a \code{PyComplexObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
+\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
+\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
+\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
-\subsection{Tuple Objects}
-
-\begin{ctypedesc}{PyTupleObject}
-This subtype of \code{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
-This instance of \code{PyTypeObject} represents the Python tuple type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
-Return true if the argument is a tuple object.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
-Return a new tuple object of size \code{s}
-\end{cfuncdesc}
+\begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
-akes a pointer to a tuple object, and returns the size
-of that tuple.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
-returns the object at position \code{pos} in the tuple pointed
-to by \code{p}.
-\end{cfuncdesc}
+\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-\begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
-does the same, but does no checking of it's
-arguments.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
- int low,
- int high}
-takes a slice of the tuple pointed to by \code{p} from
-\code{low} to \code{high} and returns it as a new tuple.
-\end{cfuncdesc}
+\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
- int pos,
- PyObject *o}
-inserts a reference to object \code{o} at position \code{pos} of
-the tuple pointed to by \code{p}. It returns 0 on success.
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
- int pos,
- PyObject *o}
+\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-does the same, but does no error checking, and
-should \emph{only} be used to fill in brand new tuples.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
- int new,
- int last_is_sticky}
-can be used to resize a tuple. Because tuples are
-\emph{supposed} to be immutable, this should only be used if there is only
-one module referencing the object. Do \emph{not} use this if the tuple may
-already be known to some other part of the code. \code{last_is_sticky} is
-a flag - if set, the tuple will grow or shrink at the front, otherwise
-it will grow or shrink at the end. Think of this as destroying the old
-tuple and creating a new one, only more efficiently.
-\end{cfuncdesc}
-\subsection{List Objects}
+\section{Other Objects}
-\begin{ctypedesc}{PyListObject}
-This subtype of \code{PyObject} represents a Python list object.
+\subsection{File Objects}
+
+\begin{ctypedesc}{PyFileObject}
+This subtype of \code{PyObject} represents a Python file object.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
-This instance of \code{PyTypeObject} represents the Python list type.
+\begin{cvardesc}{PyTypeObject}{PyFile_Type}
+This instance of \code{PyTypeObject} represents the Python file type.
\end{cvardesc}
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-returns true if it's argument is a \code{PyListObject}
+\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
+returns true if it's argument is a \code{PyFileObject}
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
+\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
+creates a new PyFileObject pointing to the file
+specified in \code{name} with the mode specified in \code{mode}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
+ char *name, char *mode, int (*close})
+creates a new PyFileObject from the already-open \code{fp}.
+The function \code{close} will be called when the file should be closed.
+\end{cfuncdesc}
+\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
+returns the file object associated with \code{p} as a \code{FILE *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
+\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
+undocumented as yet
+\end{cfuncdesc}
+\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
+returns the name of the file specified by \code{p} as a
+PyStringObject
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
+on systems with \code{setvbuf} only
+\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
+same as the file object method \code{softspace}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
+writes object \code{obj} to file object \code{p}
+\end{cfuncdesc}
+\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
+writes string \code{s} to file object \code{p}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
-\end{cfuncdesc}
+\subsection{CObjects}
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
+XXX
-\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
+\chapter{Initialization, Finalization, and Threads}
+\begin{cfuncdesc}{void}{Py_Initialize}{}
+Initialize the Python interpreter. In an application embedding
+Python, this should be called before using any other Python/C API
+functions; with the exception of \code{Py_SetProgramName()},
+\code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
+\code{PyEval_AcquireLock()}. This initializes the table of loaded
+modules (\code{sys.modules}), and creates the fundamental modules
+\code{__builtin__}, \code{__main__} and \code{sys}. It also
+initializes the module search path (\code{sys.path}). It does not set
+\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
+when called for a second time (without calling \code{Py_Finalize()}
+first). There is no return value; it is a fatal error if the
+initialization fails.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
-
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+\strong{(NEW in 1.5a4!)}
+Return true (nonzero) when the Python interpreter has been
+initialized, false (zero) if not. After \code{Py_Finalize()} is
+called, this returns false until \code{Py_Initialize()} is called
+again.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
+\begin{cfuncdesc}{void}{Py_Finalize}{}
+\strong{(NEW in 1.5a3!)}
+Undo all initializations made by \code{Py_Initialize()} and subsequent
+use of Python/C API functions, and destroy all sub-interpreters (see
+\code{Py_NewInterpreter()} below) that were created and not yet
+destroyed since the last call to \code{Py_Initialize()}. Ideally,
+this frees all memory allocated by the Python interpreter. This is a
+no-op when called for a second time (without calling
+\code{Py_Initialize()} again first). There is no return value; errors
+during finalization are ignored.
+
+This function is provided for a number of reasons. An embedding
+application might want to restart Python without having to restart the
+application itself. An application that has loaded the Python
+interpreter from a dynamically loadable library (or DLL) might want to
+free all memory allocated by Python before unloading the DLL. During a
+hunt for memory leaks in an application a developer might want to free
+all memory allocated by Python before exiting from the application.
+\emph{Bugs and caveats:} The destruction of modules and objects in
+modules is done in random order; this may cause destructors
+(\code{__del__} methods) to fail when they depend on other objects
+(even functions) or modules. Dynamically loaded extension modules
+loaded by Python are not unloaded. Small amounts of memory allocated
+by the Python interpreter may not be freed (if you find a leak, please
+report it). Memory tied up in circular references between objects is
+not freed. Some memory allocated by extension modules may not be
+freed. Some extension may not work properly if their initialization
+routine is called more than once; this can happen if an applcation
+calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
+\begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
+\strong{(NEW in 1.5a3!)}
+Create a new sub-interpreter. This is an (almost) totally separate
+environment for the execution of Python code. In particular, the new
+interpreter has separate, independent versions of all imported
+modules, including the fundamental modules \code{__builtin__},
+\code{__main__} and \code{sys}. The table of loaded modules
+(\code{sys.modules}) and the module search path (\code{sys.path}) are
+also separate. The new environment has no \code{sys.argv} variable.
+It has new standard I/O stream file objects \code{sys.stdin},
+\code{sys.stdout} and \code{sys.stderr} (however these refer to the
+same underlying \code{FILE} structures in the \C{} library).
-\end{cfuncdesc}
+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.)
-\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
+Extension modules are shared between (sub-)interpreters as follows:
+the first time a particular extension is imported, it is initialized
+normally, and a (shallow) copy of its module's dictionary is
+squirreled away. When the same extension is imported by another
+(sub-)interpreter, a new module is initialized and filled with the
+contents of this copy; the extension's \code{init} function is not
+called. Note that this is different from what happens when as
+extension is imported after the interpreter has been completely
+re-initialized by calling \code{Py_Finalize()} and
+\code{Py_Initialize()}; in that case, the extension's \code{init}
+function \emph{is} called again.
+\emph{Bugs and caveats:} Because sub-interpreters (and the main
+interpreter) are part of the same process, the insulation between them
+isn't perfect -- for example, using low-level file operations like
+\code{os.close()} they can (accidentally or maliciously) affect each
+other's open files. Because of the way extensions are shared between
+(sub-)interpreters, some extensions may not work properly; this is
+especially likely when the extension makes use of (static) global
+variables, or when the extension manipulates its module's dictionary
+after its initialization. It is possible to insert objects created in
+one sub-interpreter into a namespace of another sub-interpreter; this
+should be done with great care to avoid sharing user-defined
+functions, methods, instances or classes between sub-interpreters,
+since import operations executed by such objects may affect the
+wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
+a hard-to-fix bug that will be addressed in a future release.)
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
-
+\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Destroy the (sub-)interpreter represented by the given thread state.
+The given thread state must be the current thread state. See the
+discussion of thread states below. When the call returns, the current
+thread state is \NULL{}. All thread states associated with this
+interpreted are destroyed. (The global interpreter lock must be held
+before calling this function and is still held when it returns.)
+\code{Py_Finalize()} will destroy all sub-interpreters that haven't
+been explicitly destroyed at that point.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
+\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+\strong{(NEW in 1.5a3!)}
+This function should be called before \code{Py_Initialize()} is called
+for the first time, if it is called at all. It tells the interpreter
+the value of the \code{argv[0]} argument to the \code{main()} function
+of the program. This is used by \code{Py_GetPath()} and some other
+functions below to find the Python run-time libraries relative to the
+interpreter executable. The default value is \code{"python"}. The
+argument should point to a zero-terminated character string in static
+storage whose contents will not change for the duration of the
+program's execution. No code in the Python interpreter will change
+the contents of this storage.
+\end{cfuncdesc}
+\begin{cfuncdesc}{char *}{Py_GetProgramName}{}
+Return the program name set with \code{Py_SetProgramName()}, or the
+default. The returned string points into static storage; the caller
+should not modify its value.
\end{cfuncdesc}
+\begin{cfuncdesc}{char *}{Py_GetPrefix}{}
+Return the ``prefix'' for installed platform-independent files. This
+is derived through a number of complicated rules from the program name
+set with \code{Py_SetProgramName()} and some environment variables;
+for example, if the program name is \code{"/usr/local/bin/python"},
+the prefix is \code{"/usr/local"}. The returned string points into
+static storage; the caller should not modify its value. This
+corresponds to the \code{prefix} variable in the top-level
+\code{Makefile} and the \code{--prefix} argument to the
+\code{configure} script at build time. The value is available to
+Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
+also the next function.
+\end{cfuncdesc}
-\section{Mapping Objects}
+\begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
+Return the ``exec-prefix'' for installed platform-\emph{de}pendent
+files. This is derived through a number of complicated rules from the
+program name set with \code{Py_SetProgramName()} and some environment
+variables; for example, if the program name is
+\code{"/usr/local/bin/python"}, the exec-prefix is
+\code{"/usr/local"}. The returned string points into static storage;
+the caller should not modify its value. This corresponds to the
+\code{exec_prefix} variable in the top-level \code{Makefile} and the
+\code{--exec_prefix} argument to the \code{configure} script at build
+time. The value is available to Python code as
+\code{sys.exec_prefix}. It is only useful on \UNIX{}.
-\subsection{Dictionary Objects}
+Background: The exec-prefix differs from the prefix when platform
+dependent files (such as executables and shared libraries) are
+installed in a different directory tree. In a typical installation,
+platform dependent files may be installed in the
+\code{"/usr/local/plat"} subtree while platform independent may be
+installed in \code{"/usr/local"}.
-\begin{ctypedesc}{PyDictObject}
-This subtype of \code{PyObject} represents a Python dictionary object.
-\end{ctypedesc}
+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!).
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
-This instance of \code{PyTypeObject} represents the Python dictionary type.
-\end{cvardesc}
+System administrators will know how to configure the \code{mount} or
+\code{automount} programs to share \code{"/usr/local"} between platforms
+while having \code{"/usr/local/plat"} be a different filesystem for each
+platform.
+\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-returns true if it's argument is a PyDictObject
+\begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
+\strong{(NEW in 1.5a3!)}
+Return the full program name of the Python executable; this is
+computed as a side-effect of deriving the default module search path
+from the program name (set by \code{Py_SetProgramName()} above). The
+returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as
+\code{sys.executable}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
-returns a new empty dictionary.
+\begin{cfuncdesc}{char *}{Py_GetPath}{}
+Return the default module search path; this is computed from the
+program name (set by \code{Py_SetProgramName()} above) and some
+environment variables. The returned string consists of a series of
+directory names separated by a platform dependent delimiter character.
+The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
+DOS/Windows, and \code{'\\n'} (the ASCII newline character) on
+Macintosh. The returned string points into static storage; the caller
+should not modify its value. The value is available to Python code
+as the list \code{sys.path}, which may be modified to change the
+future search path for loaded modules.
+
+% XXX should give the exact rules
\end{cfuncdesc}
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
-empties an existing dictionary and deletes it.
+\begin{cfuncdesc}{const char *}{Py_GetVersion}{}
+Return the version of this Python interpreter. This is a string that
+looks something like
+
+\begin{verbatim}
+"1.5a3 (#67, Aug 1 1997, 22:34:28) [GCC 2.7.2.2]"
+\end{verbatim}
+
+The first word (up to the first space character) is the current Python
+version; the first three characters are the major and minor version
+separated by a period. The returned string points into static storage;
+the caller should not modify its value. The value is available to
+Python code as the list \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
- PyObject *key,
- PyObject *val}
-inserts \code{value} into the dictionary with a key of
-\code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
-be hashable.
+\begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
+Return the platform identifier for the current platform. On \UNIX{},
+this is formed from the ``official'' name of the operating system,
+converted to lower case, followed by the major revision number; e.g.,
+for Solaris 2.x, which is also known as SunOS 5.x, the value is
+\code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
+is \code{"win"}. The returned string points into static storage;
+the caller should not modify its value. The value is available to
+Python code as \code{sys.platform}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
- char *key,
- PyObject *val}
-inserts \code{value} into the dictionary using \code{key}
-as a key. \code{key} should be a char *
-\end{cfuncdesc}
+\begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
+Return the official copyright string for the current Python version,
+for example
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
-removes the entry in dictionary \code{p} with key \code{key}.
-\code{key} is a PyObject.
-\end{cfuncdesc}
+\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
-removes the entry in dictionary \code{p} which has a key
-specified by the \code{char *}\code{key}.
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as the list
+\code{sys.copyright}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
-returns the object from dictionary \code{p} which has a key
-\code{key}.
-\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{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
-does the same, but \code{key} is specified as a
-\code{char *}, rather than a \code{PyObject *}.
-\end{cfuncdesc}
+\code{"[GCC 2.7.2.2]"}
-\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
-returns a PyListObject containing all the items
-from the dictionary, as in the mapping method \code{items()} (see the Reference
-Guide)
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as part of
+the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
-returns a PyListObject containing all the keys
-from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
-\end{cfuncdesc}
+\begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
+Return information about the sequence number and build date and time
+of the current Python interpreter instance, for example
-\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
-returns a PyListObject containing all the values
-from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
-\end{cfuncdesc}
+\begin{verbatim}
+"#67, Aug 1 1997, 22:34:28"
+\end{verbatim}
-\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
-returns the number of items in the dictionary.
+The returned string points into static storage; the caller should not
+modify its value. The value is available to Python code as part of
+the variable \code{sys.version}.
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
- int ppos,
- PyObject **pkey,
- PyObject **pvalue}
-
+\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
+% XXX
\end{cfuncdesc}
+% XXX Other PySys thingies (doesn't really belong in this chapter)
-\section{Numeric Objects}
+\section{Thread State and the Global Interpreter Lock}
-\subsection{Plain Integer Objects}
+The Python interpreter is not fully thread safe. In order to support
+multi-threaded Python programs, there's a global lock that must be
+held by the current thread before it can safely access Python objects.
+Without the lock, even the simplest operations could cause problems in
+a multi-threaded proram: for example, when two threads simultaneously
+increment the reference count of the same object, the reference count
+could end up being incremented only once instead of twice.
-\begin{ctypedesc}{PyIntObject}
-This subtype of \code{PyObject} represents a Python integer object.
-\end{ctypedesc}
+Therefore, the rule exists that only the thread that has acquired the
+global interpreter lock may operate on Python objects or call Python/C
+API functions. In order to support multi-threaded Python programs,
+the interpreter regularly release and reacquires the lock -- by
+default, every ten bytecode instructions (this can be changed with
+\code{sys.setcheckinterval()}). The lock is also released and
+reacquired around potentially blocking I/O operations like reading or
+writing a file, so that other threads can run while the thread that
+requests the I/O is waiting for the I/O operation to complete.
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
-This instance of \code{PyTypeObject} represents the Python plain
-integer type.
-\end{cvardesc}
+The Python interpreter needs to keep some bookkeeping information
+separate per thread -- for this it uses a data structure called
+PyThreadState. This is new in Python 1.5; in earlier versions, such
+state was stored in global variables, and switching threads could
+cause problems. In particular, exception handling is now thread safe,
+when the application uses \code{sys.exc_info()} to access the exception
+last raised in the current thread.
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
+There's one global variable left, however: the pointer to the current
+PyThreadState structure. While most thread packages have a way to
+store ``per-thread global data'', Python's internal platform
+independent thread abstraction doesn't support this (yet). Therefore,
+the current thread state must be manipulated explicitly.
-\end{cfuncdesc}
+This is easy enough in most cases. Most code manipulating the global
+interpreter lock has the following simple structure:
-\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
-creates a new integer object with a value of \code{ival}.
+\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}
-The current implementation keeps an array of integer objects for all
-integers between -1 and 100, when you create an int in that range you
-actually just get back a reference to the existing object. So it should
-be possible to change the value of 1. I suspect the behaviour of python
-in this case is undefined. :-)
-\end{cfuncdesc}
+This is so common that a pair of macros exists to simplify it:
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
-returns the value of the object \code{io}.
-\end{cfuncdesc}
+\begin{verbatim}
+Py_BEGIN_ALLOW_THREADS
+...Do some blocking I/O operation...
+Py_END_ALLOW_THREADS
+\end{verbatim}
-\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
-will first attempt to cast the object to a PyIntObject, if
-it is not already one, and the return it's value.
-\end{cfuncdesc}
+The BEGIN macro opens a new block and declares a hidden local
+variable; the END macro closes the block. Another advantage of using
+these two macros is that when Python is compiled without thread
+support, they are defined empty, thus saving the thread state and lock
+manipulations.
-\begin{cfuncdesc}{long}{PyInt_GetMax}{}
-returns the systems idea of the largest int it can handle
-(LONG_MAX, as defined in the system header files)
-\end{cfuncdesc}
+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}
-\subsection{Long Integer Objects}
+Using even lower level primitives, we can get roughly the same effect
+as follows:
-\begin{ctypedesc}{PyLongObject}
-This subtype of \code{PyObject} represents a Python long integer object.
-\end{ctypedesc}
+\begin{verbatim}
+{
+ PyThreadState *_save;
+ _save = PyThreadState_Swap(NULL);
+ PyEval_ReleaseLock();
+ ...Do some blocking I/O operation...
+ PyEval_AcquireLock();
+ PyThreadState_Swap(_save);
+}
+\end{verbatim}
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
-This instance of \code{PyTypeObject} represents the Python long integer type.
-\end{cvardesc}
+There are some subtle differences; in particular,
+\code{PyEval_RestoreThread()} saves and restores the value of the
+global variable \code{errno}, since the lock manipulation does not
+guarantee that \code{errno} is left alone. Also, when thread support
+is disabled, \code{PyEval_SaveThread()} and
+\code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
+\code{PyEval_ReleaseLock()} and \code{PyEval_AcquireLock()} are not
+available. (This is done so that dynamically loaded extensions
+compiled with thread support enabled can be loaded by an interpreter
+that was compiled with disabled thread support.)
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-returns true if it's argument is a \code{PyLongObject}
-\end{cfuncdesc}
+The global interpreter lock is used to protect the pointer to the
+current thread state. When releasing the lock and saving the thread
+state, the current thread state pointer must be retrieved before the
+lock is released (since another thread could immediately acquire the
+lock and store its own thread state in the global variable).
+Reversely, when acquiring the lock and restoring the thread state, the
+lock must be acquired before storing the thread state pointer.
-\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
+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.
-\end{cfuncdesc}
+When creating a thread data structure, you need to provide an
+interpreter state data structure. The interpreter state data
+structure hold global data that is shared by all threads in an
+interpreter, for example the module administration
+(\code{sys.modules}). Depending on your needs, you can either create
+a new interpreter state data structure, or share the interpreter state
+data structure used by the Python main thread (to access the latter,
+you must obtain the thread state and access its \code{interp} member;
+this must be done by a thread that is created by Python or by the main
+thread after Python is initialized).
-\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
+XXX More?
-\end{cfuncdesc}
+\begin{ctypedesc}{PyInterpreterState}
+\strong{(NEW in 1.5a3!)}
+This data structure represents the state shared by a number of
+cooperating threads. Threads belonging to the same interpreter
+share their module administration and a few other internal items.
+There are no public members in this structure.
-\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
+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}
-\end{cfuncdesc}
+\begin{ctypedesc}{PyThreadState}
+\strong{(NEW in 1.5a3!)}
+This data structure represents the state of a single thread. The only
+public data member is \code{PyInterpreterState *interp}, which points
+to this thread's interpreter state.
+\end{ctypedesc}
+
+\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
+Initialize and acquire the global interpreter lock. It should be
+called in the main thread before creating a second thread or engaging
+in any other thread operations such as \code{PyEval_ReleaseLock()} or
+\code{PyEval_ReleaseThread(tstate)}. It is not needed before
+calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
+This is a no-op when called for a second time. It is safe to call
+this function before calling \code{Py_Initialize()}.
-\end{cfuncdesc}
+When only the main thread exists, no lock operations are needed. This
+is a common situation (most Python programs do not use threads), and
+the lock operations slow the interpreter down a bit. Therefore, the
+lock is not created initially. This situation is equivalent to having
+acquired the lock: when there is only a single thread, all object
+accesses are safe. Therefore, when this function initializes the
+lock, it also acquires it. Before the Python \code{thread} module
+creates a new thread, knowing that either it has the lock or the lock
+hasn't been created yet, it calls \code{PyEval_InitThreads()}. When
+this call returns, it is guaranteed that the lock has been created and
+that it has acquired it.
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
+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}{double}{PyLong_AsDouble}{PyObject *}
-
+\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+\strong{(NEW in 1.5a3!)}
+Acquire the global interpreter lock. The lock must have been created
+earlier. If this thread already has the lock, a deadlock ensues.
+This function is not available when thread support is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
-
+\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+\strong{(NEW in 1.5a3!)}
+Release the global interpreter lock. The lock must have been created
+earlier. This function is not available when thread support is
+disabled at
+compile time.
\end{cfuncdesc}
-
-\subsection{Floating Point Objects}
-
-\begin{ctypedesc}{PyFloatObject}
-This subtype of \code{PyObject} represents a Python floating point object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
-This instance of \code{PyTypeObject} represents the Python floating
-point type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-returns true if it's argument is a \code{PyFloatObject}
+\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Acquire the global interpreter lock and then set the current thread
+state to \var{tstate}, which should not be \NULL{}. The lock must
+have been created earlier. If this thread already has the lock,
+deadlock ensues. This function is not available when thread support
+is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
-
+\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+\strong{(NEW in 1.5a3!)}
+Reset the current thread state to \NULL{} and release the global
+interpreter lock. The lock must have been created earlier and must be
+held by the current thread. The \var{tstate} argument, which must not
+be \NULL{}, is only used to check that it represents the current
+thread state -- if it isn't, a fatal error is reported. This function
+is not available when thread support is disabled at
+compile time.
\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
-
+\begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
+\strong{(Different return type in 1.5a3!)}
+Release the interpreter lock (if it has been created and thread
+support is enabled) and reset the thread state to \NULL{},
+returning the previous thread state (which is not \NULL{}). If
+the lock has been created, the current thread must have acquired it.
+(This function is available even when thread support is disabled at
+compile time.)
\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
-
+\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
+\strong{(Different argument type in 1.5a3!)}
+Acquire the interpreter lock (if it has been created and thread
+support is enabled) and set the thread state to \var{tstate}, which
+must not be \NULL{}. If the lock has been created, the current
+thread must not have acquired it, otherwise deadlock ensues. (This
+function is available even when thread support is disabled at compile
+time.)
\end{cfuncdesc}
+% XXX These aren't really C types, but the ctypedesc macro is the simplest!
+\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
+This macro expands to
+\code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
+Note that it contains an opening brace; it must be matched with a
+following \code{Py_END_ALLOW_THREADS} macro. See above for further
+discussion of this macro. It is a no-op when thread support is
+disabled at compile time.
+\end{ctypedesc}
-\subsection{Complex Number Objects}
+\begin{ctypedesc}{Py_END_ALLOW_THREADS}
+This macro expands to
+\code{PyEval_RestoreThread(_save); \} }.
+Note that it contains a closing brace; it must be matched with an
+earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
+discussion of this macro. It is a no-op when thread support is
+disabled at compile time.
+\end{ctypedesc}
-\begin{ctypedesc}{Py_complex}
-typedef struct {
- double real;
- double imag;
-}
+\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
+This macro expands to \code{PyEval_RestoreThread(_save);} i.e. it
+is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
+brace. It is a no-op when thread support is disabled at compile
+time.
\end{ctypedesc}
-\begin{ctypedesc}{PyComplexObject}
-This subtype of \code{PyObject} represents a Python complex number object.
+\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
+This macro expands to \code{_save = PyEval_SaveThread();} i.e. it is
+equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
+and variable declaration. It is a no-op when thread support is
+disabled at compile time.
\end{ctypedesc}
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
-This instance of \code{PyTypeObject} represents the Python complex
-number type.
-\end{cvardesc}
+All of the following functions are only available when thread support
+is enabled at compile time, and must be called only when the
+interpreter lock has been created. They are all new in 1.5a3.
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-returns true if it's argument is a \code{PyComplexObject}
+\begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
+Create a new interpreter state object. The interpreter lock must be
+held.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
-
+\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}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
-
+\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
+Destroy an interpreter state object. The interpreter lock need not be
+held. The interpreter state must have been reset with a previous
+call to \code{PyInterpreterState_Clear()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
-
+\begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
+Create a new thread state object belonging to the given interpreter
+object. The interpreter lock must be held.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
-
+\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}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
-
+\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
+Destroy a thread state object. The interpreter lock need not be
+held. The thread state must have been reset with a previous
+call to \code{PyThreadState_Clear()}.
\end{cfuncdesc}
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
-
+\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}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
-
+\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 *}{PyComplex_FromDoubles}{double real, double imag}
-
-\end{cfuncdesc}
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
+\section{Defining New Object Types}
-\end{cfuncdesc}
+XXX To be done:
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
+PyObject, PyVarObject
-\end{cfuncdesc}
+PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
+Typedefs:
+unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
+getreadbufferproc, getwritebufferproc, getsegcountproc,
+destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
+setattrofunc, cmpfunc, reprfunc, hashfunc
-\end{cfuncdesc}
+PyNumberMethods
+PySequenceMethods
+PyMappingMethods
-\section{Other Objects}
+PyBufferProcs
-\subsection{File Objects}
+PyTypeObject
-\begin{ctypedesc}{PyFileObject}
-This subtype of \code{PyObject} represents a Python file object.
-\end{ctypedesc}
+DL_IMPORT
-\begin{cvardesc}{PyTypeObject}{PyFile_Type}
-This instance of \code{PyTypeObject} represents the Python file type.
-\end{cvardesc}
+PyType_Type
-\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
-returns true if it's argument is a \code{PyFileObject}
-\end{cfuncdesc}
+Py*_Check
-\begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
-creates a new PyFileObject pointing to the file
-specified in \code{name} with the mode specified in \code{mode}
-\end{cfuncdesc}
+Py_None, _Py_NoneStruct
-\begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
- char *name, char *mode, int (*close})
-creates a new PyFileObject from the already-open \code{fp}.
-The function \code{close} will be called when the file should be closed.
-\end{cfuncdesc}
+_PyObject_New, _PyObject_NewVar
-\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
-returns the file object associated with \code{p} as a \code{FILE *}
-\end{cfuncdesc}
+PyObject_NEW, PyObject_NEW_VAR
-\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
-undocumented as yet
-\end{cfuncdesc}
-\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
-returns the name of the file specified by \code{p} as a
-PyStringObject
-\end{cfuncdesc}
+\chapter{Defining New Object Types}
-\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
-on systems with \code{setvbuf} only
+\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
-same as the file object method \code{softspace}
+\begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
-writes object \code{obj} to file object \code{p}
+\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
\end{cfuncdesc}
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
-writes string \code{s} to file object \code{p}
+\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
\end{cfuncdesc}
-\subsection{CObjects}
+\chapter{Debugging}
-XXX
+XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
\input{api.ind} % Index -- must be last
projects / thirdparty / Python / cpython.git / commitdiff
