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 search path (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.
Py_Finalize()
is
called, this returns false until Py_Initialize()
is called
again.
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.
__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 as
extension is imported after the interpreter has been completely
re-initialized by calling Py_Finalize()
and
Py_Initialize()
; in that case, the extension's init
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.)
Py_Finalize()
will destroy all sub-interpreters that haven't
been explicitly destroyed at that point.
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.
Py_SetProgramName()
, or the
default. The returned string points into static storage; the caller
should not modify its value.
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.
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.
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
.
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.
"1.5a3 (#67, Aug 1 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
.
"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
.
"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"
The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as the list
sys.copyright
.
"[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
.
"#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
.
guido@CNRI.Reston.Va.US