[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / api / importing.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="marshalling-utils.html" />
<link rel="prev" href="processControl.html" />
<link rel="parent" href="utilities.html" />
<link rel="next" href="marshalling-utils.html" />
<meta name='aesop' content='information' />
<title>5.3 Importing Modules </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2 Process Control"
  href="processControl.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Utilities"
  href="utilities.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.4 Data marshalling support"
  href="marshalling-utils.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="processControl.html">5.2 Process Control</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="marshalling-utils.html">5.4 Data marshalling support</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION007300000000000000000"></A><A NAME="importing"></A>
<BR>
5.3 Importing Modules 
</H1>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-170' xml:id='l2h-170' class="cfunction">PyImport_ImportModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  This is a simplified interface to
  <tt class="cfunction">PyImport_ImportModuleEx()</tt> below, leaving the
  <var>globals</var> and <var>locals</var> arguments set to <tt class="constant">NULL</tt>.  When the
  <var>name</var> argument contains a dot (when it specifies a submodule of
  a package), the <var>fromlist</var> argument is set to the list
  <code>['*']</code> so that the return value is the named module rather
  than the top-level package containing it as would otherwise be the
  case.  (Unfortunately, this has an additional side effect when
  <var>name</var> in fact specifies a subpackage instead of a submodule:
  the submodules specified in the package's <code>__all__</code> variable
  are <a id='l2h-196' xml:id='l2h-196'></a>
  <a id='l2h-172' xml:id='l2h-172'></a>loaded.)  Return
  a new reference to the imported module, or <tt class="constant">NULL</tt> with an exception
  set on failure.  Before Python 2.4, the module may still be created in
  the failure case -- examine <code>sys.modules</code> to find out.  Starting
  with Python 2.4, a failing import of a module no longer leaves the
  module in <code>sys.modules</code>.
  
<span class="versionnote">Changed in version 2.4:
failing imports remove incomplete module objects.</span>

  <a id='l2h-174' xml:id='l2h-174'></a></dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-175' xml:id='l2h-175' class="cfunction">PyImport_ImportModuleEx</tt></b>(</nobr></td><td>char *<var>name</var>,
                       PyObject *<var>globals</var>, PyObject *<var>locals</var>, PyObject *<var>fromlist</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Import a module.  This is best described by referring to the
  built-in Python function
  <tt class="function">__import__()</tt><a id='l2h-176' xml:id='l2h-176'></a>, as the standard
  <tt class="function">__import__()</tt> function calls this function directly.

<P>
The return value is a new reference to the imported module or
  top-level package, or <tt class="constant">NULL</tt> with an exception set on failure (before
  Python 2.4, the
  module may still be created in this case).  Like for
  <tt class="function">__import__()</tt>, the return value when a submodule of a
  package was requested is normally the top-level package, unless a
  non-empty <var>fromlist</var> was given.
  
<span class="versionnote">Changed in version 2.4:
failing imports remove incomplete module objects.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-177' xml:id='l2h-177' class="cfunction">PyImport_Import</tt></b>(</nobr></td><td>PyObject *<var>name</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  This is a higher-level interface that calls the current ``import
  hook function''.  It invokes the <tt class="function">__import__()</tt> function
  from the <code>__builtins__</code> of the current globals.  This means
  that the import is done using whatever import hooks are installed in
  the current environment, e.g. by <tt class="module">rexec</tt><a id='l2h-197' xml:id='l2h-197'></a>
  or <tt class="module">ihooks</tt><a id='l2h-198' xml:id='l2h-198'></a>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-178' xml:id='l2h-178' class="cfunction">PyImport_ReloadModule</tt></b>(</nobr></td><td>PyObject *<var>m</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Reload a module.  This is best described by referring to the
  built-in Python function <tt class="function">reload()</tt><a id='l2h-179' xml:id='l2h-179'></a>, as
  the standard <tt class="function">reload()</tt> function calls this function
  directly.  Return a new reference to the reloaded module, or <tt class="constant">NULL</tt>
  with an exception set on failure (the module still exists in this
  case).
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-180' xml:id='l2h-180' class="cfunction">PyImport_AddModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  Return the module object corresponding to a module name.  The
  <var>name</var> argument may be of the form <code>package.module</code>.
  First check the modules dictionary if there's one there, and if not,
  create a new one and insert it in the modules dictionary.
  Return <tt class="constant">NULL</tt> with an exception set on failure.
  <span class="note"><b class="label">Note:</b>
This function does not load or import the module; if the
  module wasn't already loaded, you will get an empty module object.
  Use <tt class="cfunction">PyImport_ImportModule()</tt> or one of its variants to
  import a module.  Package structures implied by a dotted name for
  <var>name</var> are not created if not already present.</span>
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-181' xml:id='l2h-181' class="cfunction">PyImport_ExecCodeModule</tt></b>(</nobr></td><td>char *<var>name</var>, PyObject *<var>co</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Given a module name (possibly of the form <code>package.module</code>) and
  a code object read from a Python bytecode file or obtained from the
  built-in function <tt class="function">compile()</tt><a id='l2h-182' xml:id='l2h-182'></a>, load
  the module.  Return a new reference to the module object, or <tt class="constant">NULL</tt>
  with an exception set if an error occurred.  Before Python 2.4, the module
  could still be created in error cases.  Starting with Python 2.4,
  <var>name</var> is removed from <code>sys.modules</code> in error cases, and even
  if <var>name</var> was already in <code>sys.modules</code> on entry to
  <tt class="cfunction">PyImport_ExecCodeModule()</tt>.  Leaving incompletely initialized
  modules in <code>sys.modules</code> is dangerous, as imports of such modules
  have no way to know that the module object is an unknown (and probably
  damaged with respect to the module author's intents) state.

<P>
This function will reload the module if it was already imported.  See
  <tt class="cfunction">PyImport_ReloadModule()</tt> for the intended way to reload a
  module.

<P>
If <var>name</var> points to a dotted name of the
  form <code>package.module</code>, any package structures not already
  created will still not be created.

<P>

<span class="versionnote">Changed in version 2.4:
<var>name</var> is removed from <code>sys.modules</code> in error cases.</span>

<P>
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>long&nbsp;<b><tt id='l2h-183' xml:id='l2h-183' class="cfunction">PyImport_GetMagicNumber</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
  Return the magic number for Python bytecode files
  (a.k.a. <span class="file">.pyc</span> and <span class="file">.pyo</span> files).  The magic number should
  be present in the first four bytes of the bytecode file, in
  little-endian byte order.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-184' xml:id='l2h-184' class="cfunction">PyImport_GetModuleDict</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  Return the dictionary used for the module administration
  (a.k.a. <code>sys.modules</code>).  Note that this is a per-interpreter
  variable.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-185' xml:id='l2h-185' class="cfunction">_PyImport_Init</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
  Initialize the import mechanism.  For internal use only.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-186' xml:id='l2h-186' class="cfunction">PyImport_Cleanup</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
  Empty the module table.  For internal use only.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-187' xml:id='l2h-187' class="cfunction">_PyImport_Fini</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
  Finalize the import mechanism.  For internal use only.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-188' xml:id='l2h-188' class="cfunction">_PyImport_FindExtension</tt></b>(</nobr></td><td>char *, char *)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  For internal use only.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-189' xml:id='l2h-189' class="cfunction">_PyImport_FixupExtension</tt></b>(</nobr></td><td>char *, char *)</td></tr></table></dt>
<dd>
  For internal use only.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-190' xml:id='l2h-190' class="cfunction">PyImport_ImportFrozenModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
<dd>
  Load a frozen module named <var>name</var>.  Return <code>1</code> for success,
  <code>0</code> if the module is not found, and <code>-1</code> with an exception
  set if the initialization failed.  To access the imported module on
  a successful load, use <tt class="cfunction">PyImport_ImportModule()</tt>.  (Note
  the misnomer -- this function would reload the module if it was
  already imported.)
</dd></dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-191' xml:id='l2h-191'>struct _frozen</a></tt></b></dt>
<dd>
  This is the structure type definition for frozen module descriptors,
  as generated by the <b class="program">freeze</b><a id='l2h-199' xml:id='l2h-199'></a> utility
  (see <span class="file">Tools/freeze/</span> in the Python source distribution).  Its
  definition, found in <span class="file">Include/import.h</span>, is:

<P>
<div class="verbatim"><pre>
struct _frozen {
    char *name;
    unsigned char *code;
    int size;
};
</pre></div>
</dl>

<P>
<dl><dt>struct _frozen* <b><tt id='l2h-192' xml:id='l2h-192' class="cdata">PyImport_FrozenModules</tt></b></dt>
<dd>
  This pointer is initialized to point to an array of <tt class="ctype">struct
  _frozen</tt> records, terminated by one whose members are all <tt class="constant">NULL</tt> or
  zero.  When a frozen module is imported, it is searched in this
  table.  Third-party code could play tricks with this to provide a
  dynamically created collection of frozen modules.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-193' xml:id='l2h-193' class="cfunction">PyImport_AppendInittab</tt></b>(</nobr></td><td>char *<var>name</var>,
                                               void (*initfunc)(void))</td></tr></table></dt>
<dd>
  Add a single module to the existing table of built-in modules.  This
  is a convenience wrapper around
  <tt class="cfunction">PyImport_ExtendInittab()</tt>, returning <code>-1</code> if the
  table could not be extended.  The new module can be imported by the
  name <var>name</var>, and uses the function <var>initfunc</var> as the
  initialization function called on the first attempted import.  This
  should be called before <tt class="cfunction">Py_Initialize()</tt>.
</dd></dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-194' xml:id='l2h-194'>struct _inittab</a></tt></b></dt>
<dd>
  Structure describing a single entry in the list of built-in
  modules.  Each of these structures gives the name and initialization
  function for a module built into the interpreter.  Programs which
  embed Python may use an array of these structures in conjunction
  with <tt class="cfunction">PyImport_ExtendInittab()</tt> to provide additional
  built-in modules.  The structure is defined in
  <span class="file">Include/import.h</span> as:

<P>
<div class="verbatim"><pre>
struct _inittab {
    char *name;
    void (*initfunc)(void);
};
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-195' xml:id='l2h-195' class="cfunction">PyImport_ExtendInittab</tt></b>(</nobr></td><td>struct _inittab *<var>newtab</var>)</td></tr></table></dt>
<dd>
  Add a collection of modules to the table of built-in modules.  The
  <var>newtab</var> array must end with a sentinel entry which contains
  <tt class="constant">NULL</tt> for the <tt class="member">name</tt> field; failure to provide the sentinel
  value can result in a memory fault.  Returns <code>0</code> on success or
  <code>-1</code> if insufficient memory could be allocated to extend the
  internal table.  In the event of failure, no modules are added to
  the internal table.  This should be called before
  <tt class="cfunction">Py_Initialize()</tt>.
</dd></dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.2 Process Control"
  href="processControl.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Utilities"
  href="utilities.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.4 Data marshalling support"
  href="marshalling-utils.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="processControl.html">5.2 Process Control</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="marshalling-utils.html">5.4 Data marshalling support</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="api.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="api.html" title='Python/C API Reference Manual' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="marshalling-utils.html" />
	13	<link rel="prev" href="processControl.html" />
	14	<link rel="parent" href="utilities.html" />
	15	<link rel="next" href="marshalling-utils.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.3 Importing Modules </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="5.2 Process Control"
	25	href="processControl.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="5. Utilities"
	28	href="utilities.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="5.4 Data marshalling support"
	31	href="marshalling-utils.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python/C API Reference Manual</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="processControl.html">5.2 Process Control</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="marshalling-utils.html">5.4 Data marshalling support</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION007300000000000000000"></A><A NAME="importing"></A>
	56	<BR>
	57	5.3 Importing Modules
	58	</H1>
	59
	60	<P>
	61	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-170' xml:id='l2h-170' class="cfunction">PyImport_ImportModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
	62	<dd>
	63	<div class="refcount-info">
	64	<span class="label">Return value:</span>
65	<span class="value">New reference.</span>
66	</div>
67	This is a simplified interface to
68	<tt class="cfunction">PyImport_ImportModuleEx()</tt> below, leaving the
69	<var>globals</var> and <var>locals</var> arguments set to <tt class="constant">NULL</tt>. When the
70	<var>name</var> argument contains a dot (when it specifies a submodule of
71	a package), the <var>fromlist</var> argument is set to the list
72	<code>['*']</code> so that the return value is the named module rather
73	than the top-level package containing it as would otherwise be the
74	case. (Unfortunately, this has an additional side effect when
75	<var>name</var> in fact specifies a subpackage instead of a submodule:
76	the submodules specified in the package's <code>__all__</code> variable
77	are <a id='l2h-196' xml:id='l2h-196'></a>
78	<a id='l2h-172' xml:id='l2h-172'></a>loaded.) Return
79	a new reference to the imported module, or <tt class="constant">NULL</tt> with an exception
80	set on failure. Before Python 2.4, the module may still be created in
81	the failure case -- examine <code>sys.modules</code> to find out. Starting
82	with Python 2.4, a failing import of a module no longer leaves the
83	module in <code>sys.modules</code>.
84
85	<span class="versionnote">Changed in version 2.4:
86	failing imports remove incomplete module objects.</span>
87
88	<a id='l2h-174' xml:id='l2h-174'></a></dd></dl>
89
90	<P>
91	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-175' xml:id='l2h-175' class="cfunction">PyImport_ImportModuleEx</tt></b>(</nobr></td><td>char *<var>name</var>,
92	PyObject <var>globals</var>, PyObject <var>locals</var>, PyObject *<var>fromlist</var>)</td></tr></table></dt>
93	<dd>
94	<div class="refcount-info">
95	<span class="label">Return value:</span>
96	<span class="value">New reference.</span>
97	</div>
98	Import a module. This is best described by referring to the
99	built-in Python function
100	<tt class="function">__import__()</tt><a id='l2h-176' xml:id='l2h-176'></a>, as the standard
101	<tt class="function">__import__()</tt> function calls this function directly.
102
103	<P>
104	The return value is a new reference to the imported module or
105	top-level package, or <tt class="constant">NULL</tt> with an exception set on failure (before
106	Python 2.4, the
107	module may still be created in this case). Like for
108	<tt class="function">__import__()</tt>, the return value when a submodule of a
109	package was requested is normally the top-level package, unless a
110	non-empty <var>fromlist</var> was given.
111
112	<span class="versionnote">Changed in version 2.4:
113	failing imports remove incomplete module objects.</span>
114
115	</dd></dl>
116
117	<P>
118	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-177' xml:id='l2h-177' class="cfunction">PyImport_Import</tt></b>(</nobr></td><td>PyObject *<var>name</var>)</td></tr></table></dt>
119	<dd>
120	<div class="refcount-info">
121	<span class="label">Return value:</span>
122	<span class="value">New reference.</span>
123	</div>
124	This is a higher-level interface that calls the current ``import
125	hook function''. It invokes the <tt class="function">__import__()</tt> function
126	from the <code>__builtins__</code> of the current globals. This means
127	that the import is done using whatever import hooks are installed in
128	the current environment, e.g. by <tt class="module">rexec</tt><a id='l2h-197' xml:id='l2h-197'></a>
129	or <tt class="module">ihooks</tt><a id='l2h-198' xml:id='l2h-198'></a>.
130	</dd></dl>
131
132	<P>
133	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-178' xml:id='l2h-178' class="cfunction">PyImport_ReloadModule</tt></b>(</nobr></td><td>PyObject *<var>m</var>)</td></tr></table></dt>
134	<dd>
135	<div class="refcount-info">
136	<span class="label">Return value:</span>
137	<span class="value">New reference.</span>
138	</div>
139	Reload a module. This is best described by referring to the
140	built-in Python function <tt class="function">reload()</tt><a id='l2h-179' xml:id='l2h-179'></a>, as
141	the standard <tt class="function">reload()</tt> function calls this function
142	directly. Return a new reference to the reloaded module, or <tt class="constant">NULL</tt>
143	with an exception set on failure (the module still exists in this
144	case).
145	</dd></dl>
146
147	<P>
148	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-180' xml:id='l2h-180' class="cfunction">PyImport_AddModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
149	<dd>
150	<div class="refcount-info">
151	<span class="label">Return value:</span>
152	<span class="value">Borrowed reference.</span>
153	</div>
154	Return the module object corresponding to a module name. The
155	<var>name</var> argument may be of the form <code>package.module</code>.
156	First check the modules dictionary if there's one there, and if not,
157	create a new one and insert it in the modules dictionary.
158	Return <tt class="constant">NULL</tt> with an exception set on failure.
159	<span class="note"><b class="label">Note:</b>
160	This function does not load or import the module; if the
161	module wasn't already loaded, you will get an empty module object.
162	Use <tt class="cfunction">PyImport_ImportModule()</tt> or one of its variants to
163	import a module. Package structures implied by a dotted name for
164	<var>name</var> are not created if not already present.</span>
165	</dd></dl>
166
167	<P>
168	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-181' xml:id='l2h-181' class="cfunction">PyImport_ExecCodeModule</tt></b>(</nobr></td><td>char <var>name</var>, PyObject <var>co</var>)</td></tr></table></dt>
169	<dd>
170	<div class="refcount-info">
171	<span class="label">Return value:</span>
172	<span class="value">New reference.</span>
173	</div>
174	Given a module name (possibly of the form <code>package.module</code>) and
175	a code object read from a Python bytecode file or obtained from the
176	built-in function <tt class="function">compile()</tt><a id='l2h-182' xml:id='l2h-182'></a>, load
177	the module. Return a new reference to the module object, or <tt class="constant">NULL</tt>
178	with an exception set if an error occurred. Before Python 2.4, the module
179	could still be created in error cases. Starting with Python 2.4,
180	<var>name</var> is removed from <code>sys.modules</code> in error cases, and even
181	if <var>name</var> was already in <code>sys.modules</code> on entry to
182	<tt class="cfunction">PyImport_ExecCodeModule()</tt>. Leaving incompletely initialized
183	modules in <code>sys.modules</code> is dangerous, as imports of such modules
184	have no way to know that the module object is an unknown (and probably
185	damaged with respect to the module author's intents) state.
186
187	<P>
188	This function will reload the module if it was already imported. See
189	<tt class="cfunction">PyImport_ReloadModule()</tt> for the intended way to reload a
190	module.
191
192	<P>
193	If <var>name</var> points to a dotted name of the
194	form <code>package.module</code>, any package structures not already
195	created will still not be created.
196
197	<P>
198
199	<span class="versionnote">Changed in version 2.4:
200	<var>name</var> is removed from <code>sys.modules</code> in error cases.</span>
201
202	<P>
203	</dd></dl>
204
205	<P>
206	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>long <b><tt id='l2h-183' xml:id='l2h-183' class="cfunction">PyImport_GetMagicNumber</tt></b>(</nobr></td><td>)</td></tr></table></dt>
207	<dd>
208	Return the magic number for Python bytecode files
209	(a.k.a. <span class="file">.pyc</span> and <span class="file">.pyo</span> files). The magic number should
210	be present in the first four bytes of the bytecode file, in
211	little-endian byte order.
212	</dd></dl>
213
214	<P>
215	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-184' xml:id='l2h-184' class="cfunction">PyImport_GetModuleDict</tt></b>(</nobr></td><td>)</td></tr></table></dt>
216	<dd>
217	<div class="refcount-info">
218	<span class="label">Return value:</span>
219	<span class="value">Borrowed reference.</span>
220	</div>
221	Return the dictionary used for the module administration
222	(a.k.a. <code>sys.modules</code>). Note that this is a per-interpreter
223	variable.
224	</dd></dl>
225
226	<P>
227	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-185' xml:id='l2h-185' class="cfunction">_PyImport_Init</tt></b>(</nobr></td><td>)</td></tr></table></dt>
228	<dd>
229	Initialize the import mechanism. For internal use only.
230	</dd></dl>
231
232	<P>
233	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-186' xml:id='l2h-186' class="cfunction">PyImport_Cleanup</tt></b>(</nobr></td><td>)</td></tr></table></dt>
234	<dd>
235	Empty the module table. For internal use only.
236	</dd></dl>
237
238	<P>
239	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-187' xml:id='l2h-187' class="cfunction">_PyImport_Fini</tt></b>(</nobr></td><td>)</td></tr></table></dt>
240	<dd>
241	Finalize the import mechanism. For internal use only.
242	</dd></dl>
243
244	<P>
245	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-188' xml:id='l2h-188' class="cfunction">_PyImport_FindExtension</tt></b>(</nobr></td><td>char , char )</td></tr></table></dt>
246	<dd>
247	<div class="refcount-info">
248	<span class="label">Return value:</span>
249	<span class="value">Borrowed reference.</span>
250	</div>
251	For internal use only.
252	</dd></dl>
253
254	<P>
255	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-189' xml:id='l2h-189' class="cfunction">_PyImport_FixupExtension</tt></b>(</nobr></td><td>char , char )</td></tr></table></dt>
256	<dd>
257	For internal use only.
258	</dd></dl>
259
260	<P>
261	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-190' xml:id='l2h-190' class="cfunction">PyImport_ImportFrozenModule</tt></b>(</nobr></td><td>char *<var>name</var>)</td></tr></table></dt>
262	<dd>
263	Load a frozen module named <var>name</var>. Return <code>1</code> for success,
264	<code>0</code> if the module is not found, and <code>-1</code> with an exception
265	set if the initialization failed. To access the imported module on
266	a successful load, use <tt class="cfunction">PyImport_ImportModule()</tt>. (Note
267	the misnomer -- this function would reload the module if it was
268	already imported.)
269	</dd></dl>
270
271	<P>
272	<dl><dt><b><tt class="ctype"><a id='l2h-191' xml:id='l2h-191'>struct _frozen</a></tt></b></dt>
273	<dd>
274	This is the structure type definition for frozen module descriptors,
275	as generated by the <b class="program">freeze</b><a id='l2h-199' xml:id='l2h-199'></a> utility
276	(see <span class="file">Tools/freeze/</span> in the Python source distribution). Its
277	definition, found in <span class="file">Include/import.h</span>, is:
278
279	<P>
280	<div class="verbatim"><pre>
281	struct _frozen {
282	char *name;
283	unsigned char *code;
284	int size;
285	};
286	</pre></div>
287	</dl>
288
289	<P>
290	<dl><dt>struct _frozen* <b><tt id='l2h-192' xml:id='l2h-192' class="cdata">PyImport_FrozenModules</tt></b></dt>
291	<dd>
292	This pointer is initialized to point to an array of <tt class="ctype">struct
293	_frozen</tt> records, terminated by one whose members are all <tt class="constant">NULL</tt> or
294	zero. When a frozen module is imported, it is searched in this
295	table. Third-party code could play tricks with this to provide a
296	dynamically created collection of frozen modules.
297	</dd></dl>
298
299	<P>
300	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-193' xml:id='l2h-193' class="cfunction">PyImport_AppendInittab</tt></b>(</nobr></td><td>char *<var>name</var>,
301	void (*initfunc)(void))</td></tr></table></dt>
302	<dd>
303	Add a single module to the existing table of built-in modules. This
304	is a convenience wrapper around
305	<tt class="cfunction">PyImport_ExtendInittab()</tt>, returning <code>-1</code> if the
306	table could not be extended. The new module can be imported by the
307	name <var>name</var>, and uses the function <var>initfunc</var> as the
308	initialization function called on the first attempted import. This
309	should be called before <tt class="cfunction">Py_Initialize()</tt>.
310	</dd></dl>
311
312	<P>
313	<dl><dt><b><tt class="ctype"><a id='l2h-194' xml:id='l2h-194'>struct _inittab</a></tt></b></dt>
314	<dd>
315	Structure describing a single entry in the list of built-in
316	modules. Each of these structures gives the name and initialization
317	function for a module built into the interpreter. Programs which
318	embed Python may use an array of these structures in conjunction
319	with <tt class="cfunction">PyImport_ExtendInittab()</tt> to provide additional
320	built-in modules. The structure is defined in
321	<span class="file">Include/import.h</span> as:
322
323	<P>
324	<div class="verbatim"><pre>
325	struct _inittab {
326	char *name;
327	void (*initfunc)(void);
328	};
329	</pre></div>
330	</dl>
331
332	<P>
333	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-195' xml:id='l2h-195' class="cfunction">PyImport_ExtendInittab</tt></b>(</nobr></td><td>struct _inittab *<var>newtab</var>)</td></tr></table></dt>
334	<dd>
335	Add a collection of modules to the table of built-in modules. The
336	<var>newtab</var> array must end with a sentinel entry which contains
337	<tt class="constant">NULL</tt> for the <tt class="member">name</tt> field; failure to provide the sentinel
338	value can result in a memory fault. Returns <code>0</code> on success or
339	<code>-1</code> if insufficient memory could be allocated to extend the
340	internal table. In the event of failure, no modules are added to
341	the internal table. This should be called before
342	<tt class="cfunction">Py_Initialize()</tt>.
343	</dd></dl>
344
345	<P>
346
347	<DIV CLASS="navigation">
348	<div class='online-navigation'>
349	<p></p><hr />
350	<table align="center" width="100%" cellpadding="0" cellspacing="2">
351	<tr>
352	<td class='online-navigation'><a rel="prev" title="5.2 Process Control"
353	href="processControl.html"><img src='../icons/previous.png'
354	border='0' height='32' alt='Previous Page' width='32' /></A></td>
355	<td class='online-navigation'><a rel="parent" title="5. Utilities"
356	href="utilities.html"><img src='../icons/up.png'
357	border='0' height='32' alt='Up One Level' width='32' /></A></td>
358	<td class='online-navigation'><a rel="next" title="5.4 Data marshalling support"
359	href="marshalling-utils.html"><img src='../icons/next.png'
360	border='0' height='32' alt='Next Page' width='32' /></A></td>
361	<td align="center" width="100%">Python/C API Reference Manual</td>
362	<td class='online-navigation'><a rel="contents" title="Table of Contents"
363	href="contents.html"><img src='../icons/contents.png'
364	border='0' height='32' alt='Contents' width='32' /></A></td>
365	<td class='online-navigation'><img src='../icons/blank.png'
366	border='0' height='32' alt='' width='32' /></td>
367	<td class='online-navigation'><a rel="index" title="Index"
368	href="genindex.html"><img src='../icons/index.png'
369	border='0' height='32' alt='Index' width='32' /></A></td>
370	</tr></table>
371	<div class='online-navigation'>
372	<b class="navlabel">Previous:</b>
373	<a class="sectref" rel="prev" href="processControl.html">5.2 Process Control</A>
374	<b class="navlabel">Up:</b>
375	<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
376	<b class="navlabel">Next:</b>
377	<a class="sectref" rel="next" href="marshalling-utils.html">5.4 Data marshalling support</A>
378	</div>
379	</div>
380	<hr />
381	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
382	</DIV>
383	<!--End of Navigation Panel-->
384	<ADDRESS>
385	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
386	</ADDRESS>
387	</BODY>
388	</HTML>