From 42cefd03cf6097d016cded315b0d496eecdbaf89 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Sun, 5 Oct 1997 15:27:29 +0000 Subject: [PATCH] Checkpoint. Added docs for the new exception handling APIs and for the interfaces defined in import.h. --- Doc/api.tex | 288 ++++++++++++++++++++++++++++++++++++++++++------ Doc/api/api.tex | 288 ++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 506 insertions(+), 70 deletions(-) diff --git a/Doc/api.tex b/Doc/api.tex index 98969b73f38..63ba3079e41 100644 --- a/Doc/api.tex +++ b/Doc/api.tex @@ -463,21 +463,24 @@ will be executed later, it must be set explicitly with a call to \code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call to \code{Py_Initialize()}. -On Unix, \code{Py_Initialize()} calculates the module search path -based upon its best guess for the location of the standard Python -interpreter executable, assuming that the Python library is found in a -fixed location relative to the Python interpreter executable. In -particular, it looks for a directory named \code{lib/python1.5} -(replacing \code{1.5} with the current interpreter version) relative -to the parent directory where the executable named \code{python} is -found on the shell command search path (the environment variable -\code{\$PATH}). For instance, if the Python executable is found in -\code{/usr/local/bin/python}, it will assume that the libraries are in -\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' -location, used when no executable file named \code{python} is found -along \code{\$PATH}. The user can change this behavior by setting the -environment variable \code{\$PYTHONHOME}, and can insert additional -directories in front of the standard path by setting +On most systems (in particular, on Unix and Windows, although the +details are slightly different), \code{Py_Initialize()} calculates the +module search path based upon its best guess for the location of the +standard Python interpreter executable, assuming that the Python +library is found in a fixed location relative to the Python +interpreter executable. In particular, it looks for a directory named +\code{lib/python1.5} (replacing \code{1.5} with the current +interpreter version) relative to the parent directory where the +executable named \code{python} is found on the shell command search +path (the environment variable \code{\$PATH}). + +For instance, if the Python executable is found in +\code{/usr/local/bin/python}, it will assume that the libraries are in +\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' +location, used when no executable file named \code{python} is found +along \code{\$PATH}. The user can change this behavior by setting the +environment variable \code{\$PYTHONHOME}, and can insert additional +directories in front of the standard path by setting \code{\$PYTHONPATH}. The embedding application can steer the search by calling @@ -646,14 +649,6 @@ would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. \end{cfuncdesc} -\begin{cfuncdesc}{void}{PyImport_Init}{} -Initialize the module table. For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyImport_Cleanup}{} -Empty the module table. For internal use only. -\end{cfuncdesc} - \begin{cfuncdesc}{void}{PyBuiltin_Init}{} Initialize the \code{__builtin__} module. For internal use only. \end{cfuncdesc} @@ -742,7 +737,35 @@ Test whether the error indicator is set. If set, return the exception \code{type} (the first argument to the last call to one of the \code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not set, return \NULL{}. You do not own a reference to the return value, -so you do not need to \code{Py_DECREF()} it. +so you do not need to \code{Py_DECREF()} it. Note: do not compare the +return value to a specific exception; use +\code{PyErr_ExceptionMatches} instead, shown below. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} +\strong{NEW in 1.5a4!} +Equivalent to +\code{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}. +This should only be called when an exception is actually set. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} +\strong{NEW in 1.5a4!} +Return true if the \var{given} exception matches the exception in +\var{exc}. If \var{exc} is a class object, this also returns true +when \var{given} is a subclass. If \var{exc} is a tuple, all +exceptions in the tuple (and recursively in subtuples) are searched +for a match. This should only be called when an exception is actually +set. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} +\strong{NEW in 1.5a4!} +Under certain circumstances, the values returned by +\code{PyErr_Fetch()} below can be ``unnormalized'', meaning that +\var{*exc} is a class object but \var{*val} is not an instance of the +same class. This function can be used to instantiate the class in +that case. If the values are already normalized, nothing happens. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyErr_Clear}{} @@ -846,13 +869,39 @@ the effect of a \code{SIGINT} signal arriving -- the next time raised. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name, +PyObject *base, PyObject *dict} +\strong{NEW in 1.5a4!} +This utility function creates and returns a new exception object. The +\var{name} argument must be the name of the new exception, a C string +of the form \code{module.class}. The \var{base} and \var{dict} +arguments are normally \code{NULL}. Normally, this creates a class +object derived from the root for all exceptions, the built-in name +\code{Exception} (accessible in C as \code{PyExc_Exception}). In this +case the \code{__module__} attribute of the new class is set to the +first part (up to the last dot) of the \var{name} argument, and the +class name is set to the last part (after the last dot). When the +user has specified the \code{-X} command line option to use string +exceptions, for backward compatibility, or when the \var{base} +argument is not a class object (and not \code{NULL}), a string object +created from the entire \var{name} argument is returned. The +\var{base} argument can be used to specify an alternate base class. +The \var{dict} argument can be used to specify a dictionary of class +variables and methods. +\end{cfuncdesc} + + \section{Standard Exceptions} All standard Python exceptions are available as global variables whose names are \code{PyExc_} followed by the Python exception name. These have the type \code{PyObject *}; they are all string objects. -For completion, here are all the variables: -\code{PyExc_AccessError}, +For completeness, here are all the variables (the first four are new +in Python 1.5a4): +\code{PyExc_Exception}, +\code{PyExc_StandardError}, +\code{PyExc_ArithmeticError}, +\code{PyExc_LookupError}, \code{PyExc_AssertionError}, \code{PyExc_AttributeError}, \code{PyExc_EOFError}, @@ -880,6 +929,8 @@ The functions in this chapter perform various utility tasks, such as parsing function arguments and constructing Python values from C values. +\section{OS Utilities} + \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} Return true (nonzero) if the standard I/O file \code{fp} with name \code{filename} is deemed interactive. This is the case for files for @@ -896,6 +947,153 @@ the standard C library function \code{time()}. \end{cfuncdesc} +\section{Importing modules} + +\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} +This is a simplified interface to \code{PyImport_ImportModuleEx} +below, leaving the \var{globals} and \var{locals} arguments set to +\code{NULL}. When the \var{name} argument contains a dot (i.e., when +it specifies a submodule of a package), the \var{fromlist} argument is +set to the list \code{['*']} so that the return value is the named +module rather than the top-level package containing it as would +otherwise be the case. (Unfortunately, this has an additional side +effect when \var{name} in fact specifies a subpackage instead of a +submodule: the submodules specified in the package's \code{__all__} +variable are loaded.) Return a new reference to the imported module, +or \code{NULL} with an exception set on failure (the module may still +be created in this case). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist} +\strong{NEW in 1.5a4!} +Import a module. This is best described by referring to the built-in +Python function \code{__import()__}, as the standard +\code{__import__()} function calls this function directly. + +% Should move this para to libfuncs.tex: +For example, the statement \code{import spam} results in the following +call: +\code{__import__('spam', globals(), locals(), [])}; +the statement \code{from spam.ham import eggs} results in +\code{__import__('spam.ham', globals(), locals(), ['eggs'])}. +Note that even though \code{locals()} and \code{['eggs']} are passed +in as arguments, the \code{__import__()} function does not set the +local variable named \code{eggs}; this is done by subsequent code that +is generated for the import statement. + +The return value is a new reference to the imported module or +top-level package, or \code{NULL} with an exception set on failure +(the module may still be created in this case). When the \var{name} +variable is of the form \code{package.module}, normally, the top-level +package (the name up till the first dot) is returned, \emph{not} the +module named by \var{name}. However, when a non-empty \var{fromlist} +argument is given, the module named by \var{name} is returned. This +is done for compatibility with the bytecode generated for the +different kinds of import statement; when using \code{import +spam.ham.eggs}, the top-level package \code{spam} must be placed in +the importing namespace, but when using \code{from spam.ham import +eggs}, the \code{spam.ham} subpackage must be used to find the +\code{eggs} variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name} +This is a higher-level interface that calls the current ``import hook +function''. It invokes the \code{__import__()} function from the +\code{__builtins__} of the current globals. This means that the +import is done using whatever import hooks are installed in the +current environment, e.g. by \code{rexec} or \code{ihooks}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m} +Reload a module. This is best described by referring to the built-in +Python function \code{reload()}, as the standard \code{reload()} +function calls this function directly. Return a new reference to the +reloaded module, or \code{NULL} with an exception set on failure (the +module still exists in this case). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name} +Return the module object corresponding to a module name. The +\var{name} argument may be of the form \code{package.module}). First +check the modules dictionary if there's one there, and if not, create +a new one and insert in in the modules dictionary. Because the former +action is most common, this does not return a new reference, and you +do not own the returned reference. Return \code{NULL} with an +exception set on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co} +Given a module name (possibly of the form \code{package.module}) and a +code object read from a Python bytecode file or obtained from the +built-in function \code{compile()}, load the module. Return a new +reference to the module object, or \code{NULL} with an exception set +if an error occurred (the module may still be created in this case). +(This function would reload the module if it was already imported.) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} +Return the magic number for Python bytecode files (a.k.a. \code{.pyc} +and \code{.pyo} files). The magic number should be present in the +first four bytes of the bytecode file, in little-endian byte order. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{} +Return the dictionary used for the module administration +(a.k.a. \code{sys.modules}). Note that this is a per-interpreter +variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Init}{} +Initialize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Cleanup}{} +Empty the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Fini}{} +Finalize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *} +For internal use only. +\end{cvardesc} + +\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *} +For internal use only. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *} +Load a frozen module. Return \code{1} for success, \code{0} if the +module is not found, and \code{-1} with an exception set if the +initialization failed. To access the imported module on a successful +load, use \code{PyImport_ImportModule()). +(Note the misnomer -- this function would reload the module if it was +already imported.) +\end{cfuncdesc} + +\begin{ctypedesc}{struct _frozen} +This is the structure type definition for frozen module descriptors, +as generated by the \code{freeze} utility (see \file{Tools/freeze/} in +the Python source distribution). Its definition is: +\bcode\begin{verbatim} +struct _frozen { + char *name; + unsigned char *code; + int size; +}; +\end{verbatim}\ecode +\end{ctypedesc} + +\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules} +This pointer is initialized to point to an array of \code{struct +_freeze} records, terminated by one whose members are all \code{NULL} +or zero. When a frozen module is imported, it is searched in this +table. Third party code could play tricks with this to provide a +dynamically created collection of frozen modules. +\end{cvardesc} + + \chapter{Debugging} XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. @@ -1557,20 +1755,29 @@ functions; with the exception of \code{Py_SetProgramName()}, 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. It is a fatal -error to call it for a second time without calling -\code{Py_Finalize()} first. There is no return value; it is a fatal -error if the initialization fails. +\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op +when called for a second time (without calling \code{Py_Finalize()} +first). There is no return value; it is a fatal error if the +initialization fails. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_IsInitialized}{} +\strong{NEW in 1.5a4!} +Return true (nonzero) when the Python interpreter has been +initialized, false (zero) if not. After \code{Py_Finalize()} is +called, this returns false until \code{Py_Initialize()} is called +again. \end{cfuncdesc} \begin{cfuncdesc}{void}{Py_Finalize}{} +\strong{NEW in 1.5a3!} Undo all initializations made by \code{Py_Initialize()} and subsequent use of Python/C API functions, and destroy all sub-interpreters (see \code{Py_NewInterpreter()} below) that were created and not yet -destroyed since the last call to \code{Py_Initialize()}. Ideally, -this frees all memory allocated by the Python interpreter. It is a -fatal error to call it for a second time without calling -\code{Py_Initialize()} again first. There is no return value; errors +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 @@ -1595,6 +1802,7 @@ 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 @@ -1647,6 +1855,7 @@ 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 @@ -1658,6 +1867,7 @@ been explicitly destroyed at that point. \end{cfuncdesc} \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} +\strong{NEW in 1.5a3!} This function should be called before \code{Py_Initialize()} is called for the first time, if it is called at all. It tells the interpreter the value of the \code{argv[0]} argument to the \code{main()} function @@ -1729,12 +1939,13 @@ platform. \end{cfuncdesc} \begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{} +\strong{NEW in 1.5a3!} Return the full program name of the Python executable; this is computed as a side-effect of deriving the default module search path from the program name (set by \code{Py_SetProgramName()} above). The returned string points into static storage; the caller should not modify its value. The value is available to Python code as -\code{sys.executable}. % XXX is that the right sys.name? +\code{sys.executable}. \end{cfuncdesc} \begin{cfuncdesc}{char *}{Py_GetPath}{} @@ -1822,15 +2033,22 @@ the variable \code{sys.version}. \section{Thread State and the Global Interpreter Lock} \begin{cfuncdesc}{void}{PyEval_AcquireLock}{} +\strong{NEW in 1.5a3!} +HIRO + + \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 98969b73f38..63ba3079e41 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -463,21 +463,24 @@ will be executed later, it must be set explicitly with a call to \code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call to \code{Py_Initialize()}. -On Unix, \code{Py_Initialize()} calculates the module search path -based upon its best guess for the location of the standard Python -interpreter executable, assuming that the Python library is found in a -fixed location relative to the Python interpreter executable. In -particular, it looks for a directory named \code{lib/python1.5} -(replacing \code{1.5} with the current interpreter version) relative -to the parent directory where the executable named \code{python} is -found on the shell command search path (the environment variable -\code{\$PATH}). For instance, if the Python executable is found in -\code{/usr/local/bin/python}, it will assume that the libraries are in -\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' -location, used when no executable file named \code{python} is found -along \code{\$PATH}. The user can change this behavior by setting the -environment variable \code{\$PYTHONHOME}, and can insert additional -directories in front of the standard path by setting +On most systems (in particular, on Unix and Windows, although the +details are slightly different), \code{Py_Initialize()} calculates the +module search path based upon its best guess for the location of the +standard Python interpreter executable, assuming that the Python +library is found in a fixed location relative to the Python +interpreter executable. In particular, it looks for a directory named +\code{lib/python1.5} (replacing \code{1.5} with the current +interpreter version) relative to the parent directory where the +executable named \code{python} is found on the shell command search +path (the environment variable \code{\$PATH}). + +For instance, if the Python executable is found in +\code{/usr/local/bin/python}, it will assume that the libraries are in +\code{/usr/local/lib/python1.5}. In fact, this also the ``fallback'' +location, used when no executable file named \code{python} is found +along \code{\$PATH}. The user can change this behavior by setting the +environment variable \code{\$PYTHONHOME}, and can insert additional +directories in front of the standard path by setting \code{\$PYTHONPATH}. The embedding application can steer the search by calling @@ -646,14 +649,6 @@ would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. \end{cfuncdesc} -\begin{cfuncdesc}{void}{PyImport_Init}{} -Initialize the module table. For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyImport_Cleanup}{} -Empty the module table. For internal use only. -\end{cfuncdesc} - \begin{cfuncdesc}{void}{PyBuiltin_Init}{} Initialize the \code{__builtin__} module. For internal use only. \end{cfuncdesc} @@ -742,7 +737,35 @@ Test whether the error indicator is set. If set, return the exception \code{type} (the first argument to the last call to one of the \code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not set, return \NULL{}. You do not own a reference to the return value, -so you do not need to \code{Py_DECREF()} it. +so you do not need to \code{Py_DECREF()} it. Note: do not compare the +return value to a specific exception; use +\code{PyErr_ExceptionMatches} instead, shown below. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} +\strong{NEW in 1.5a4!} +Equivalent to +\code{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}. +This should only be called when an exception is actually set. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} +\strong{NEW in 1.5a4!} +Return true if the \var{given} exception matches the exception in +\var{exc}. If \var{exc} is a class object, this also returns true +when \var{given} is a subclass. If \var{exc} is a tuple, all +exceptions in the tuple (and recursively in subtuples) are searched +for a match. This should only be called when an exception is actually +set. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} +\strong{NEW in 1.5a4!} +Under certain circumstances, the values returned by +\code{PyErr_Fetch()} below can be ``unnormalized'', meaning that +\var{*exc} is a class object but \var{*val} is not an instance of the +same class. This function can be used to instantiate the class in +that case. If the values are already normalized, nothing happens. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyErr_Clear}{} @@ -846,13 +869,39 @@ the effect of a \code{SIGINT} signal arriving -- the next time raised. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name, +PyObject *base, PyObject *dict} +\strong{NEW in 1.5a4!} +This utility function creates and returns a new exception object. The +\var{name} argument must be the name of the new exception, a C string +of the form \code{module.class}. The \var{base} and \var{dict} +arguments are normally \code{NULL}. Normally, this creates a class +object derived from the root for all exceptions, the built-in name +\code{Exception} (accessible in C as \code{PyExc_Exception}). In this +case the \code{__module__} attribute of the new class is set to the +first part (up to the last dot) of the \var{name} argument, and the +class name is set to the last part (after the last dot). When the +user has specified the \code{-X} command line option to use string +exceptions, for backward compatibility, or when the \var{base} +argument is not a class object (and not \code{NULL}), a string object +created from the entire \var{name} argument is returned. The +\var{base} argument can be used to specify an alternate base class. +The \var{dict} argument can be used to specify a dictionary of class +variables and methods. +\end{cfuncdesc} + + \section{Standard Exceptions} All standard Python exceptions are available as global variables whose names are \code{PyExc_} followed by the Python exception name. These have the type \code{PyObject *}; they are all string objects. -For completion, here are all the variables: -\code{PyExc_AccessError}, +For completeness, here are all the variables (the first four are new +in Python 1.5a4): +\code{PyExc_Exception}, +\code{PyExc_StandardError}, +\code{PyExc_ArithmeticError}, +\code{PyExc_LookupError}, \code{PyExc_AssertionError}, \code{PyExc_AttributeError}, \code{PyExc_EOFError}, @@ -880,6 +929,8 @@ The functions in this chapter perform various utility tasks, such as parsing function arguments and constructing Python values from C values. +\section{OS Utilities} + \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} Return true (nonzero) if the standard I/O file \code{fp} with name \code{filename} is deemed interactive. This is the case for files for @@ -896,6 +947,153 @@ the standard C library function \code{time()}. \end{cfuncdesc} +\section{Importing modules} + +\begin{cfuncdesc}{PyObject *}{PyImport_ImportModule}{char *name} +This is a simplified interface to \code{PyImport_ImportModuleEx} +below, leaving the \var{globals} and \var{locals} arguments set to +\code{NULL}. When the \var{name} argument contains a dot (i.e., when +it specifies a submodule of a package), the \var{fromlist} argument is +set to the list \code{['*']} so that the return value is the named +module rather than the top-level package containing it as would +otherwise be the case. (Unfortunately, this has an additional side +effect when \var{name} in fact specifies a subpackage instead of a +submodule: the submodules specified in the package's \code{__all__} +variable are loaded.) Return a new reference to the imported module, +or \code{NULL} with an exception set on failure (the module may still +be created in this case). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist} +\strong{NEW in 1.5a4!} +Import a module. This is best described by referring to the built-in +Python function \code{__import()__}, as the standard +\code{__import__()} function calls this function directly. + +% Should move this para to libfuncs.tex: +For example, the statement \code{import spam} results in the following +call: +\code{__import__('spam', globals(), locals(), [])}; +the statement \code{from spam.ham import eggs} results in +\code{__import__('spam.ham', globals(), locals(), ['eggs'])}. +Note that even though \code{locals()} and \code{['eggs']} are passed +in as arguments, the \code{__import__()} function does not set the +local variable named \code{eggs}; this is done by subsequent code that +is generated for the import statement. + +The return value is a new reference to the imported module or +top-level package, or \code{NULL} with an exception set on failure +(the module may still be created in this case). When the \var{name} +variable is of the form \code{package.module}, normally, the top-level +package (the name up till the first dot) is returned, \emph{not} the +module named by \var{name}. However, when a non-empty \var{fromlist} +argument is given, the module named by \var{name} is returned. This +is done for compatibility with the bytecode generated for the +different kinds of import statement; when using \code{import +spam.ham.eggs}, the top-level package \code{spam} must be placed in +the importing namespace, but when using \code{from spam.ham import +eggs}, the \code{spam.ham} subpackage must be used to find the +\code{eggs} variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name} +This is a higher-level interface that calls the current ``import hook +function''. It invokes the \code{__import__()} function from the +\code{__builtins__} of the current globals. This means that the +import is done using whatever import hooks are installed in the +current environment, e.g. by \code{rexec} or \code{ihooks}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m} +Reload a module. This is best described by referring to the built-in +Python function \code{reload()}, as the standard \code{reload()} +function calls this function directly. Return a new reference to the +reloaded module, or \code{NULL} with an exception set on failure (the +module still exists in this case). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name} +Return the module object corresponding to a module name. The +\var{name} argument may be of the form \code{package.module}). First +check the modules dictionary if there's one there, and if not, create +a new one and insert in in the modules dictionary. Because the former +action is most common, this does not return a new reference, and you +do not own the returned reference. Return \code{NULL} with an +exception set on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co} +Given a module name (possibly of the form \code{package.module}) and a +code object read from a Python bytecode file or obtained from the +built-in function \code{compile()}, load the module. Return a new +reference to the module object, or \code{NULL} with an exception set +if an error occurred (the module may still be created in this case). +(This function would reload the module if it was already imported.) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} +Return the magic number for Python bytecode files (a.k.a. \code{.pyc} +and \code{.pyo} files). The magic number should be present in the +first four bytes of the bytecode file, in little-endian byte order. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{} +Return the dictionary used for the module administration +(a.k.a. \code{sys.modules}). Note that this is a per-interpreter +variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Init}{} +Initialize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Cleanup}{} +Empty the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Fini}{} +Finalize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *} +For internal use only. +\end{cvardesc} + +\begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *} +For internal use only. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *} +Load a frozen module. Return \code{1} for success, \code{0} if the +module is not found, and \code{-1} with an exception set if the +initialization failed. To access the imported module on a successful +load, use \code{PyImport_ImportModule()). +(Note the misnomer -- this function would reload the module if it was +already imported.) +\end{cfuncdesc} + +\begin{ctypedesc}{struct _frozen} +This is the structure type definition for frozen module descriptors, +as generated by the \code{freeze} utility (see \file{Tools/freeze/} in +the Python source distribution). Its definition is: +\bcode\begin{verbatim} +struct _frozen { + char *name; + unsigned char *code; + int size; +}; +\end{verbatim}\ecode +\end{ctypedesc} + +\begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules} +This pointer is initialized to point to an array of \code{struct +_freeze} records, terminated by one whose members are all \code{NULL} +or zero. When a frozen module is imported, it is searched in this +table. Third party code could play tricks with this to provide a +dynamically created collection of frozen modules. +\end{cvardesc} + + \chapter{Debugging} XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. @@ -1557,20 +1755,29 @@ functions; with the exception of \code{Py_SetProgramName()}, 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. It is a fatal -error to call it for a second time without calling -\code{Py_Finalize()} first. There is no return value; it is a fatal -error if the initialization fails. +\code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op +when called for a second time (without calling \code{Py_Finalize()} +first). There is no return value; it is a fatal error if the +initialization fails. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_IsInitialized}{} +\strong{NEW in 1.5a4!} +Return true (nonzero) when the Python interpreter has been +initialized, false (zero) if not. After \code{Py_Finalize()} is +called, this returns false until \code{Py_Initialize()} is called +again. \end{cfuncdesc} \begin{cfuncdesc}{void}{Py_Finalize}{} +\strong{NEW in 1.5a3!} Undo all initializations made by \code{Py_Initialize()} and subsequent use of Python/C API functions, and destroy all sub-interpreters (see \code{Py_NewInterpreter()} below) that were created and not yet -destroyed since the last call to \code{Py_Initialize()}. Ideally, -this frees all memory allocated by the Python interpreter. It is a -fatal error to call it for a second time without calling -\code{Py_Initialize()} again first. There is no return value; errors +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 @@ -1595,6 +1802,7 @@ 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 @@ -1647,6 +1855,7 @@ 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 @@ -1658,6 +1867,7 @@ been explicitly destroyed at that point. \end{cfuncdesc} \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} +\strong{NEW in 1.5a3!} This function should be called before \code{Py_Initialize()} is called for the first time, if it is called at all. It tells the interpreter the value of the \code{argv[0]} argument to the \code{main()} function @@ -1729,12 +1939,13 @@ platform. \end{cfuncdesc} \begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{} +\strong{NEW in 1.5a3!} Return the full program name of the Python executable; this is computed as a side-effect of deriving the default module search path from the program name (set by \code{Py_SetProgramName()} above). The returned string points into static storage; the caller should not modify its value. The value is available to Python code as -\code{sys.executable}. % XXX is that the right sys.name? +\code{sys.executable}. \end{cfuncdesc} \begin{cfuncdesc}{char *}{Py_GetPath}{} @@ -1822,15 +2033,22 @@ the variable \code{sys.version}. \section{Thread State and the Global Interpreter Lock} \begin{cfuncdesc}{void}{PyEval_AcquireLock}{} +\strong{NEW in 1.5a3!} +HIRO + + \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} +\strong{NEW in 1.5a3!} \end{cfuncdesc} \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}