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.3 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.3.
(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 all 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.
|
