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
Py_SetProgramName(),
PyEval_InitThreads(),
PyEval_ReleaseLock(),
and PyEval_AcquireLock().
This initializes the table of loaded modules (sys.modules), and
creates the
fundamental modules __builtin__,
__main__and
sys. It also initializes the module
searchpath (sys.path).
It does not set sys.argv; use
PySys_SetArgv()for that. This
is a no-op when called for a second time (without calling
Py_Finalize()first). There is no
return value; it is a fatal error if the initialization fails.
Return true (nonzero) when the Python interpreter has been
initialized, false (zero) if not. After Py_Finalize() is
called, this returns false until Py_Initialize() is called
again.
Undo all initializations made by Py_Initialize() and
subsequent use of Python/C API functions, and destroy all
sub-interpreters (see Py_NewInterpreter() below) that were
created and not yet destroyed since the last call to
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 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.
Bugs and caveats: The destruction of modules and objects in
modules is done in random order; this may cause destructors
(__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 Py_Initialize() and Py_Finalize() more
than once.
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
__builtin__,
__main__and
sys. The table of loaded modules
(sys.modules) and the module search path (sys.path) are
also separate. The new environment has no sys.argv variable.
It has new standard I/O stream file objects sys.stdin,
sys.stdout and sys.stderr (however these refer to the
same underlying FILE structures in the C library).
The return value points to the first thread state created in the new
sub-interpreter. This thread state is made the current thread state.
Note that no actual thread is created; see the discussion of thread
states below. If creation of the new interpreter is unsuccessful,
NULL is returned; no exception is set since the exception state
is stored in the current thread state and there may not be a current
thread state. (Like all other Python/C API functions, the global
interpreter lock must be held before calling this function and is
still held when it returns; however, unlike most other Python/C API
functions, there needn't be a current thread state on entry.)
Extension modules are shared between (sub-)interpreters as follows:
the first time a particular extension is imported, it is initialized
normally, and a (shallow) copy of its module's dictionary is
squirreled away. When the same extension is imported by another
(sub-)interpreter, a new module is initialized and filled with the
contents of this copy; the extension's init function is not
called. Note that this is different from what happens when an
extension is imported after the interpreter has been completely
re-initialized by calling
Py_Finalize()and
Py_Initialize(); in that case,
the extension's initmodule function is called
again.
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
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.)
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.)
Py_Finalize()will destroy all
sub-interpreters that haven't been explicitly destroyed at that point.
This function should be called before
Py_Initialize()is called
for the first time, if it is called at all. It tells the interpreter
the value of the argv[0] argument to the
main()function of the program. This is
used by Py_GetPath()and some other
functions below to find the Python run-time libraries relative to the
interpreter executable. The default value is '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.
Return the program name set with
Py_SetProgramName(), or the
default. The returned string points into static storage; the caller
should not modify its value.
Return the prefix for installed platform-independent files. This
is derived through a number of complicated rules from the program name
set with Py_SetProgramName() and some environment variables;
for example, if the program name is '/usr/local/bin/python',
the prefix is '/usr/local'. The returned string points into
static storage; the caller should not modify its value. This
corresponds to the prefix variable in the top-level
Makefile and the --prefix argument to the
configure script at build time. The value is available to
Python code as sys.prefix. It is only useful on Unix. See
also the next function.
Return the exec-prefix for installed platform-dependent
files. This is derived through a number of complicated rules from the
program name set with Py_SetProgramName() and some environment
variables; for example, if the program name is
'/usr/local/bin/python', the exec-prefix is
'/usr/local'. The returned string points into static storage;
the caller should not modify its value. This corresponds to the
exec_prefix variable in the top-level Makefile and the
--exec-prefix argument to the
configure script at build time. The value is available to
Python code as 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
/usr/local/plat subtree while platform independent may be
installed in /usr/local.
Generally speaking, a platform is a combination of hardware and
software families, e.g. Sparc machines running the Solaris 2.x
operating system are considered the same platform, but Intel machines
running Solaris 2.x are another platform, and Intel machines running
Linux are yet another platform. Different major revisions of the same
operating system generally also form different platforms. Non-Unix
operating systems are a different story; the installation strategies
on those systems are so different that the prefix and exec-prefix are
meaningless, and set to the empty string. Note that compiled Python
bytecode files are platform independent (but not independent from the
Python version by which they were compiled!).
System administrators will know how to configure the mount or
automount programs to share /usr/local between platforms
while having /usr/local/plat be a different filesystem for each
platform.
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
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
sys.executable.
Return the default module search path; this is computed from the
program name (set by 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 ":" on Unix, ";" on
DOS/Windows, and "\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 sys.path,
which may be modified to change the future search path for loaded
modules.
Return the version of this Python interpreter. This is a string that
looks something like
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
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 sys.version.
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
'sunos5'. On Macintosh, it is 'mac'. On Windows, it
is 'win'. The returned string points into static storage;
the caller should not modify its value. The value is available to
Python code as sys.platform.
The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as the list
sys.copyright.
Return an indication of the compiler used to build the current Python
version, in square brackets, for example:
"[GCC 2.7.2.2]"
The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as part of
the variable sys.version.
Return information about the sequence number and build date and time
of the current Python interpreter instance, for example
"#67, Aug 1 1997, 22:34:28"
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 sys.version.
Set sys.argv based on argc and argv. These
parameters are similar to those passed to the program's
main()function with the difference that
the first entry should refer to the script file to be executed rather
than the executable hosting the Python interpreter. If there isn't a
script that will be run, the first entry in argv can be an empty
string. If this function fails to initialize sys.argv, a fatal
condition is signalled using
Py_FatalError().