mirror of
https://gitflic.ru/project/openide/openide.git
synced 2025-12-16 22:51:17 +07:00
c44fb89c28
Migrate to DocumentationMarkup elements GitOrigin-RevId: ea4d71638b1dd3a160521e655fd2a1670ea27701
97 lines
12 KiB
HTML
97 lines
12 KiB
HTML
<html><body><div class="content"><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> ::= "import" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] ( "," <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
|
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
|
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )*
|
|
| "from" <a class="reference internal" href="#grammar-token-relative_module"><tt class="xref docutils literal"><span class="pre">relative_module</span></tt></a> "import" "(" <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>]
|
|
( "," <a class="reference internal" href="lexical_analysis.html#grammar-token-identifier"><tt class="xref docutils literal"><span class="pre">identifier</span></tt></a> ["as" <a class="reference internal" href="#grammar-token-name"><tt class="xref docutils literal"><span class="pre">name</span></tt></a>] )* [","] ")"
|
|
| "from" <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> "import" "*"
|
|
<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> ".")* <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> ::= "."* <a class="reference internal" href="#grammar-token-module"><tt class="xref docutils literal"><span class="pre">module</span></tt></a> | "."+
|
|
<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’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’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’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’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 — <tt class="docutils literal"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">*</span></tt> — 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>
|
|
</div></body></html> |