GNU Info

(python2.1-api.info)Embedding Python

---

Prev: Exceptions Up: Introduction

---

Enter node , (file) or (file)node

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__'  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/python2.1' 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.1'.  (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.