1135 lines
118 KiB
HTML
1135 lines
118 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>5. The import system — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="6. Expressions" href="expressions.html" />
|
|||
|
|
<link rel="prev" title="4. Execution model" href="executionmodel.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/reference/import.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="expressions.html" title="6. Expressions"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="executionmodel.html" title="4. Execution model"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Language Reference</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="the-import-system">
|
|||
|
|
<span id="importsystem"></span><h1>5. The import system<a class="headerlink" href="#the-import-system" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p id="index-0">Python code in one <a class="reference internal" href="../glossary.html#term-module"><span class="xref std std-term">module</span></a> gains access to the code in another module
|
|||
|
|
by the process of <a class="reference internal" href="../glossary.html#term-importing"><span class="xref std std-term">importing</span></a> it. The <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement is
|
|||
|
|
the most common way of invoking the import machinery, but it is not the only
|
|||
|
|
way. Functions such as <a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a> and built-in
|
|||
|
|
<a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> can also be used to invoke the import machinery.</p>
|
|||
|
|
<p>The <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement combines two operations; it searches for the
|
|||
|
|
named module, then it binds the results of that search to a name in the local
|
|||
|
|
scope. The search operation of the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement is defined as
|
|||
|
|
a call to the <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function, with the appropriate arguments.
|
|||
|
|
The return value of <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> is used to perform the name
|
|||
|
|
binding operation of the <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement. See the
|
|||
|
|
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code> statement for the exact details of that name binding
|
|||
|
|
operation.</p>
|
|||
|
|
<p>A direct call to <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> performs only the module search and, if
|
|||
|
|
found, the module creation operation. While certain side-effects may occur,
|
|||
|
|
such as the importing of parent packages, and the updating of various caches
|
|||
|
|
(including <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>), only the <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement performs
|
|||
|
|
a name binding operation.</p>
|
|||
|
|
<p>When an <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement is executed, the standard builtin
|
|||
|
|
<a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function is called. Other mechanisms for invoking the
|
|||
|
|
import system (such as <a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a>) may choose to bypass
|
|||
|
|
<a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> and use their own solutions to implement import semantics.</p>
|
|||
|
|
<p>When a module is first imported, Python searches for the module and if found,
|
|||
|
|
it creates a module object <a class="footnote-reference brackets" href="#fnmo" id="id1">1</a>, initializing it. If the named module
|
|||
|
|
cannot be found, a <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> is raised. Python implements various
|
|||
|
|
strategies to search for the named module when the import machinery is
|
|||
|
|
invoked. These strategies can be modified and extended by using various hooks
|
|||
|
|
described in the sections below.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>The import system has been updated to fully implement the second phase
|
|||
|
|
of <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>. There is no longer any implicit import machinery - the full
|
|||
|
|
import system is exposed through <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>. In addition,
|
|||
|
|
native namespace package support has been implemented (see <span class="target" id="index-2"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a>).</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="importlib">
|
|||
|
|
<h2>5.1. <a class="reference internal" href="../library/importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a><a class="headerlink" href="#importlib" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The <a class="reference internal" href="../library/importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> module provides a rich API for interacting with the
|
|||
|
|
import system. For example <a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a> provides a
|
|||
|
|
recommended, simpler API than built-in <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> for invoking the
|
|||
|
|
import machinery. Refer to the <a class="reference internal" href="../library/importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a> library documentation for
|
|||
|
|
additional detail.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="packages">
|
|||
|
|
<h2>5.2. Packages<a class="headerlink" href="#packages" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p id="index-3">Python has only one type of module object, and all modules are of this type,
|
|||
|
|
regardless of whether the module is implemented in Python, C, or something
|
|||
|
|
else. To help organize modules and provide a naming hierarchy, Python has a
|
|||
|
|
concept of <a class="reference internal" href="../glossary.html#term-package"><span class="xref std std-term">packages</span></a>.</p>
|
|||
|
|
<p>You can think of packages as the directories on a file system and modules as
|
|||
|
|
files within directories, but don’t take this analogy too literally since
|
|||
|
|
packages and modules need not originate from the file system. For the
|
|||
|
|
purposes of this documentation, we’ll use this convenient analogy of
|
|||
|
|
directories and files. Like file system directories, packages are organized
|
|||
|
|
hierarchically, and packages may themselves contain subpackages, as well as
|
|||
|
|
regular modules.</p>
|
|||
|
|
<p>It’s important to keep in mind that all packages are modules, but not all
|
|||
|
|
modules are packages. Or put another way, packages are just a special kind of
|
|||
|
|
module. Specifically, any module that contains a <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute is
|
|||
|
|
considered a package.</p>
|
|||
|
|
<p>All modules have a name. Subpackage names are separated from their parent
|
|||
|
|
package name by dots, akin to Python’s standard attribute access syntax. Thus
|
|||
|
|
you might have a module called <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> and a package called <a class="reference internal" href="../library/email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code></a>,
|
|||
|
|
which in turn has a subpackage called <a class="reference internal" href="../library/email.mime.html#module-email.mime" title="email.mime: Build MIME messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.mime</span></code></a> and a module within
|
|||
|
|
that subpackage called <code class="xref py py-mod docutils literal notranslate"><span class="pre">email.mime.text</span></code>.</p>
|
|||
|
|
<div class="section" id="regular-packages">
|
|||
|
|
<h3>5.2.1. Regular packages<a class="headerlink" href="#regular-packages" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-4">Python defines two types of packages, <a class="reference internal" href="../glossary.html#term-regular-package"><span class="xref std std-term">regular packages</span></a> and <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a>. Regular
|
|||
|
|
packages are traditional packages as they existed in Python 3.2 and earlier.
|
|||
|
|
A regular package is typically implemented as a directory containing an
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file. When a regular package is imported, this
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file is implicitly executed, and the objects it defines are
|
|||
|
|
bound to names in the package’s namespace. The <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file can
|
|||
|
|
contain the same Python code that any other module can contain, and Python
|
|||
|
|
will add some additional attributes to the module when it is imported.</p>
|
|||
|
|
<p>For example, the following file system layout defines a top level <code class="docutils literal notranslate"><span class="pre">parent</span></code>
|
|||
|
|
package with three subpackages:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parent</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">one</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">two</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">three</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Importing <code class="docutils literal notranslate"><span class="pre">parent.one</span></code> will implicitly execute <code class="docutils literal notranslate"><span class="pre">parent/__init__.py</span></code> and
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">parent/one/__init__.py</span></code>. Subsequent imports of <code class="docutils literal notranslate"><span class="pre">parent.two</span></code> or
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">parent.three</span></code> will execute <code class="docutils literal notranslate"><span class="pre">parent/two/__init__.py</span></code> and
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">parent/three/__init__.py</span></code> respectively.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="namespace-packages">
|
|||
|
|
<h3>5.2.2. Namespace packages<a class="headerlink" href="#namespace-packages" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-5">A namespace package is a composite of various <a class="reference internal" href="../glossary.html#term-portion"><span class="xref std std-term">portions</span></a>,
|
|||
|
|
where each portion contributes a subpackage to the parent package. Portions
|
|||
|
|
may reside in different locations on the file system. Portions may also be
|
|||
|
|
found in zip files, on the network, or anywhere else that Python searches
|
|||
|
|
during import. Namespace packages may or may not correspond directly to
|
|||
|
|
objects on the file system; they may be virtual modules that have no concrete
|
|||
|
|
representation.</p>
|
|||
|
|
<p>Namespace packages do not use an ordinary list for their <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
attribute. They instead use a custom iterable type which will automatically
|
|||
|
|
perform a new search for package portions on the next import attempt within
|
|||
|
|
that package if the path of their parent package (or <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> for a
|
|||
|
|
top level package) changes.</p>
|
|||
|
|
<p>With namespace packages, there is no <code class="docutils literal notranslate"><span class="pre">parent/__init__.py</span></code> file. In fact,
|
|||
|
|
there may be multiple <code class="docutils literal notranslate"><span class="pre">parent</span></code> directories found during import search, where
|
|||
|
|
each one is provided by a different portion. Thus <code class="docutils literal notranslate"><span class="pre">parent/one</span></code> may not be
|
|||
|
|
physically located next to <code class="docutils literal notranslate"><span class="pre">parent/two</span></code>. In this case, Python will create a
|
|||
|
|
namespace package for the top-level <code class="docutils literal notranslate"><span class="pre">parent</span></code> package whenever it or one of
|
|||
|
|
its subpackages is imported.</p>
|
|||
|
|
<p>See also <span class="target" id="index-6"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a> for the namespace package specification.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="searching">
|
|||
|
|
<h2>5.3. Searching<a class="headerlink" href="#searching" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>To begin the search, Python needs the <a class="reference internal" href="../glossary.html#term-qualified-name"><span class="xref std std-term">fully qualified</span></a>
|
|||
|
|
name of the module (or package, but for the purposes of this discussion, the
|
|||
|
|
difference is immaterial) being imported. This name may come from various
|
|||
|
|
arguments to the <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement, or from the parameters to the
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.import_module()</span></code></a> or <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> functions.</p>
|
|||
|
|
<p>This name will be used in various phases of the import search, and it may be
|
|||
|
|
the dotted path to a submodule, e.g. <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>. In this case, Python
|
|||
|
|
first tries to import <code class="docutils literal notranslate"><span class="pre">foo</span></code>, then <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>, and finally <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>.
|
|||
|
|
If any of the intermediate imports fail, a <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> is raised.</p>
|
|||
|
|
<div class="section" id="the-module-cache">
|
|||
|
|
<h3>5.3.1. The module cache<a class="headerlink" href="#the-module-cache" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-7">The first place checked during import search is <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>. This
|
|||
|
|
mapping serves as a cache of all modules that have been previously imported,
|
|||
|
|
including the intermediate paths. So if <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code> was previously
|
|||
|
|
imported, <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> will contain entries for <code class="docutils literal notranslate"><span class="pre">foo</span></code>, <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>,
|
|||
|
|
and <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>. Each key will have as its value the corresponding module
|
|||
|
|
object.</p>
|
|||
|
|
<p>During import, the module name is looked up in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> and if
|
|||
|
|
present, the associated value is the module satisfying the import, and the
|
|||
|
|
process completes. However, if the value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then a
|
|||
|
|
<a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> is raised. If the module name is missing, Python will
|
|||
|
|
continue searching for the module.</p>
|
|||
|
|
<p><a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> is writable. Deleting a key may not destroy the
|
|||
|
|
associated module (as other modules may hold references to it),
|
|||
|
|
but it will invalidate the cache entry for the named module, causing
|
|||
|
|
Python to search anew for the named module upon its next
|
|||
|
|
import. The key can also be assigned to <code class="docutils literal notranslate"><span class="pre">None</span></code>, forcing the next import
|
|||
|
|
of the module to result in a <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a>.</p>
|
|||
|
|
<p>Beware though, as if you keep a reference to the module object,
|
|||
|
|
invalidate its cache entry in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, and then re-import the
|
|||
|
|
named module, the two module objects will <em>not</em> be the same. By contrast,
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.reload" title="importlib.reload"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.reload()</span></code></a> will reuse the <em>same</em> module object, and simply
|
|||
|
|
reinitialise the module contents by rerunning the module’s code.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="finders-and-loaders">
|
|||
|
|
<h3>5.3.2. Finders and loaders<a class="headerlink" href="#finders-and-loaders" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-8">If the named module is not found in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, then Python’s import
|
|||
|
|
protocol is invoked to find and load the module. This protocol consists of
|
|||
|
|
two conceptual objects, <a class="reference internal" href="../glossary.html#term-finder"><span class="xref std std-term">finders</span></a> and <a class="reference internal" href="../glossary.html#term-loader"><span class="xref std std-term">loaders</span></a>.
|
|||
|
|
A finder’s job is to determine whether it can find the named module using
|
|||
|
|
whatever strategy it knows about. Objects that implement both of these
|
|||
|
|
interfaces are referred to as <a class="reference internal" href="../glossary.html#term-importer"><span class="xref std std-term">importers</span></a> - they return
|
|||
|
|
themselves when they find that they can load the requested module.</p>
|
|||
|
|
<p>Python includes a number of default finders and importers. The first one
|
|||
|
|
knows how to locate built-in modules, and the second knows how to locate
|
|||
|
|
frozen modules. A third default finder searches an <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a>
|
|||
|
|
for modules. The <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a> is a list of locations that may
|
|||
|
|
name file system paths or zip files. It can also be extended to search
|
|||
|
|
for any locatable resource, such as those identified by URLs.</p>
|
|||
|
|
<p>The import machinery is extensible, so new finders can be added to extend the
|
|||
|
|
range and scope of module searching.</p>
|
|||
|
|
<p>Finders do not actually load modules. If they can find the named module, they
|
|||
|
|
return a <em class="dfn">module spec</em>, an encapsulation of the module’s import-related
|
|||
|
|
information, which the import machinery then uses when loading the module.</p>
|
|||
|
|
<p>The following sections describe the protocol for finders and loaders in more
|
|||
|
|
detail, including how you can create and register new ones to extend the
|
|||
|
|
import machinery.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>In previous versions of Python, finders returned <a class="reference internal" href="../glossary.html#term-loader"><span class="xref std std-term">loaders</span></a>
|
|||
|
|
directly, whereas now they return module specs which <em>contain</em> loaders.
|
|||
|
|
Loaders are still used during import but have fewer responsibilities.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="import-hooks">
|
|||
|
|
<h3>5.3.3. Import hooks<a class="headerlink" href="#import-hooks" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-9">The import machinery is designed to be extensible; the primary mechanism for
|
|||
|
|
this are the <em>import hooks</em>. There are two types of import hooks: <em>meta
|
|||
|
|
hooks</em> and <em>import path hooks</em>.</p>
|
|||
|
|
<p>Meta hooks are called at the start of import processing, before any other
|
|||
|
|
import processing has occurred, other than <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> cache look up.
|
|||
|
|
This allows meta hooks to override <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> processing, frozen
|
|||
|
|
modules, or even built-in modules. Meta hooks are registered by adding new
|
|||
|
|
finder objects to <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>, as described below.</p>
|
|||
|
|
<p>Import path hooks are called as part of <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> (or
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">package.__path__</span></code>) processing, at the point where their associated path
|
|||
|
|
item is encountered. Import path hooks are registered by adding new callables
|
|||
|
|
to <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> as described below.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="the-meta-path">
|
|||
|
|
<h3>5.3.4. The meta path<a class="headerlink" href="#the-meta-path" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-10">When the named module is not found in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, Python next
|
|||
|
|
searches <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>, which contains a list of meta path finder
|
|||
|
|
objects. These finders are queried in order to see if they know how to handle
|
|||
|
|
the named module. Meta path finders must implement a method called
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> which takes three arguments:
|
|||
|
|
a name, an import path, and (optionally) a target module. The meta path
|
|||
|
|
finder can use any strategy it wants to determine whether it can handle
|
|||
|
|
the named module or not.</p>
|
|||
|
|
<p>If the meta path finder knows how to handle the named module, it returns a
|
|||
|
|
spec object. If it cannot handle the named module, it returns <code class="docutils literal notranslate"><span class="pre">None</span></code>. If
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a> processing reaches the end of its list without returning
|
|||
|
|
a spec, then a <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> is raised. Any other exceptions
|
|||
|
|
raised are simply propagated up, aborting the import process.</p>
|
|||
|
|
<p>The <a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method of meta path
|
|||
|
|
finders is called with two or three arguments. The first is the fully
|
|||
|
|
qualified name of the module being imported, for example <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>.
|
|||
|
|
The second argument is the path entries to use for the module search. For
|
|||
|
|
top-level modules, the second argument is <code class="docutils literal notranslate"><span class="pre">None</span></code>, but for submodules or
|
|||
|
|
subpackages, the second argument is the value of the parent package’s
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute. If the appropriate <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute cannot
|
|||
|
|
be accessed, a <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> is raised. The third argument
|
|||
|
|
is an existing module object that will be the target of loading later.
|
|||
|
|
The import system passes in a target module only during reload.</p>
|
|||
|
|
<p>The meta path may be traversed multiple times for a single import request.
|
|||
|
|
For example, assuming none of the modules involved has already been cached,
|
|||
|
|
importing <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code> will first perform a top level import, calling
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">mpf.find_spec("foo",</span> <span class="pre">None,</span> <span class="pre">None)</span></code> on each meta path finder (<code class="docutils literal notranslate"><span class="pre">mpf</span></code>). After
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">foo</span></code> has been imported, <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code> will be imported by traversing the
|
|||
|
|
meta path a second time, calling
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">mpf.find_spec("foo.bar",</span> <span class="pre">foo.__path__,</span> <span class="pre">None)</span></code>. Once <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code> has been
|
|||
|
|
imported, the final traversal will call
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">mpf.find_spec("foo.bar.baz",</span> <span class="pre">foo.bar.__path__,</span> <span class="pre">None)</span></code>.</p>
|
|||
|
|
<p>Some meta path finders only support top level imports. These importers will
|
|||
|
|
always return <code class="docutils literal notranslate"><span class="pre">None</span></code> when anything other than <code class="docutils literal notranslate"><span class="pre">None</span></code> is passed as the
|
|||
|
|
second argument.</p>
|
|||
|
|
<p>Python’s default <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a> has three meta path finders, one that
|
|||
|
|
knows how to import built-in modules, one that knows how to import frozen
|
|||
|
|
modules, and one that knows how to import modules from an <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a>
|
|||
|
|
(i.e. the <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a>).</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>The <a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method of meta path
|
|||
|
|
finders replaced <a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_module" title="importlib.abc.MetaPathFinder.find_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_module()</span></code></a>, which
|
|||
|
|
is now deprecated. While it will continue to work without change, the
|
|||
|
|
import machinery will try it only if the finder does not implement
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">find_spec()</span></code>.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="loading">
|
|||
|
|
<h2>5.4. Loading<a class="headerlink" href="#loading" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>If and when a module spec is found, the import machinery will use it (and
|
|||
|
|
the loader it contains) when loading the module. Here is an approximation
|
|||
|
|
of what happens during the loading portion of import:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">module</span> <span class="o">=</span> <span class="kc">None</span>
|
|||
|
|
<span class="k">if</span> <span class="n">spec</span><span class="o">.</span><span class="n">loader</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">spec</span><span class="o">.</span><span class="n">loader</span><span class="p">,</span> <span class="s1">'create_module'</span><span class="p">):</span>
|
|||
|
|
<span class="c1"># It is assumed 'exec_module' will also be defined on the loader.</span>
|
|||
|
|
<span class="n">module</span> <span class="o">=</span> <span class="n">spec</span><span class="o">.</span><span class="n">loader</span><span class="o">.</span><span class="n">create_module</span><span class="p">(</span><span class="n">spec</span><span class="p">)</span>
|
|||
|
|
<span class="k">if</span> <span class="n">module</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
|||
|
|
<span class="n">module</span> <span class="o">=</span> <span class="n">ModuleType</span><span class="p">(</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
|
|||
|
|
<span class="c1"># The import-related module attributes get set here:</span>
|
|||
|
|
<span class="n">_init_module_attrs</span><span class="p">(</span><span class="n">spec</span><span class="p">,</span> <span class="n">module</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="k">if</span> <span class="n">spec</span><span class="o">.</span><span class="n">loader</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
|||
|
|
<span class="k">if</span> <span class="n">spec</span><span class="o">.</span><span class="n">submodule_search_locations</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
|||
|
|
<span class="c1"># namespace package</span>
|
|||
|
|
<span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">module</span>
|
|||
|
|
<span class="k">else</span><span class="p">:</span>
|
|||
|
|
<span class="c1"># unsupported</span>
|
|||
|
|
<span class="k">raise</span> <span class="ne">ImportError</span>
|
|||
|
|
<span class="k">elif</span> <span class="ow">not</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">spec</span><span class="o">.</span><span class="n">loader</span><span class="p">,</span> <span class="s1">'exec_module'</span><span class="p">):</span>
|
|||
|
|
<span class="n">module</span> <span class="o">=</span> <span class="n">spec</span><span class="o">.</span><span class="n">loader</span><span class="o">.</span><span class="n">load_module</span><span class="p">(</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
|
|||
|
|
<span class="c1"># Set __loader__ and __package__ if missing.</span>
|
|||
|
|
<span class="k">else</span><span class="p">:</span>
|
|||
|
|
<span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">module</span>
|
|||
|
|
<span class="k">try</span><span class="p">:</span>
|
|||
|
|
<span class="n">spec</span><span class="o">.</span><span class="n">loader</span><span class="o">.</span><span class="n">exec_module</span><span class="p">(</span><span class="n">module</span><span class="p">)</span>
|
|||
|
|
<span class="k">except</span> <span class="ne">BaseException</span><span class="p">:</span>
|
|||
|
|
<span class="k">try</span><span class="p">:</span>
|
|||
|
|
<span class="k">del</span> <span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">]</span>
|
|||
|
|
<span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
|
|||
|
|
<span class="k">pass</span>
|
|||
|
|
<span class="k">raise</span>
|
|||
|
|
<span class="k">return</span> <span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="n">spec</span><span class="o">.</span><span class="n">name</span><span class="p">]</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Note the following details:</p>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><ul class="simple">
|
|||
|
|
<li><p>If there is an existing module object with the given name in
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, import will have already returned it.</p></li>
|
|||
|
|
<li><p>The module will exist in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> before the loader
|
|||
|
|
executes the module code. This is crucial because the module code may
|
|||
|
|
(directly or indirectly) import itself; adding it to <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>
|
|||
|
|
beforehand prevents unbounded recursion in the worst case and multiple
|
|||
|
|
loading in the best.</p></li>
|
|||
|
|
<li><p>If loading fails, the failing module – and only the failing module –
|
|||
|
|
gets removed from <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>. Any module already in the
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> cache, and any module that was successfully loaded
|
|||
|
|
as a side-effect, must remain in the cache. This contrasts with
|
|||
|
|
reloading where even the failing module is left in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>.</p></li>
|
|||
|
|
<li><p>After the module is created but before execution, the import machinery
|
|||
|
|
sets the import-related module attributes (“_init_module_attrs” in
|
|||
|
|
the pseudo-code example above), as summarized in a
|
|||
|
|
<a class="reference internal" href="#import-mod-attrs"><span class="std std-ref">later section</span></a>.</p></li>
|
|||
|
|
<li><p>Module execution is the key moment of loading in which the module’s
|
|||
|
|
namespace gets populated. Execution is entirely delegated to the
|
|||
|
|
loader, which gets to decide what gets populated and how.</p></li>
|
|||
|
|
<li><p>The module created during loading and passed to exec_module() may
|
|||
|
|
not be the one returned at the end of import <a class="footnote-reference brackets" href="#fnlo" id="id2">2</a>.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div></blockquote>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>The import system has taken over the boilerplate responsibilities of
|
|||
|
|
loaders. These were previously performed by the
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">importlib.abc.Loader.load_module()</span></code></a> method.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="loaders">
|
|||
|
|
<h3>5.4.1. Loaders<a class="headerlink" href="#loaders" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Module loaders provide the critical function of loading: module execution.
|
|||
|
|
The import machinery calls the <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">importlib.abc.Loader.exec_module()</span></code></a>
|
|||
|
|
method with a single argument, the module object to execute. Any value
|
|||
|
|
returned from <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exec_module()</span></code></a> is ignored.</p>
|
|||
|
|
<p>Loaders must satisfy the following requirements:</p>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><ul class="simple">
|
|||
|
|
<li><p>If the module is a Python module (as opposed to a built-in module or a
|
|||
|
|
dynamically loaded extension), the loader should execute the module’s code
|
|||
|
|
in the module’s global name space (<code class="docutils literal notranslate"><span class="pre">module.__dict__</span></code>).</p></li>
|
|||
|
|
<li><p>If the loader cannot execute the module, it should raise an
|
|||
|
|
<a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a>, although any other exception raised during
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exec_module()</span></code></a> will be propagated.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div></blockquote>
|
|||
|
|
<p>In many cases, the finder and loader can be the same object; in such cases the
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method would just return a
|
|||
|
|
spec with the loader set to <code class="docutils literal notranslate"><span class="pre">self</span></code>.</p>
|
|||
|
|
<p>Module loaders may opt in to creating the module object during loading
|
|||
|
|
by implementing a <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.create_module" title="importlib.abc.Loader.create_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_module()</span></code></a> method.
|
|||
|
|
It takes one argument, the module spec, and returns the new module object
|
|||
|
|
to use during loading. <code class="docutils literal notranslate"><span class="pre">create_module()</span></code> does not need to set any attributes
|
|||
|
|
on the module object. If the method returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, the
|
|||
|
|
import machinery will create the new module itself.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4: </span>The <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.create_module" title="importlib.abc.Loader.create_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_module()</span></code></a> method of loaders.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>The <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">load_module()</span></code></a> method was replaced by
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exec_module()</span></code></a> and the import
|
|||
|
|
machinery assumed all the boilerplate responsibilities of loading.</p>
|
|||
|
|
<p>For compatibility with existing loaders, the import machinery will use
|
|||
|
|
the <code class="docutils literal notranslate"><span class="pre">load_module()</span></code> method of loaders if it exists and the loader does
|
|||
|
|
not also implement <code class="docutils literal notranslate"><span class="pre">exec_module()</span></code>. However, <code class="docutils literal notranslate"><span class="pre">load_module()</span></code> has been
|
|||
|
|
deprecated and loaders should implement <code class="docutils literal notranslate"><span class="pre">exec_module()</span></code> instead.</p>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">load_module()</span></code> method must implement all the boilerplate loading
|
|||
|
|
functionality described above in addition to executing the module. All
|
|||
|
|
the same constraints apply, with some additional clarification:</p>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><ul class="simple">
|
|||
|
|
<li><p>If there is an existing module object with the given name in
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, the loader must use that existing module.
|
|||
|
|
(Otherwise, <a class="reference internal" href="../library/importlib.html#importlib.reload" title="importlib.reload"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.reload()</span></code></a> will not work correctly.) If the
|
|||
|
|
named module does not exist in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, the loader
|
|||
|
|
must create a new module object and add it to <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>.</p></li>
|
|||
|
|
<li><p>The module <em>must</em> exist in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a> before the loader
|
|||
|
|
executes the module code, to prevent unbounded recursion or multiple
|
|||
|
|
loading.</p></li>
|
|||
|
|
<li><p>If loading fails, the loader must remove any modules it has inserted
|
|||
|
|
into <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>, but it must remove <strong>only</strong> the failing
|
|||
|
|
module(s), and only if the loader itself has loaded the module(s)
|
|||
|
|
explicitly.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div></blockquote>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.5: </span>A <a class="reference internal" href="../library/exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> is raised when <code class="docutils literal notranslate"><span class="pre">exec_module()</span></code> is defined but
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">create_module()</span></code> is not.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>An <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> is raised when <code class="docutils literal notranslate"><span class="pre">exec_module()</span></code> is defined but
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">create_module()</span></code> is not.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="submodules">
|
|||
|
|
<h3>5.4.2. Submodules<a class="headerlink" href="#submodules" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>When a submodule is loaded using any mechanism (e.g. <code class="docutils literal notranslate"><span class="pre">importlib</span></code> APIs, the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">import</span></code> or <code class="docutils literal notranslate"><span class="pre">import-from</span></code> statements, or built-in <code class="docutils literal notranslate"><span class="pre">__import__()</span></code>) a
|
|||
|
|
binding is placed in the parent module’s namespace to the submodule object.
|
|||
|
|
For example, if package <code class="docutils literal notranslate"><span class="pre">spam</span></code> has a submodule <code class="docutils literal notranslate"><span class="pre">foo</span></code>, after importing
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">spam.foo</span></code>, <code class="docutils literal notranslate"><span class="pre">spam</span></code> will have an attribute <code class="docutils literal notranslate"><span class="pre">foo</span></code> which is bound to the
|
|||
|
|
submodule. Let’s say you have the following directory structure:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">spam</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>and <code class="docutils literal notranslate"><span class="pre">spam/__init__.py</span></code> has the following lines in it:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">.foo</span> <span class="k">import</span> <span class="n">Foo</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">.bar</span> <span class="k">import</span> <span class="n">Bar</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>then executing the following puts a name binding to <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code> in the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">spam</span></code> module:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spam</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">spam</span><span class="o">.</span><span class="n">foo</span>
|
|||
|
|
<span class="go"><module 'spam.foo' from '/tmp/imports/spam/foo.py'></span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">spam</span><span class="o">.</span><span class="n">bar</span>
|
|||
|
|
<span class="go"><module 'spam.bar' from '/tmp/imports/spam/bar.py'></span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Given Python’s familiar name binding rules this might seem surprising, but
|
|||
|
|
it’s actually a fundamental feature of the import system. The invariant
|
|||
|
|
holding is that if you have <code class="docutils literal notranslate"><span class="pre">sys.modules['spam']</span></code> and
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">sys.modules['spam.foo']</span></code> (as you would after the above import), the latter
|
|||
|
|
must appear as the <code class="docutils literal notranslate"><span class="pre">foo</span></code> attribute of the former.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="module-spec">
|
|||
|
|
<h3>5.4.3. Module spec<a class="headerlink" href="#module-spec" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>The import machinery uses a variety of information about each module
|
|||
|
|
during import, especially before loading. Most of the information is
|
|||
|
|
common to all modules. The purpose of a module’s spec is to encapsulate
|
|||
|
|
this import-related information on a per-module basis.</p>
|
|||
|
|
<p>Using a spec during import allows state to be transferred between import
|
|||
|
|
system components, e.g. between the finder that creates the module spec
|
|||
|
|
and the loader that executes it. Most importantly, it allows the
|
|||
|
|
import machinery to perform the boilerplate operations of loading,
|
|||
|
|
whereas without a module spec the loader had that responsibility.</p>
|
|||
|
|
<p>The module’s spec is exposed as the <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> attribute on a module object.
|
|||
|
|
See <a class="reference internal" href="../library/importlib.html#importlib.machinery.ModuleSpec" title="importlib.machinery.ModuleSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ModuleSpec</span></code></a> for details on the contents of
|
|||
|
|
the module spec.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="import-related-module-attributes">
|
|||
|
|
<span id="import-mod-attrs"></span><h3>5.4.4. Import-related module attributes<a class="headerlink" href="#import-related-module-attributes" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>The import machinery fills in these attributes on each module object
|
|||
|
|
during loading, based on the module’s spec, before the loader executes
|
|||
|
|
the module.</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__name__">
|
|||
|
|
<code class="descname">__name__</code><a class="headerlink" href="#__name__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <code class="docutils literal notranslate"><span class="pre">__name__</span></code> attribute must be set to the fully-qualified name of
|
|||
|
|
the module. This name is used to uniquely identify the module in
|
|||
|
|
the import system.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__loader__">
|
|||
|
|
<code class="descname">__loader__</code><a class="headerlink" href="#__loader__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <code class="docutils literal notranslate"><span class="pre">__loader__</span></code> attribute must be set to the loader object that
|
|||
|
|
the import machinery used when loading the module. This is mostly
|
|||
|
|
for introspection, but can be used for additional loader-specific
|
|||
|
|
functionality, for example getting data associated with a loader.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__package__">
|
|||
|
|
<code class="descname">__package__</code><a class="headerlink" href="#__package__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The module’s <code class="docutils literal notranslate"><span class="pre">__package__</span></code> attribute must be set. Its value must
|
|||
|
|
be a string, but it can be the same value as its <code class="docutils literal notranslate"><span class="pre">__name__</span></code>. When
|
|||
|
|
the module is a package, its <code class="docutils literal notranslate"><span class="pre">__package__</span></code> value should be set to
|
|||
|
|
its <code class="docutils literal notranslate"><span class="pre">__name__</span></code>. When the module is not a package, <code class="docutils literal notranslate"><span class="pre">__package__</span></code>
|
|||
|
|
should be set to the empty string for top-level modules, or for
|
|||
|
|
submodules, to the parent package’s name. See <span class="target" id="index-11"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0366"><strong>PEP 366</strong></a> for further
|
|||
|
|
details.</p>
|
|||
|
|
<p>This attribute is used instead of <code class="docutils literal notranslate"><span class="pre">__name__</span></code> to calculate explicit
|
|||
|
|
relative imports for main modules, as defined in <span class="target" id="index-12"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0366"><strong>PEP 366</strong></a>. It is
|
|||
|
|
expected to have the same value as <code class="docutils literal notranslate"><span class="pre">__spec__.parent</span></code>.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>The value of <code class="docutils literal notranslate"><span class="pre">__package__</span></code> is expected to be the same as
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__spec__.parent</span></code>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__spec__">
|
|||
|
|
<code class="descname">__spec__</code><a class="headerlink" href="#__spec__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> attribute must be set to the module spec that was
|
|||
|
|
used when importing the module. Setting <code class="docutils literal notranslate"><span class="pre">__spec__</span></code>
|
|||
|
|
appropriately applies equally to <a class="reference internal" href="toplevel_components.html#programs"><span class="std std-ref">modules initialized during
|
|||
|
|
interpreter startup</span></a>. The one exception is <code class="docutils literal notranslate"><span class="pre">__main__</span></code>,
|
|||
|
|
where <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> is <a class="reference internal" href="#main-spec"><span class="std std-ref">set to None in some cases</span></a>.</p>
|
|||
|
|
<p>When <code class="docutils literal notranslate"><span class="pre">__package__</span></code> is not defined, <code class="docutils literal notranslate"><span class="pre">__spec__.parent</span></code> is used as
|
|||
|
|
a fallback.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span><code class="docutils literal notranslate"><span class="pre">__spec__.parent</span></code> is used as a fallback when <code class="docutils literal notranslate"><span class="pre">__package__</span></code> is
|
|||
|
|
not defined.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__path__">
|
|||
|
|
<code class="descname">__path__</code><a class="headerlink" href="#__path__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If the module is a package (either regular or namespace), the module
|
|||
|
|
object’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute must be set. The value must be
|
|||
|
|
iterable, but may be empty if <code class="docutils literal notranslate"><span class="pre">__path__</span></code> has no further significance.
|
|||
|
|
If <code class="docutils literal notranslate"><span class="pre">__path__</span></code> is not empty, it must produce strings when iterated
|
|||
|
|
over. More details on the semantics of <code class="docutils literal notranslate"><span class="pre">__path__</span></code> are given
|
|||
|
|
<a class="reference internal" href="#package-path-rules"><span class="std std-ref">below</span></a>.</p>
|
|||
|
|
<p>Non-package modules should not have a <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__file__">
|
|||
|
|
<code class="descname">__file__</code><a class="headerlink" href="#__file__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd></dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="__cached__">
|
|||
|
|
<code class="descname">__cached__</code><a class="headerlink" href="#__cached__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">__file__</span></code> is optional. If set, this attribute’s value must be a
|
|||
|
|
string. The import system may opt to leave <code class="docutils literal notranslate"><span class="pre">__file__</span></code> unset if it
|
|||
|
|
has no semantic meaning (e.g. a module loaded from a database).</p>
|
|||
|
|
<p>If <code class="docutils literal notranslate"><span class="pre">__file__</span></code> is set, it may also be appropriate to set the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__cached__</span></code> attribute which is the path to any compiled version of
|
|||
|
|
the code (e.g. byte-compiled file). The file does not need to exist
|
|||
|
|
to set this attribute; the path can simply point to where the
|
|||
|
|
compiled file would exist (see <span class="target" id="index-13"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147"><strong>PEP 3147</strong></a>).</p>
|
|||
|
|
<p>It is also appropriate to set <code class="docutils literal notranslate"><span class="pre">__cached__</span></code> when <code class="docutils literal notranslate"><span class="pre">__file__</span></code> is not
|
|||
|
|
set. However, that scenario is quite atypical. Ultimately, the
|
|||
|
|
loader is what makes use of <code class="docutils literal notranslate"><span class="pre">__file__</span></code> and/or <code class="docutils literal notranslate"><span class="pre">__cached__</span></code>. So
|
|||
|
|
if a loader can load from a cached module but otherwise does not load
|
|||
|
|
from a file, that atypical scenario may be appropriate.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="module-path">
|
|||
|
|
<span id="package-path-rules"></span><h3>5.4.5. module.__path__<a class="headerlink" href="#module-path" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>By definition, if a module has a <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute, it is a package.</p>
|
|||
|
|
<p>A package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute is used during imports of its subpackages.
|
|||
|
|
Within the import machinery, it functions much the same as <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>,
|
|||
|
|
i.e. providing a list of locations to search for modules during import.
|
|||
|
|
However, <code class="docutils literal notranslate"><span class="pre">__path__</span></code> is typically much more constrained than
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>.</p>
|
|||
|
|
<p><code class="docutils literal notranslate"><span class="pre">__path__</span></code> must be an iterable of strings, but it may be empty.
|
|||
|
|
The same rules used for <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> also apply to a package’s
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__path__</span></code>, and <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> (described below) are
|
|||
|
|
consulted when traversing a package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code>.</p>
|
|||
|
|
<p>A package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file may set or alter the package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
attribute, and this was typically the way namespace packages were implemented
|
|||
|
|
prior to <span class="target" id="index-14"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a>. With the adoption of <span class="target" id="index-15"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a>, namespace packages no
|
|||
|
|
longer need to supply <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files containing only <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
manipulation code; the import machinery automatically sets <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
correctly for the namespace package.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="module-reprs">
|
|||
|
|
<h3>5.4.6. Module reprs<a class="headerlink" href="#module-reprs" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>By default, all modules have a usable repr, however depending on the
|
|||
|
|
attributes set above, and in the module’s spec, you can more explicitly
|
|||
|
|
control the repr of module objects.</p>
|
|||
|
|
<p>If the module has a spec (<code class="docutils literal notranslate"><span class="pre">__spec__</span></code>), the import machinery will try
|
|||
|
|
to generate a repr from it. If that fails or there is no spec, the import
|
|||
|
|
system will craft a default repr using whatever information is available
|
|||
|
|
on the module. It will try to use the <code class="docutils literal notranslate"><span class="pre">module.__name__</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">module.__file__</span></code>, and <code class="docutils literal notranslate"><span class="pre">module.__loader__</span></code> as input into the repr,
|
|||
|
|
with defaults for whatever information is missing.</p>
|
|||
|
|
<p>Here are the exact rules used:</p>
|
|||
|
|
<blockquote>
|
|||
|
|
<div><ul class="simple">
|
|||
|
|
<li><p>If the module has a <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> attribute, the information in the spec
|
|||
|
|
is used to generate the repr. The “name”, “loader”, “origin”, and
|
|||
|
|
“has_location” attributes are consulted.</p></li>
|
|||
|
|
<li><p>If the module has a <code class="docutils literal notranslate"><span class="pre">__file__</span></code> attribute, this is used as part of the
|
|||
|
|
module’s repr.</p></li>
|
|||
|
|
<li><p>If the module has no <code class="docutils literal notranslate"><span class="pre">__file__</span></code> but does have a <code class="docutils literal notranslate"><span class="pre">__loader__</span></code> that is not
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>, then the loader’s repr is used as part of the module’s repr.</p></li>
|
|||
|
|
<li><p>Otherwise, just use the module’s <code class="docutils literal notranslate"><span class="pre">__name__</span></code> in the repr.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</div></blockquote>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>Use of <a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.module_repr" title="importlib.abc.Loader.module_repr"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loader.module_repr()</span></code></a>
|
|||
|
|
has been deprecated and the module spec is now used by the import
|
|||
|
|
machinery to generate a module repr.</p>
|
|||
|
|
<p>For backward compatibility with Python 3.3, the module repr will be
|
|||
|
|
generated by calling the loader’s
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.Loader.module_repr" title="importlib.abc.Loader.module_repr"><code class="xref py py-meth docutils literal notranslate"><span class="pre">module_repr()</span></code></a> method, if defined, before
|
|||
|
|
trying either approach described above. However, the method is deprecated.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="cached-bytecode-invalidation">
|
|||
|
|
<span id="pyc-invalidation"></span><h3>5.4.7. Cached bytecode invalidation<a class="headerlink" href="#cached-bytecode-invalidation" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Before Python loads cached bytecode from <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> file, it checks whether the
|
|||
|
|
cache is up-to-date with the source <code class="docutils literal notranslate"><span class="pre">.py</span></code> file. By default, Python does this
|
|||
|
|
by storing the source’s last-modified timestamp and size in the cache file when
|
|||
|
|
writing it. At runtime, the import system then validates the cache file by
|
|||
|
|
checking the stored metadata in the cache file against at source’s
|
|||
|
|
metadata.</p>
|
|||
|
|
<p>Python also supports “hash-based” cache files, which store a hash of the source
|
|||
|
|
file’s contents rather than its metadata. There are two variants of hash-based
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files: checked and unchecked. For checked hash-based <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files,
|
|||
|
|
Python validates the cache file by hashing the source file and comparing the
|
|||
|
|
resulting hash with the hash in the cache file. If a checked hash-based cache
|
|||
|
|
file is found to be invalid, Python regenerates it and writes a new checked
|
|||
|
|
hash-based cache file. For unchecked hash-based <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files, Python simply
|
|||
|
|
assumes the cache file is valid if it exists. Hash-based <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files
|
|||
|
|
validation behavior may be overridden with the <a class="reference internal" href="../using/cmdline.html#cmdoption-check-hash-based-pycs"><code class="xref std std-option docutils literal notranslate"><span class="pre">--check-hash-based-pycs</span></code></a>
|
|||
|
|
flag.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>Added hash-based <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files. Previously, Python only supported
|
|||
|
|
timestamp-based invalidation of bytecode caches.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="the-path-based-finder">
|
|||
|
|
<h2>5.5. The Path Based Finder<a class="headerlink" href="#the-path-based-finder" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p id="index-16">As mentioned previously, Python comes with several default meta path finders.
|
|||
|
|
One of these, called the <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a>
|
|||
|
|
(<a class="reference internal" href="../library/importlib.html#importlib.machinery.PathFinder" title="importlib.machinery.PathFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathFinder</span></code></a>), searches an <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a>,
|
|||
|
|
which contains a list of <a class="reference internal" href="../glossary.html#term-path-entry"><span class="xref std std-term">path entries</span></a>. Each path
|
|||
|
|
entry names a location to search for modules.</p>
|
|||
|
|
<p>The path based finder itself doesn’t know how to import anything. Instead, it
|
|||
|
|
traverses the individual path entries, associating each of them with a
|
|||
|
|
path entry finder that knows how to handle that particular kind of path.</p>
|
|||
|
|
<p>The default set of path entry finders implement all the semantics for finding
|
|||
|
|
modules on the file system, handling special file types such as Python source
|
|||
|
|
code (<code class="docutils literal notranslate"><span class="pre">.py</span></code> files), Python byte code (<code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files) and
|
|||
|
|
shared libraries (e.g. <code class="docutils literal notranslate"><span class="pre">.so</span></code> files). When supported by the <a class="reference internal" href="../library/zipimport.html#module-zipimport" title="zipimport: support for importing Python modules from ZIP archives."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipimport</span></code></a>
|
|||
|
|
module in the standard library, the default path entry finders also handle
|
|||
|
|
loading all of these file types (other than shared libraries) from zipfiles.</p>
|
|||
|
|
<p>Path entries need not be limited to file system locations. They can refer to
|
|||
|
|
URLs, database queries, or any other location that can be specified as a
|
|||
|
|
string.</p>
|
|||
|
|
<p>The path based finder provides additional hooks and protocols so that you
|
|||
|
|
can extend and customize the types of searchable path entries. For example,
|
|||
|
|
if you wanted to support path entries as network URLs, you could write a hook
|
|||
|
|
that implements HTTP semantics to find modules on the web. This hook (a
|
|||
|
|
callable) would return a <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a> supporting the protocol
|
|||
|
|
described below, which was then used to get a loader for the module from the
|
|||
|
|
web.</p>
|
|||
|
|
<p>A word of warning: this section and the previous both use the term <em>finder</em>,
|
|||
|
|
distinguishing between them by using the terms <a class="reference internal" href="../glossary.html#term-meta-path-finder"><span class="xref std std-term">meta path finder</span></a> and
|
|||
|
|
<a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a>. These two types of finders are very similar,
|
|||
|
|
support similar protocols, and function in similar ways during the import
|
|||
|
|
process, but it’s important to keep in mind that they are subtly different.
|
|||
|
|
In particular, meta path finders operate at the beginning of the import
|
|||
|
|
process, as keyed off the <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a> traversal.</p>
|
|||
|
|
<p>By contrast, path entry finders are in a sense an implementation detail
|
|||
|
|
of the path based finder, and in fact, if the path based finder were to be
|
|||
|
|
removed from <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>, none of the path entry finder semantics
|
|||
|
|
would be invoked.</p>
|
|||
|
|
<div class="section" id="path-entry-finders">
|
|||
|
|
<h3>5.5.1. Path entry finders<a class="headerlink" href="#path-entry-finders" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p id="index-17">The <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a> is responsible for finding and loading
|
|||
|
|
Python modules and packages whose location is specified with a string
|
|||
|
|
<a class="reference internal" href="../glossary.html#term-path-entry"><span class="xref std std-term">path entry</span></a>. Most path entries name locations in the file system,
|
|||
|
|
but they need not be limited to this.</p>
|
|||
|
|
<p>As a meta path finder, the <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a> implements the
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> protocol previously
|
|||
|
|
described, however it exposes additional hooks that can be used to
|
|||
|
|
customize how modules are found and loaded from the <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a>.</p>
|
|||
|
|
<p>Three variables are used by the <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a>, <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>,
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> and <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a>. The <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
attributes on package objects are also used. These provide additional ways
|
|||
|
|
that the import machinery can be customized.</p>
|
|||
|
|
<p><a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> contains a list of strings providing search locations for
|
|||
|
|
modules and packages. It is initialized from the <code class="xref py py-data docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>
|
|||
|
|
environment variable and various other installation- and
|
|||
|
|
implementation-specific defaults. Entries in <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> can name
|
|||
|
|
directories on the file system, zip files, and potentially other “locations”
|
|||
|
|
(see the <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module) that should be searched for modules, such as
|
|||
|
|
URLs, or database queries. Only strings and bytes should be present on
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>; all other data types are ignored. The encoding of bytes
|
|||
|
|
entries is determined by the individual <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finders</span></a>.</p>
|
|||
|
|
<p>The <a class="reference internal" href="../glossary.html#term-path-based-finder"><span class="xref std std-term">path based finder</span></a> is a <a class="reference internal" href="../glossary.html#term-meta-path-finder"><span class="xref std std-term">meta path finder</span></a>, so the import
|
|||
|
|
machinery begins the <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a> search by calling the path
|
|||
|
|
based finder’s <a class="reference internal" href="../library/importlib.html#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method as
|
|||
|
|
described previously. When the <code class="docutils literal notranslate"><span class="pre">path</span></code> argument to
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> is given, it will be a
|
|||
|
|
list of string paths to traverse - typically a package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code>
|
|||
|
|
attribute for an import within that package. If the <code class="docutils literal notranslate"><span class="pre">path</span></code> argument is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>, this indicates a top level import and <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> is used.</p>
|
|||
|
|
<p>The path based finder iterates over every entry in the search path, and
|
|||
|
|
for each of these, looks for an appropriate <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a>
|
|||
|
|
(<a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder" title="importlib.abc.PathEntryFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathEntryFinder</span></code></a>) for the
|
|||
|
|
path entry. Because this can be an expensive operation (e.g. there may be
|
|||
|
|
<cite>stat()</cite> call overheads for this search), the path based finder maintains
|
|||
|
|
a cache mapping path entries to path entry finders. This cache is maintained
|
|||
|
|
in <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a> (despite the name, this cache actually
|
|||
|
|
stores finder objects rather than being limited to <a class="reference internal" href="../glossary.html#term-importer"><span class="xref std std-term">importer</span></a> objects).
|
|||
|
|
In this way, the expensive search for a particular <a class="reference internal" href="../glossary.html#term-path-entry"><span class="xref std std-term">path entry</span></a>
|
|||
|
|
location’s <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a> need only be done once. User code is
|
|||
|
|
free to remove cache entries from <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a> forcing
|
|||
|
|
the path based finder to perform the path entry search again <a class="footnote-reference brackets" href="#fnpic" id="id3">3</a>.</p>
|
|||
|
|
<p>If the path entry is not present in the cache, the path based finder iterates
|
|||
|
|
over every callable in <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a>. Each of the <a class="reference internal" href="../glossary.html#term-path-entry-hook"><span class="xref std std-term">path entry
|
|||
|
|
hooks</span></a> in this list is called with a single argument, the
|
|||
|
|
path entry to be searched. This callable may either return a <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path
|
|||
|
|
entry finder</span></a> that can handle the path entry, or it may raise
|
|||
|
|
<a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a>. An <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a> is used by the path based finder to
|
|||
|
|
signal that the hook cannot find a <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a>
|
|||
|
|
for that <a class="reference internal" href="../glossary.html#term-path-entry"><span class="xref std std-term">path entry</span></a>. The
|
|||
|
|
exception is ignored and <a class="reference internal" href="../glossary.html#term-import-path"><span class="xref std std-term">import path</span></a> iteration continues. The hook
|
|||
|
|
should expect either a string or bytes object; the encoding of bytes objects
|
|||
|
|
is up to the hook (e.g. it may be a file system encoding, UTF-8, or something
|
|||
|
|
else), and if the hook cannot decode the argument, it should raise
|
|||
|
|
<a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a>.</p>
|
|||
|
|
<p>If <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> iteration ends with no <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a>
|
|||
|
|
being returned, then the path based finder’s
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method will store <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
|||
|
|
in <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a> (to indicate that there is no finder for
|
|||
|
|
this path entry) and return <code class="docutils literal notranslate"><span class="pre">None</span></code>, indicating that this
|
|||
|
|
<a class="reference internal" href="../glossary.html#term-meta-path-finder"><span class="xref std std-term">meta path finder</span></a> could not find the module.</p>
|
|||
|
|
<p>If a <a class="reference internal" href="../glossary.html#term-path-entry-finder"><span class="xref std std-term">path entry finder</span></a> <em>is</em> returned by one of the <a class="reference internal" href="../glossary.html#term-path-entry-hook"><span class="xref std std-term">path entry
|
|||
|
|
hook</span></a> callables on <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a>, then the following protocol is used
|
|||
|
|
to ask the finder for a module spec, which is then used when loading the
|
|||
|
|
module.</p>
|
|||
|
|
<p>The current working directory – denoted by an empty string – is handled
|
|||
|
|
slightly differently from other entries on <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>. First, if the
|
|||
|
|
current working directory is found to not exist, no value is stored in
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a>. Second, the value for the current working
|
|||
|
|
directory is looked up fresh for each module lookup. Third, the path used for
|
|||
|
|
<a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a> and returned by
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">importlib.machinery.PathFinder.find_spec()</span></code></a> will be the actual current
|
|||
|
|
working directory and not the empty string.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="path-entry-finder-protocol">
|
|||
|
|
<h3>5.5.2. Path entry finder protocol<a class="headerlink" href="#path-entry-finder-protocol" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>In order to support imports of modules and initialized packages and also to
|
|||
|
|
contribute portions to namespace packages, path entry finders must implement
|
|||
|
|
the <a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> method.</p>
|
|||
|
|
<p><a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> takes two argument, the
|
|||
|
|
fully qualified name of the module being imported, and the (optional) target
|
|||
|
|
module. <code class="docutils literal notranslate"><span class="pre">find_spec()</span></code> returns a fully populated spec for the module.
|
|||
|
|
This spec will always have “loader” set (with one exception).</p>
|
|||
|
|
<p>To indicate to the import machinery that the spec represents a namespace
|
|||
|
|
<a class="reference internal" href="../glossary.html#term-portion"><span class="xref std std-term">portion</span></a>. the path entry finder sets “loader” on the spec to
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code> and “submodule_search_locations” to a list containing the
|
|||
|
|
portion.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span><a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> replaced
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_loader" title="importlib.abc.PathEntryFinder.find_loader"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_loader()</span></code></a> and
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_module" title="importlib.abc.PathEntryFinder.find_module"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_module()</span></code></a>, both of which
|
|||
|
|
are now deprecated, but will be used if <code class="docutils literal notranslate"><span class="pre">find_spec()</span></code> is not defined.</p>
|
|||
|
|
<p>Older path entry finders may implement one of these two deprecated methods
|
|||
|
|
instead of <code class="docutils literal notranslate"><span class="pre">find_spec()</span></code>. The methods are still respected for the
|
|||
|
|
sake of backward compatibility. However, if <code class="docutils literal notranslate"><span class="pre">find_spec()</span></code> is
|
|||
|
|
implemented on the path entry finder, the legacy methods are ignored.</p>
|
|||
|
|
<p><a class="reference internal" href="../library/importlib.html#importlib.abc.PathEntryFinder.find_loader" title="importlib.abc.PathEntryFinder.find_loader"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_loader()</span></code></a> takes one argument, the
|
|||
|
|
fully qualified name of the module being imported. <code class="docutils literal notranslate"><span class="pre">find_loader()</span></code>
|
|||
|
|
returns a 2-tuple where the first item is the loader and the second item
|
|||
|
|
is a namespace <a class="reference internal" href="../glossary.html#term-portion"><span class="xref std std-term">portion</span></a>. When the first item (i.e. the loader) is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>, this means that while the path entry finder does not have a
|
|||
|
|
loader for the named module, it knows that the path entry contributes to
|
|||
|
|
a namespace portion for the named module. This will almost always be the
|
|||
|
|
case where Python is asked to import a namespace package that has no
|
|||
|
|
physical presence on the file system. When a path entry finder returns
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code> for the loader, the second item of the 2-tuple return value must
|
|||
|
|
be a sequence, although it can be empty.</p>
|
|||
|
|
<p>If <code class="docutils literal notranslate"><span class="pre">find_loader()</span></code> returns a non-<code class="docutils literal notranslate"><span class="pre">None</span></code> loader value, the portion is
|
|||
|
|
ignored and the loader is returned from the path based finder, terminating
|
|||
|
|
the search through the path entries.</p>
|
|||
|
|
<p>For backwards compatibility with other implementations of the import
|
|||
|
|
protocol, many path entry finders also support the same,
|
|||
|
|
traditional <code class="docutils literal notranslate"><span class="pre">find_module()</span></code> method that meta path finders support.
|
|||
|
|
However path entry finder <code class="docutils literal notranslate"><span class="pre">find_module()</span></code> methods are never called
|
|||
|
|
with a <code class="docutils literal notranslate"><span class="pre">path</span></code> argument (they are expected to record the appropriate
|
|||
|
|
path information from the initial call to the path hook).</p>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">find_module()</span></code> method on path entry finders is deprecated,
|
|||
|
|
as it does not allow the path entry finder to contribute portions to
|
|||
|
|
namespace packages. If both <code class="docutils literal notranslate"><span class="pre">find_loader()</span></code> and <code class="docutils literal notranslate"><span class="pre">find_module()</span></code>
|
|||
|
|
exist on a path entry finder, the import system will always call
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">find_loader()</span></code> in preference to <code class="docutils literal notranslate"><span class="pre">find_module()</span></code>.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="replacing-the-standard-import-system">
|
|||
|
|
<h2>5.6. Replacing the standard import system<a class="headerlink" href="#replacing-the-standard-import-system" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The most reliable mechanism for replacing the entire import system is to
|
|||
|
|
delete the default contents of <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a>, replacing them
|
|||
|
|
entirely with a custom meta path hook.</p>
|
|||
|
|
<p>If it is acceptable to only alter the behaviour of import statements
|
|||
|
|
without affecting other APIs that access the import system, then replacing
|
|||
|
|
the builtin <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function may be sufficient. This technique
|
|||
|
|
may also be employed at the module level to only alter the behaviour of
|
|||
|
|
import statements within that module.</p>
|
|||
|
|
<p>To selectively prevent import of some modules from a hook early on the
|
|||
|
|
meta path (rather than disabling the standard import system entirely),
|
|||
|
|
it is sufficient to raise <a class="reference internal" href="../library/exceptions.html#ModuleNotFoundError" title="ModuleNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ModuleNotFoundError</span></code></a> directly from
|
|||
|
|
<a class="reference internal" href="../library/importlib.html#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find_spec()</span></code></a> instead of returning
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>. The latter indicates that the meta path search should continue,
|
|||
|
|
while raising an exception terminates it immediately.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="package-relative-imports">
|
|||
|
|
<span id="relativeimports"></span><h2>5.7. Package Relative Imports<a class="headerlink" href="#package-relative-imports" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Relative imports use leading dots. A single leading dot indicates a relative
|
|||
|
|
import, starting with the current package. Two or more leading dots indicate a
|
|||
|
|
relative import to the parent(s) of the current package, one level per dot
|
|||
|
|
after the first. For example, given the following package layout:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">package</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">subpackage1</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">moduleX</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">moduleY</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">subpackage2</span><span class="o">/</span>
|
|||
|
|
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">moduleZ</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
<span class="n">moduleA</span><span class="o">.</span><span class="n">py</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>In either <code class="docutils literal notranslate"><span class="pre">subpackage1/moduleX.py</span></code> or <code class="docutils literal notranslate"><span class="pre">subpackage1/__init__.py</span></code>,
|
|||
|
|
the following are valid relative imports:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">.moduleY</span> <span class="k">import</span> <span class="n">spam</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">.moduleY</span> <span class="k">import</span> <span class="n">spam</span> <span class="k">as</span> <span class="n">ham</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">.</span> <span class="k">import</span> <span class="n">moduleY</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">..subpackage1</span> <span class="k">import</span> <span class="n">moduleY</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">..subpackage2.moduleZ</span> <span class="k">import</span> <span class="n">eggs</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">..moduleA</span> <span class="k">import</span> <span class="n">foo</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Absolute imports may use either the <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre"><></span></code> or <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre"><></span> <span class="pre">import</span> <span class="pre"><></span></code>
|
|||
|
|
syntax, but relative imports may only use the second form; the reason
|
|||
|
|
for this is that:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">XXX.YYY.ZZZ</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>should expose <code class="docutils literal notranslate"><span class="pre">XXX.YYY.ZZZ</span></code> as a usable expression, but .moduleY is
|
|||
|
|
not a valid expression.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="special-considerations-for-main">
|
|||
|
|
<h2>5.8. Special considerations for __main__<a class="headerlink" href="#special-considerations-for-main" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> module is a special case relative to Python’s import
|
|||
|
|
system. As noted <a class="reference internal" href="toplevel_components.html#programs"><span class="std std-ref">elsewhere</span></a>, the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module
|
|||
|
|
is directly initialized at interpreter startup, much like <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> and
|
|||
|
|
<a class="reference internal" href="../library/builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a>. However, unlike those two, it doesn’t strictly
|
|||
|
|
qualify as a built-in module. This is because the manner in which
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__main__</span></code> is initialized depends on the flags and other options with
|
|||
|
|
which the interpreter is invoked.</p>
|
|||
|
|
<div class="section" id="main-spec">
|
|||
|
|
<span id="id4"></span><h3>5.8.1. __main__.__spec__<a class="headerlink" href="#main-spec" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Depending on how <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> is initialized, <code class="docutils literal notranslate"><span class="pre">__main__.__spec__</span></code>
|
|||
|
|
gets set appropriately or to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
<p>When Python is started with the <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> option, <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> is set
|
|||
|
|
to the module spec of the corresponding module or package. <code class="docutils literal notranslate"><span class="pre">__spec__</span></code> is
|
|||
|
|
also populated when the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module is loaded as part of executing a
|
|||
|
|
directory, zipfile or other <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> entry.</p>
|
|||
|
|
<p>In <a class="reference internal" href="../using/cmdline.html#using-on-interface-options"><span class="std std-ref">the remaining cases</span></a>
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__main__.__spec__</span></code> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, as the code used to populate the
|
|||
|
|
<a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> does not correspond directly with an importable module:</p>
|
|||
|
|
<ul class="simple">
|
|||
|
|
<li><p>interactive prompt</p></li>
|
|||
|
|
<li><p><a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a> option</p></li>
|
|||
|
|
<li><p>running from stdin</p></li>
|
|||
|
|
<li><p>running directly from a source or bytecode file</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Note that <code class="docutils literal notranslate"><span class="pre">__main__.__spec__</span></code> is always <code class="docutils literal notranslate"><span class="pre">None</span></code> in the last case,
|
|||
|
|
<em>even if</em> the file could technically be imported directly as a module
|
|||
|
|
instead. Use the <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> switch if valid module metadata is desired
|
|||
|
|
in <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a>.</p>
|
|||
|
|
<p>Note also that even when <code class="docutils literal notranslate"><span class="pre">__main__</span></code> corresponds with an importable module
|
|||
|
|
and <code class="docutils literal notranslate"><span class="pre">__main__.__spec__</span></code> is set accordingly, they’re still considered
|
|||
|
|
<em>distinct</em> modules. This is due to the fact that blocks guarded by
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">"__main__":</span></code> checks only execute when the module is used
|
|||
|
|
to populate the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> namespace, and not during normal import.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="open-issues">
|
|||
|
|
<h2>5.9. Open issues<a class="headerlink" href="#open-issues" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>XXX It would be really nice to have a diagram.</p>
|
|||
|
|
<p>XXX * (import_machinery.rst) how about a section devoted just to the
|
|||
|
|
attributes of modules and packages, perhaps expanding upon or supplanting the
|
|||
|
|
related entries in the data model reference page?</p>
|
|||
|
|
<p>XXX runpy, pkgutil, et al in the library manual should all get “See Also”
|
|||
|
|
links at the top pointing to the new import system section.</p>
|
|||
|
|
<p>XXX Add more explanation regarding the different ways in which
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__main__</span></code> is initialized?</p>
|
|||
|
|
<p>XXX Add more info on <code class="docutils literal notranslate"><span class="pre">__main__</span></code> quirks/pitfalls (i.e. copy from
|
|||
|
|
<span class="target" id="index-18"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0395"><strong>PEP 395</strong></a>).</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="references">
|
|||
|
|
<h2>5.10. References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The import machinery has evolved considerably since Python’s early days. The
|
|||
|
|
original <a class="reference external" href="https://www.python.org/doc/essays/packages/">specification for packages</a> is still available to read,
|
|||
|
|
although some details have changed since the writing of that document.</p>
|
|||
|
|
<p>The original specification for <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a> was <span class="target" id="index-19"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>, with
|
|||
|
|
subsequent extension in <span class="target" id="index-20"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a>.</p>
|
|||
|
|
<p><span class="target" id="index-21"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a> introduced <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a> for
|
|||
|
|
Python 3.3. <span class="target" id="index-22"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a> also introduced the <code class="xref py py-meth docutils literal notranslate"><span class="pre">find_loader()</span></code> protocol as an
|
|||
|
|
alternative to <code class="xref py py-meth docutils literal notranslate"><span class="pre">find_module()</span></code>.</p>
|
|||
|
|
<p><span class="target" id="index-23"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0366"><strong>PEP 366</strong></a> describes the addition of the <code class="docutils literal notranslate"><span class="pre">__package__</span></code> attribute for
|
|||
|
|
explicit relative imports in main modules.</p>
|
|||
|
|
<p><span class="target" id="index-24"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0328"><strong>PEP 328</strong></a> introduced absolute and explicit relative imports and initially
|
|||
|
|
proposed <code class="docutils literal notranslate"><span class="pre">__name__</span></code> for semantics <span class="target" id="index-25"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0366"><strong>PEP 366</strong></a> would eventually specify for
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__package__</span></code>.</p>
|
|||
|
|
<p><span class="target" id="index-26"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0338"><strong>PEP 338</strong></a> defines executing modules as scripts.</p>
|
|||
|
|
<p><span class="target" id="index-27"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0451"><strong>PEP 451</strong></a> adds the encapsulation of per-module import state in spec
|
|||
|
|
objects. It also off-loads most of the boilerplate responsibilities of
|
|||
|
|
loaders back onto the import machinery. These changes allow the
|
|||
|
|
deprecation of several APIs in the import system and also addition of new
|
|||
|
|
methods to finders and loaders.</p>
|
|||
|
|
<p class="rubric">Footnotes</p>
|
|||
|
|
<dl class="footnote brackets">
|
|||
|
|
<dt class="label" id="fnmo"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
|
|||
|
|
<dd><p>See <a class="reference internal" href="../library/types.html#types.ModuleType" title="types.ModuleType"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ModuleType</span></code></a>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt class="label" id="fnlo"><span class="brackets"><a class="fn-backref" href="#id2">2</a></span></dt>
|
|||
|
|
<dd><p>The importlib implementation avoids using the return value
|
|||
|
|
directly. Instead, it gets the module object by looking the module name up
|
|||
|
|
in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>. The indirect effect of this is that an imported
|
|||
|
|
module may replace itself in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.modules</span></code></a>. This is
|
|||
|
|
implementation-specific behavior that is not guaranteed to work in other
|
|||
|
|
Python implementations.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt class="label" id="fnpic"><span class="brackets"><a class="fn-backref" href="#id3">3</a></span></dt>
|
|||
|
|
<dd><p>In legacy code, it is possible to find instances of
|
|||
|
|
<a class="reference internal" href="../library/imp.html#imp.NullImporter" title="imp.NullImporter"><code class="xref py py-class docutils literal notranslate"><span class="pre">imp.NullImporter</span></code></a> in the <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a>. It
|
|||
|
|
is recommended that code be changed to use <code class="docutils literal notranslate"><span class="pre">None</span></code> instead. See
|
|||
|
|
<a class="reference internal" href="../whatsnew/3.3.html#portingpythoncode"><span class="std std-ref">Porting Python code</span></a> for more details.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#">5. The import system</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#importlib">5.1. <code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code></a></li>
|
|||
|
|
<li><a class="reference internal" href="#packages">5.2. Packages</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#regular-packages">5.2.1. Regular packages</a></li>
|
|||
|
|
<li><a class="reference internal" href="#namespace-packages">5.2.2. Namespace packages</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#searching">5.3. Searching</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#the-module-cache">5.3.1. The module cache</a></li>
|
|||
|
|
<li><a class="reference internal" href="#finders-and-loaders">5.3.2. Finders and loaders</a></li>
|
|||
|
|
<li><a class="reference internal" href="#import-hooks">5.3.3. Import hooks</a></li>
|
|||
|
|
<li><a class="reference internal" href="#the-meta-path">5.3.4. The meta path</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#loading">5.4. Loading</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#loaders">5.4.1. Loaders</a></li>
|
|||
|
|
<li><a class="reference internal" href="#submodules">5.4.2. Submodules</a></li>
|
|||
|
|
<li><a class="reference internal" href="#module-spec">5.4.3. Module spec</a></li>
|
|||
|
|
<li><a class="reference internal" href="#import-related-module-attributes">5.4.4. Import-related module attributes</a></li>
|
|||
|
|
<li><a class="reference internal" href="#module-path">5.4.5. module.__path__</a></li>
|
|||
|
|
<li><a class="reference internal" href="#module-reprs">5.4.6. Module reprs</a></li>
|
|||
|
|
<li><a class="reference internal" href="#cached-bytecode-invalidation">5.4.7. Cached bytecode invalidation</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#the-path-based-finder">5.5. The Path Based Finder</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#path-entry-finders">5.5.1. Path entry finders</a></li>
|
|||
|
|
<li><a class="reference internal" href="#path-entry-finder-protocol">5.5.2. Path entry finder protocol</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#replacing-the-standard-import-system">5.6. Replacing the standard import system</a></li>
|
|||
|
|
<li><a class="reference internal" href="#package-relative-imports">5.7. Package Relative Imports</a></li>
|
|||
|
|
<li><a class="reference internal" href="#special-considerations-for-main">5.8. Special considerations for __main__</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#main-spec">5.8.1. __main__.__spec__</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#open-issues">5.9. Open issues</a></li>
|
|||
|
|
<li><a class="reference internal" href="#references">5.10. References</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="executionmodel.html"
|
|||
|
|
title="previous chapter">4. Execution model</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="expressions.html"
|
|||
|
|
title="next chapter">6. Expressions</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/reference/import.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="expressions.html" title="6. Expressions"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="executionmodel.html" title="4. Execution model"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|