<div class="section" id="the-import-statement">
<span id="from"></span><span id="import"></span><h2>The <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement</h2>
<pre id="index-31">
<strong id="grammar-token-import_stmt">import_stmt    </strong> ::=  &quot;import&quot; <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] ( &quot;,&quot; <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
                     | &quot;from&quot; <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> &quot;import&quot; <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
                     ( &quot;,&quot; <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
                     | &quot;from&quot; <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> &quot;import&quot; &quot;(&quot; <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
                     ( &quot;,&quot; <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> [&quot;as&quot; <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )* [&quot;,&quot;] &quot;)&quot;
                     | &quot;from&quot; <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> &quot;import&quot; &quot;*&quot;
<strong id="grammar-token-module">module         </strong> ::=  (<a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> &quot;.&quot;)* <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
<strong id="grammar-token-relative_module">relative_module</strong> ::=  &quot;.&quot;* <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> | &quot;.&quot;+
<strong id="grammar-token-name">name           </strong> ::=  <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a>
</pre>
<p>The basic import statement (no <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause) is executed in two
steps:</p>
<ol class="arabic simple">
<li>find a module, loading and initializing it if necessary</li>
<li>define a name or names in the local namespace for the scope where
the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</li>
</ol>
<p>When the statement contains multiple clauses (separated by
commas) the two steps are carried out separately for each clause, just
as though the clauses had been separated out into individiual import
statements.</p>
<p>The details of the first step, finding and loading modules are described in
greater detail in the section on the <a class="reference internal" href="import.html#importsystem"><em>import system</em></a>,
which also describes the various types of packages and modules that can
be imported, as well as all the hooks that can be used to customize
the import system. Note that failures in this step may indicate either
that the module could not be located, <em>or</em> that an error occurred while
initializing the module, which includes execution of the module&#8217;s code.</p>
<p>If the requested module is retrieved successfully, it will be made
available in the local namespace in one of three ways:</p>
<ul class="simple" id="index-32">
<li>If the module name is followed by <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a>, then the name
following <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> is bound directly to the imported module.</li>
<li>If no other name is specified, and the module being imported is a top
level module, the module&#8217;s name is bound in the local namespace as a
reference to the imported module</li>
<li>If the module being imported is <em>not</em> a top level module, then the name
of the top level package that contains the module is bound in the local
namespace as a reference to the top level package. The imported module
must be accessed using its full qualified name rather than directly</li>
</ul>
<p id="index-33">The <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> form uses a slightly more complex process:</p>
<ol class="arabic simple">
<li>find the module specified in the <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> clause, loading and
initializing it if necessary;</li>
<li>for each of the identifiers specified in the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> clauses:<ol class="arabic">
<li>check if the imported module has an attribute by that name</li>
<li>if not, attempt to import a submodule with that name and then
check the imported module again for that attribute</li>
<li>if the attribute is not found, <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> is raised.</li>
<li>otherwise, a reference to that value is stored in the local namespace,
using the name in the <a class="reference internal" href="compound_stmts.html#as"><tt class="xref std std-keyword docutils literal"><span class="pre">as</span></tt></a> clause if it is present,
otherwise using the attribute name</li>
</ol>
</li>
</ol>
<p>Examples:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">foo</span>                 <span class="c"># foo imported and bound locally</span>
<span class="kn">import</span> <span class="nn">foo.bar.baz</span>         <span class="c"># foo.bar.baz imported, foo bound locally</span>
<span class="kn">import</span> <span class="nn">foo.bar.baz</span> <span class="k">as</span> <span class="nn">fbb</span>  <span class="c"># foo.bar.baz imported and bound as fbb</span>
<span class="kn">from</span> <span class="nn">foo.bar</span> <span class="k">import</span> <span class="n">baz</span>    <span class="c"># foo.bar.baz imported and bound as baz</span>
<span class="kn">from</span> <span class="nn">foo</span> <span class="k">import</span> <span class="n">attr</span>       <span class="c"># foo imported and foo.attr bound as attr</span>
</pre></div>
</div>
<p>If the list of identifiers is replaced by a star (<tt class="docutils literal"><span class="pre">'*'</span></tt>), all public
names defined in the module are bound in the local namespace for the scope
where the <a class="reference internal" href="#import"><tt class="xref std std-keyword docutils literal"><span class="pre">import</span></tt></a> statement occurs.</p>
<p id="index-34">The <em>public names</em> defined by a module are determined by checking the module&#8217;s
namespace for a variable named <tt class="docutils literal"><span class="pre">__all__</span></tt>; if defined, it must be a sequence
of strings which are names defined or imported by that module.  The names
given in <tt class="docutils literal"><span class="pre">__all__</span></tt> are all considered public and are required to exist.  If
<tt class="docutils literal"><span class="pre">__all__</span></tt> is not defined, the set of public names includes all names found
in the module&#8217;s namespace which do not begin with an underscore character
(<tt class="docutils literal"><span class="pre">'_'</span></tt>).  <tt class="docutils literal"><span class="pre">__all__</span></tt> should contain the entire public API. It is intended
to avoid accidentally exporting items that are not part of the API (such as
library modules which were imported and used within the module).</p>
<p>The wild card form of import &#8212; <tt class="docutils literal"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></tt> &#8212; is only allowed at
the module level.  Attempting to use it in class or function definitions will
raise a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a>.</p>
<p id="index-35">When specifying what module to import you do not have to specify the absolute
name of the module. When a module or package is contained within another
package it is possible to make a relative import within the same top package
without having to mention the package name. By using leading dots in the
specified module or package after <a class="reference internal" href="#from"><tt class="xref std std-keyword docutils literal"><span class="pre">from</span></tt></a> you can specify how high to
traverse up the current package hierarchy without specifying exact names. One
leading dot means the current package where the module making the import
exists. Two dots means up one package level. Three dots is up two levels, etc.
So if you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">.</span> <span class="pre">import</span> <span class="pre">mod</span></tt> from a module in the <tt class="docutils literal"><span class="pre">pkg</span></tt> package
then you will end up importing <tt class="docutils literal"><span class="pre">pkg.mod</span></tt>. If you execute <tt class="docutils literal"><span class="pre">from</span> <span class="pre">..subpkg2</span>
<span class="pre">import</span> <span class="pre">mod</span></tt> from within <tt class="docutils literal"><span class="pre">pkg.subpkg1</span></tt> you will import <tt class="docutils literal"><span class="pre">pkg.subpkg2.mod</span></tt>.
The specification for relative imports is contained within <span class="target" id="index-36"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a>.</p>
<p><a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><tt class="xref py py-func docutils literal"><span class="pre">importlib.import_module()</span></tt></a> is provided to support applications that
determine dynamically the modules to be loaded.</p>
