Next: 2 Basic Utilities Up: 1 Introduction Previous: 1.3 Exceptions
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__ and sys. 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/python1.5 (replacing 1.5 with the current
interpreter version) 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/python1.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(),
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 iff Python is currently in the
initialized state. More information about these functions is given in
a later chapter.
guido@CNRI.Reston.Va.US