1 line
13 KiB
HTML
Executable file
1 line
13 KiB
HTML
Executable file
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html><head><link rel="STYLESHEET" href="ref.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="ref.html" title='Python 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="global.html" /><link rel="prev" href="continue.html" /><link rel="parent" href="simple.html" /><link rel="next" href="future.html" /><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta name='aesop' content='information' /><title>6.12 The import statement </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="6.11 the continue statement" href="continue.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="6. simple statements" href="simple.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="6.12.1 future statements" href="future.html"><img src='../icons/next.png' border='0' height='32' alt='Next Page' width='32' /></a></td><td align="center" width="100%">Python 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="continue.html">6.11 The continue statement</a><b class="navlabel">Up:</b><a class="sectref" rel="parent" href="simple.html">6. Simple statements</a><b class="navlabel">Next:</b><a class="sectref" rel="next" href="future.html">6.12.1 Future statements</a></div><hr /></div></div><!--End of Navigation Panel--><h1><a name="SECTION0081200000000000000000"></a><a name="import"></a><br>6.12 The <tt class="keyword">import</tt> statement </h1><a id='l2h-535' xml:id='l2h-535'></a><a id='l2h-556' xml:id='l2h-556'></a><a id='l2h-536' xml:id='l2h-536'></a><a id='l2h-537' xml:id='l2h-537'></a><p><dl><dd class="grammar"><div class="productions"><table><tr> <td><a id='tok-import_stmt' xml:id='tok-import_stmt'>import_stmt</a></td> <td>::=</td> <td>"import" <a class='grammartoken' href="import.html#tok-module">module</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] ( "," <a class='grammartoken' href="import.html#tok-module">module</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )*</td></tr> <tr> <td></td> <td></td> <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>]</code></td></tr> <tr> <td></td> <td></td> <td><code>( "," <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )*</code></td></tr> <tr> <td></td> <td></td> <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" "(" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>]</code></td></tr> <tr> <td></td> <td></td> <td><code>( "," <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )* [","] ")"</code></td></tr> <tr> <td></td> <td></td> <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" "*"</code></td></tr> <tr> <td><a id='tok-module' xml:id='tok-module'>module</a></td> <td>::=</td> <td>(<a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ".")* <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></td></tr></table></div><a class="grammar-footer" href="grammar.txt" type="text/plain" >Download entire grammar as text.</a></dd></dl><p>Import statements are executed in two steps: (1) find a module, andinitialize it if necessary; (2) define a name or names in the localnamespace (of the scope where the <tt class="keyword">import</tt> statement occurs).The first form (without <tt class="keyword">from</tt>) repeats these steps for eachidentifier in the list. The form with <tt class="keyword">from</tt> performs step(1) once, and then performs step (2) repeatedly.<p>In this context, to ``initialize'' a built-in or extension module means tocall an initialization function that the module must provide for the purpose(in the reference implementation, the function's name is obtained byprepending string ``init'' to the module's name); to ``initialize'' aPython-coded module means to execute the module's body.<p>The system maintains a table of modules that have been or are beinginitialized,indexed by module name. This table isaccessible as <code>sys.modules</code>. When a module name is found inthis table, step (1) is finished. If not, a search for a moduledefinition is started. When a module is found, it is loaded. Detailsof the module searching and loading process are implementation andplatform specific. It generally involves searching for a ``built-in''module with the given name and then searching a list of locationsgiven as <code>sys.path</code>.<a id='l2h-539' xml:id='l2h-539'></a><a id='l2h-557' xml:id='l2h-557'></a><a id='l2h-540' xml:id='l2h-540'></a><a id='l2h-541' xml:id='l2h-541'></a><a id='l2h-542' xml:id='l2h-542'></a><a id='l2h-558' xml:id='l2h-558'></a><a id='l2h-543' xml:id='l2h-543'></a><a id='l2h-544' xml:id='l2h-544'></a><p>If a built-in module is found,<a id='l2h-545' xml:id='l2h-545'></a> itsbuilt-in initialization code is executed and step (1) is finished. Ifno matching file is found,<tt class="exception">ImportError</tt><a id='l2h-546' xml:id='l2h-546'></a> is raised.<a id='l2h-559' xml:id='l2h-559'></a>If a file is found, it is parsed,yielding an executable code block. If a syntax error occurs,<tt class="exception">SyntaxError</tt><a id='l2h-547' xml:id='l2h-547'></a> is raised. Otherwise, anempty module of the given name is created and inserted in the moduletable, and then the code block is executed in the context of thismodule. Exceptions during this execution terminate step (1).<p>When step (1) finishes without raising an exception, step (2) canbegin.<p>The first form of <tt class="keyword">import</tt> statement binds the module name inthe local namespace to the module object, and then goes on to importthe next identifier, if any. If the module name is followed by<tt class="keyword">as</tt>, the name following <tt class="keyword">as</tt> is used as the localname for the module. <p>The <tt class="keyword">from</tt> form does not bind the module name: it goes through thelist of identifiers, looks each one of them up in the module found in step(1), and binds the name in the local namespace to the object thus found. As with the first form of <tt class="keyword">import</tt>, an alternate local name can besupplied by specifying "<tt class="keyword">as</tt> localname". If a name is not found,<tt class="exception">ImportError</tt> is raised. If the list of identifiers is replacedby a star ("<tt class="character">*</tt>"), all public names defined in the module arebound in the local namespace of the <tt class="keyword">import</tt> statement..<a id='l2h-548' xml:id='l2h-548'></a><a id='l2h-549' xml:id='l2h-549'></a><p>The <em>public names</em> defined by a module are determined by checkingthe module's namespace for a variable named <code>__all__</code>; ifdefined, it must be a sequence of strings which are names defined orimported by that module. The names given in <code>__all__</code> are allconsidered public and are required to exist. If <code>__all__</code> is notdefined, the set of public names includes all names found in themodule's namespace which do not begin with an underscore character("<tt class="character">_</tt>"). <code>__all__</code> should contain the entire public API.It is intended to avoid accidentally exporting items that are not partof the API (such as library modules which were imported and used withinthe module).<a id='l2h-551' xml:id='l2h-551'></a><p>The <tt class="keyword">from</tt> form with "<tt class="samp">*</tt>" may only occur in a modulescope. If the wild card form of import -- "<tt class="samp">import *</tt>" -- isused in a function and the function contains or is a nested block withfree variables, the compiler will raise a <tt class="exception">SyntaxError</tt>.<p><a id='l2h-552' xml:id='l2h-552'></a><a id='l2h-553' xml:id='l2h-553'></a><p><strong>Hierarchical module names:</strong><a id='l2h-554' xml:id='l2h-554'></a>when the module names contains one or more dots, the module searchpath is carried out differently. The sequence of identifiers up tothe last dot is used to find a ``package''<a id='l2h-560' xml:id='l2h-560'></a>; the finalidentifier is then searched inside the package. A package isgenerally a subdirectory of a directory on <code>sys.path</code> that has afile <span class="file">__init__.py</span>.<a id='l2h-561' xml:id='l2h-561'></a>[XXX Can't be bothered to spell this out right now; see the URL<a class="url" href="http://www.python.org/doc/essays/packages.html">http://www.python.org/doc/essays/packages.html</a> for more details, alsoabout how the module search works from inside a package.]<p>The built-in function <tt class="function">__import__()</tt> is provided to supportapplications that determine which modules need to be loadeddynamically; refer to <a class="ulink" href="../lib/built-in-funcs.html" >Built-inFunctions</a> in the<em class="citetitle"><a href="../lib/lib.html" title="Python Library Reference" >Python Library Reference</a></em> for additionalinformation.<a id='l2h-555' xml:id='l2h-555'></a><p><p><br /></p><hr class='online-navigation' /><div class='online-navigation'><!--Table of Child-Links--><a name="CHILD_LINKS"><strong>Subsections</strong></a><ul class="ChildLinks"><li><a href="future.html">6.12.1 Future statements</a></ul><!--End of Table of Child-Links--></div><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="6.11 the continue statement" href="continue.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="6. simple statements" href="simple.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="6.12.1 future statements" href="future.html"><img src='../icons/next.png' border='0' height='32' alt='Next Page' width='32' /></a></td><td align="center" width="100%">Python 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="continue.html">6.11 The continue statement</a><b class="navlabel">Up:</b><a class="sectref" rel="parent" href="simple.html">6. Simple statements</a><b class="navlabel">Next:</b><a class="sectref" rel="next" href="future.html">6.12.1 Future statements</a></div></div><hr /><span class="release-info">Release 2.5, documentation updated on 19th September, 2006.</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>
|