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
This initializes the table of loaded modules, and creates the
fundamental modules __builtin__,
sys. It also initializes the module
search 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
argv) subsequent to the call to
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
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.