<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>1.4 Embedding Python </TITLE>
<META NAME="description" CONTENT="1.4 Embedding Python ">
<META NAME="keywords" CONTENT="api">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="api.css">
<LINK REL="previous" HREF="exceptions.html">
<LINK REL="up" HREF="intro.html">
<LINK REL="next" HREF="veryhigh.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="veryhigh.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="intro.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="exceptions.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python/C API Reference Manual</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="veryhigh.html">2. The Very High</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="intro.html">1. Introduction</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="exceptions.html">1.3 Exceptions</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003400000000000000000"></A>
<BR>
1.4 Embedding Python 
</H1>

<P>
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.

<P>
The basic initialization function is <tt class=cfunction>Py_Initialize()</tt>.
This initializes the table of loaded modules, and creates the
fundamental modules <tt class=module>__builtin__</tt><a name="l2h-1"></a>,
<tt class=module>__main__</tt><a name="l2h-2"></a> and 
<tt class=module>sys</tt><a name="l2h-3"></a>.  It also initializes the module
search path (<tt>sys.path</tt>).<a name="l2h-4"></a>

<P>
<tt class=cfunction>Py_Initialize()</tt> does not set the ``script argument list'' 
(<tt>sys.argv</tt>).  If this variable is needed by Python code that 
will be executed later, it must be set explicitly with a call to 
<tt>PySys_SetArgv(<var>argc</var>, <var>argv</var>)</tt> subsequent to the call 
to <tt class=cfunction>Py_Initialize()</tt>.

<P>
On most systems (in particular, on Unix and Windows, although the
details are slightly different), <tt class=cfunction>Py_Initialize()</tt>
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
<tt class=file>lib/python1.5</tt> (replacing <tt class=file>1.5</tt> with the current
interpreter version) relative to the parent directory where the
executable named <tt class=file>python</tt> is found on the shell command search
path (the environment variable <span class=envvar><a name="l2h-5">$PATH</a></span>).

<P>
For instance, if the Python executable is found in
<tt class=file>/usr/local/bin/python</tt>, it will assume that the libraries are in
<tt class=file>/usr/local/lib/python1.5</tt>.  (In fact, this particular path
is also the ``fallback'' location, used when no executable file named
<tt class=file>python</tt> is found along <span class=envvar><a name="l2h-6">$PATH</a></span>.)  The user can override
this behavior by setting the environment variable <span class=envvar><a name="l2h-7">$PYTHONHOME</a></span>,
or insert additional directories in front of the standard path by
setting <span class=envvar><a name="l2h-8">$PYTHONPATH</a></span>.

<P>
The embedding application can steer the search by calling 
<tt>Py_SetProgramName(<var>file</var>)</tt> <i>before</i> calling 
<tt class=cfunction>Py_Initialize()</tt>.  Note that <span class=envvar><a name="l2h-9">$PYTHONHOME</a></span> still
overrides this and <span class=envvar><a name="l2h-10">$PYTHONPATH</a></span> is still inserted in front of
the standard path.  An application that requires total control has to
provide its own implementation of <tt class=cfunction>Py_GetPath()</tt>,
<tt class=cfunction>Py_GetPrefix()</tt>, <tt class=cfunction>Py_GetExecPrefix()</tt>,
<tt class=cfunction>Py_GetProgramFullPath()</tt> (all defined in
<tt class=file>Modules/getpath.c</tt>).

<P>
Sometimes, it is desirable to ``uninitialize'' Python.  For instance, 
the application may want to start over (make another call to 
<tt class=cfunction>Py_Initialize()</tt>) 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 <tt class=cfunction>Py_Finalize()</tt>.  The function
<tt class=cfunction>Py_IsInitialized()</tt> returns true iff Python is currently in the
initialized state.  More information about these functions is given in
a later chapter.

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="veryhigh.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="intro.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="exceptions.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python/C API Reference Manual</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="veryhigh.html">2. The Very High</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="intro.html">1. Introduction</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="exceptions.html">1.3 Exceptions</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
