From e5bf8b2c7992a7507824f034c299bc74ca3c3d59 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Thu, 12 Feb 1998 21:22:28 +0000 Subject: [PATCH] Reorganized a bit. No changed content. Guido, please take a look at new structure, at least the ToC. --- Doc/api.tex | 1839 +++++++++++++++++++++++------------------------ Doc/api/api.tex | 1839 +++++++++++++++++++++++------------------------ 2 files changed, 1832 insertions(+), 1846 deletions(-) diff --git a/Doc/api.tex b/Doc/api.tex index 780034a787..b13a097703 100644 --- a/Doc/api.tex +++ b/Doc/api.tex @@ -523,34 +523,40 @@ initialized state. More information about these functions is given in 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} @@ -849,7 +855,36 @@ the standard \C{} library function \code{time()}. \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} @@ -978,48 +1013,6 @@ dynamically created collection of frozen modules. \end{cvardesc} -\chapter{Debugging} - -XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - -\chapter{The Very High Level Layer} - -The functions in this chapter will let you execute Python source code -given in a file or a buffer, but they will not let you interact in a -more detailed way with the interpreter. - -\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} -\end{cfuncdesc} - - \chapter{Abstract Objects Layer} The functions in this chapter interact with Python objects regardless @@ -1609,1226 +1602,1226 @@ types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; e.g. to check that an object is a dictionary, use -\code{PyDict_Check()}. +\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 diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 780034a787..b13a097703 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -523,34 +523,40 @@ initialized state. More information about these functions is given in 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} @@ -849,7 +855,36 @@ the standard \C{} library function \code{time()}. \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} @@ -978,48 +1013,6 @@ dynamically created collection of frozen modules. \end{cvardesc} -\chapter{Debugging} - -XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - -\chapter{The Very High Level Layer} - -The functions in this chapter will let you execute Python source code -given in a file or a buffer, but they will not let you interact in a -more detailed way with the interpreter. - -\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int} -\end{cfuncdesc} - - \chapter{Abstract Objects Layer} The functions in this chapter interact with Python objects regardless @@ -1609,1226 +1602,1226 @@ types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; e.g. to check that an object is a dictionary, use -\code{PyDict_Check()}. +\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 -- 2.50.1