1.4 Embedding Python
The one important task that only embedders (as opposed to extension writers) of the Python interpreter have to worry about is the initialization, and possibly the finalization, of the Python interpreter. Most functionality of the interpreter can only be used after the interpreter has been initialized.
The basic initialization function is
Py_Initialize().
This initializes the table of loaded modules, and creates the
fundamental modules __builtin__,
__main__, sys,
and exceptions. It also initializes
the module search path (sys.path).
Py_Initialize() does not set the ``script argument list''
(sys.argv). If this variable is needed by Python code that
will be executed later, it must be set explicitly with a call to
PySys_SetArgv(argc,
argv) subsequent to the call to
Py_Initialize().
On most systems (in particular, on Unix and Windows, although the details are slightly different), 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 lib/python2.5 relative to the parent directory where the executable named python is found on the shell command search path (the environment variable PATH).
For instance, if the Python executable is found in /usr/local/bin/python, it will assume that the libraries are in /usr/local/lib/python2.5. (In fact, this particular path is also the ``fallback'' location, used when no executable file named python is found along PATH.) The user can override this behavior by setting the environment variable PYTHONHOME, or insert additional directories in front of the standard path by setting PYTHONPATH.
The embedding application can steer the search by calling
Py_SetProgramName(file) before calling
Py_Initialize(). Note that PYTHONHOME still
overrides this and PYTHONPATH is still inserted in front of
the standard path. An application that requires total control has to
provide its own implementation of
Py_GetPath(),
Py_GetPrefix(),
Py_GetExecPrefix(), and
Py_GetProgramFullPath() (all
defined in Modules/getpath.c).
Sometimes, it is desirable to ``uninitialize'' Python. For instance, the application may want to start over (make another call to Py_Initialize()) or the application is simply done with its use of Python and wants to free memory allocated by Python. This can be accomplished by calling Py_Finalize(). The function Py_IsInitialized() returns true if Python is currently in the initialized state. More information about these functions is given in a later chapter. Notice that Py_Finalize does not free all memory allocated by the Python interpreter, e.g. memory allocated by extension modules currently cannot be released.
 |
 |
 |
Python/C API Reference Manual |  |
 |
 |
Release 2.5, documentation updated on 19th September, 2006.