879 lines
71 KiB
HTML
879 lines
71 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="6. Modules" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/tutorial/modules.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are bett..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are bett..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>6. Modules — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 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="7. Input and Output" href="inputoutput.html" />
|
||
<link rel="prev" title="5. Data Structures" href="datastructures.html" />
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/tutorial/modules.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">6. Modules</a><ul>
|
||
<li><a class="reference internal" href="#more-on-modules">6.1. More on Modules</a><ul>
|
||
<li><a class="reference internal" href="#executing-modules-as-scripts">6.1.1. Executing modules as scripts</a></li>
|
||
<li><a class="reference internal" href="#the-module-search-path">6.1.2. The Module Search Path</a></li>
|
||
<li><a class="reference internal" href="#compiled-python-files">6.1.3. “Compiled” Python files</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#standard-modules">6.2. Standard Modules</a></li>
|
||
<li><a class="reference internal" href="#the-dir-function">6.3. The <code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code> Function</a></li>
|
||
<li><a class="reference internal" href="#packages">6.4. Packages</a><ul>
|
||
<li><a class="reference internal" href="#importing-from-a-package">6.4.1. Importing * From a Package</a></li>
|
||
<li><a class="reference internal" href="#intra-package-references">6.4.2. Intra-package References</a></li>
|
||
<li><a class="reference internal" href="#packages-in-multiple-directories">6.4.3. Packages in Multiple Directories</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="datastructures.html"
|
||
title="previous chapter"><span class="section-number">5. </span>Data Structures</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="inputoutput.html"
|
||
title="next chapter"><span class="section-number">7. </span>Input and Output</a></p>
|
||
</div>
|
||
<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/main/Doc/tutorial/modules.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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="inputoutput.html" title="7. Input and Output"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="datastructures.html" title="5. Data Structures"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Python Tutorial</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">6. </span>Modules</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="modules">
|
||
<span id="tut-modules"></span><h1><span class="section-number">6. </span>Modules<a class="headerlink" href="#modules" title="Link to this heading">¶</a></h1>
|
||
<p>If you quit from the Python interpreter and enter it again, the definitions you
|
||
have made (functions and variables) are lost. Therefore, if you want to write a
|
||
somewhat longer program, you are better off using a text editor to prepare the
|
||
input for the interpreter and running it with that file as input instead. This
|
||
is known as creating a <em>script</em>. As your program gets longer, you may want to
|
||
split it into several files for easier maintenance. You may also want to use a
|
||
handy function that you’ve written in several programs without copying its
|
||
definition into each program.</p>
|
||
<p>To support this, Python has a way to put definitions in a file and use them in a
|
||
script or in an interactive instance of the interpreter. Such a file is called a
|
||
<em>module</em>; definitions from a module can be <em>imported</em> into other modules or into
|
||
the <em>main</em> module (the collection of variables that you have access to in a
|
||
script executed at the top level and in calculator mode).</p>
|
||
<p>A module is a file containing Python definitions and statements. The file name
|
||
is the module name with the suffix <code class="file docutils literal notranslate"><span class="pre">.py</span></code> appended. Within a module, the
|
||
module’s name (as a string) is available as the value of the global variable
|
||
<code class="docutils literal notranslate"><span class="pre">__name__</span></code>. For instance, use your favorite text editor to create a file
|
||
called <code class="file docutils literal notranslate"><span class="pre">fibo.py</span></code> in the current directory with the following contents:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Fibonacci numbers module</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">fib</span><span class="p">(</span><span class="n">n</span><span class="p">):</span> <span class="c1"># write Fibonacci series up to n</span>
|
||
<span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>
|
||
<span class="k">while</span> <span class="n">a</span> <span class="o"><</span> <span class="n">n</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s1">' '</span><span class="p">)</span>
|
||
<span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="o">+</span><span class="n">b</span>
|
||
<span class="nb">print</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">fib2</span><span class="p">(</span><span class="n">n</span><span class="p">):</span> <span class="c1"># return Fibonacci series up to n</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="p">[]</span>
|
||
<span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>
|
||
<span class="k">while</span> <span class="n">a</span> <span class="o"><</span> <span class="n">n</span><span class="p">:</span>
|
||
<span class="n">result</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">=</span> <span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="o">+</span><span class="n">b</span>
|
||
<span class="k">return</span> <span class="n">result</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Now enter the Python interpreter and import this module with the following
|
||
command:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">fibo</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This does not add the names of the functions defined in <code class="docutils literal notranslate"><span class="pre">fibo</span></code> directly to
|
||
the current <a class="reference internal" href="../glossary.html#term-namespace"><span class="xref std std-term">namespace</span></a> (see <a class="reference internal" href="classes.html#tut-scopes"><span class="std std-ref">Python Scopes and Namespaces</span></a> for more details);
|
||
it only adds the module name <code class="docutils literal notranslate"><span class="pre">fibo</span></code> there. Using
|
||
the module name you can access the functions:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">fibo</span><span class="o">.</span><span class="n">fib</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987</span>
|
||
<span class="gp">>>> </span><span class="n">fibo</span><span class="o">.</span><span class="n">fib2</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
|
||
<span class="go">[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]</span>
|
||
<span class="gp">>>> </span><span class="n">fibo</span><span class="o">.</span><span class="vm">__name__</span>
|
||
<span class="go">'fibo'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you intend to use a function often you can assign it to a local name:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">fib</span> <span class="o">=</span> <span class="n">fibo</span><span class="o">.</span><span class="n">fib</span>
|
||
<span class="gp">>>> </span><span class="n">fib</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377</span>
|
||
</pre></div>
|
||
</div>
|
||
<section id="more-on-modules">
|
||
<span id="tut-moremodules"></span><h2><span class="section-number">6.1. </span>More on Modules<a class="headerlink" href="#more-on-modules" title="Link to this heading">¶</a></h2>
|
||
<p>A module can contain executable statements as well as function definitions.
|
||
These statements are intended to initialize the module. They are executed only
|
||
the <em>first</em> time the module name is encountered in an import statement. <a class="footnote-reference brackets" href="#id3" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>
|
||
(They are also run if the file is executed as a script.)</p>
|
||
<p>Each module has its own private namespace, which is used as the global namespace
|
||
by all functions defined in the module. Thus, the author of a module can
|
||
use global variables in the module without worrying about accidental clashes
|
||
with a user’s global variables. On the other hand, if you know what you are
|
||
doing you can touch a module’s global variables with the same notation used to
|
||
refer to its functions, <code class="docutils literal notranslate"><span class="pre">modname.itemname</span></code>.</p>
|
||
<p>Modules can import other modules. It is customary but not required to place all
|
||
<a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statements at the beginning of a module (or script, for that
|
||
matter). The imported module names, if placed at the top level of a module
|
||
(outside any functions or classes), are added to the module’s global namespace.</p>
|
||
<p>There is a variant of the <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement that imports names from a
|
||
module directly into the importing module’s namespace. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">fibo</span><span class="w"> </span><span class="kn">import</span> <span class="n">fib</span><span class="p">,</span> <span class="n">fib2</span>
|
||
<span class="gp">>>> </span><span class="n">fib</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This does not introduce the module name from which the imports are taken in the
|
||
local namespace (so in the example, <code class="docutils literal notranslate"><span class="pre">fibo</span></code> is not defined).</p>
|
||
<p>There is even a variant to import all names that a module defines:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">fibo</span><span class="w"> </span><span class="kn">import</span> <span class="o">*</span>
|
||
<span class="gp">>>> </span><span class="n">fib</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This imports all names except those beginning with an underscore (<code class="docutils literal notranslate"><span class="pre">_</span></code>).
|
||
In most cases Python programmers do not use this facility since it introduces
|
||
an unknown set of names into the interpreter, possibly hiding some things
|
||
you have already defined.</p>
|
||
<p>Note that in general the practice of importing <code class="docutils literal notranslate"><span class="pre">*</span></code> from a module or package is
|
||
frowned upon, since it often causes poorly readable code. However, it is okay to
|
||
use it to save typing in interactive sessions.</p>
|
||
<p>If the module name is followed by <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code>, then the name
|
||
following <code class="xref std std-keyword docutils literal notranslate"><span class="pre">as</span></code> is bound directly to the imported module.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">fibo</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">fib</span>
|
||
<span class="gp">>>> </span><span class="n">fib</span><span class="o">.</span><span class="n">fib</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This is effectively importing the module in the same way that <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">fibo</span></code>
|
||
will do, with the only difference of it being available as <code class="docutils literal notranslate"><span class="pre">fib</span></code>.</p>
|
||
<p>It can also be used when utilising <a class="reference internal" href="../reference/simple_stmts.html#from"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">from</span></code></a> with similar effects:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">fibo</span><span class="w"> </span><span class="kn">import</span> <span class="n">fib</span> <span class="k">as</span> <span class="n">fibonacci</span>
|
||
<span class="gp">>>> </span><span class="n">fibonacci</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34 55 89 144 233 377</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For efficiency reasons, each module is only imported once per interpreter
|
||
session. Therefore, if you change your modules, you must restart the
|
||
interpreter – or, if it’s just one module you want to test interactively,
|
||
use <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>, e.g. <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">importlib;</span>
|
||
<span class="pre">importlib.reload(modulename)</span></code>.</p>
|
||
</div>
|
||
<section id="executing-modules-as-scripts">
|
||
<span id="tut-modulesasscripts"></span><h3><span class="section-number">6.1.1. </span>Executing modules as scripts<a class="headerlink" href="#executing-modules-as-scripts" title="Link to this heading">¶</a></h3>
|
||
<p>When you run a Python module with</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">fibo</span><span class="o">.</span><span class="n">py</span> <span class="o"><</span><span class="n">arguments</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>the code in the module will be executed, just as if you imported it, but with
|
||
the <code class="docutils literal notranslate"><span class="pre">__name__</span></code> set to <code class="docutils literal notranslate"><span class="pre">"__main__"</span></code>. That means that by adding this code at
|
||
the end of your module:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
|
||
<span class="n">fib</span><span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>you can make the file usable as a script as well as an importable module,
|
||
because the code that parses the command line only runs if the module is
|
||
executed as the “main” file:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>fibo.py<span class="w"> </span><span class="m">50</span>
|
||
<span class="go">0 1 1 2 3 5 8 13 21 34</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If the module is imported, the code is not run:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">fibo</span>
|
||
<span class="gp">>>></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This is often used either to provide a convenient user interface to a module, or
|
||
for testing purposes (running the module as a script executes a test suite).</p>
|
||
</section>
|
||
<section id="the-module-search-path">
|
||
<span id="tut-searchpath"></span><h3><span class="section-number">6.1.2. </span>The Module Search Path<a class="headerlink" href="#the-module-search-path" title="Link to this heading">¶</a></h3>
|
||
<p id="index-0">When a module named <code class="xref py py-mod docutils literal notranslate"><span class="pre">spam</span></code> is imported, the interpreter first searches for
|
||
a built-in module with that name. These module names are listed in
|
||
<a class="reference internal" href="../library/sys.html#sys.builtin_module_names" title="sys.builtin_module_names"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.builtin_module_names</span></code></a>. If not found, it then searches for a file
|
||
named <code class="file docutils literal notranslate"><span class="pre">spam.py</span></code> in a list of directories given by the variable
|
||
<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" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> is initialized from these locations:</p>
|
||
<ul class="simple">
|
||
<li><p>The directory containing the input script (or the current directory when no
|
||
file is specified).</p></li>
|
||
<li><p><span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> (a list of directory names, with the same syntax as the
|
||
shell variable <span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>).</p></li>
|
||
<li><p>The installation-dependent default (by convention including a
|
||
<code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, handled by 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).</p></li>
|
||
</ul>
|
||
<p>More details are at <a class="reference internal" href="../library/sys_path_init.html#sys-path-init"><span class="std std-ref">The initialization of the sys.path module search path</span></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On file systems which support symlinks, the directory containing the input
|
||
script is calculated after the symlink is followed. In other words the
|
||
directory containing the symlink is <strong>not</strong> added to the module search path.</p>
|
||
</div>
|
||
<p>After initialization, Python programs can modify <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>. The
|
||
directory containing the script being run is placed at the beginning of the
|
||
search path, ahead of the standard library path. This means that scripts in that
|
||
directory will be loaded instead of modules of the same name in the library
|
||
directory. This is an error unless the replacement is intended. See section
|
||
<a class="reference internal" href="#tut-standardmodules"><span class="std std-ref">Standard Modules</span></a> for more information.</p>
|
||
</section>
|
||
<section id="compiled-python-files">
|
||
<span id="tut-pycache"></span><h3><span class="section-number">6.1.3. </span>“Compiled” Python files<a class="headerlink" href="#compiled-python-files" title="Link to this heading">¶</a></h3>
|
||
<p>To speed up loading modules, Python caches the compiled version of each module
|
||
in the <code class="docutils literal notranslate"><span class="pre">__pycache__</span></code> directory under the name <code class="file docutils literal notranslate"><span class="pre">module.</span><em><span class="pre">version</span></em><span class="pre">.pyc</span></code>,
|
||
where the version encodes the format of the compiled file; it generally contains
|
||
the Python version number. For example, in CPython release 3.3 the compiled
|
||
version of spam.py would be cached as <code class="docutils literal notranslate"><span class="pre">__pycache__/spam.cpython-33.pyc</span></code>. This
|
||
naming convention allows compiled modules from different releases and different
|
||
versions of Python to coexist.</p>
|
||
<p>Python checks the modification date of the source against the compiled version
|
||
to see if it’s out of date and needs to be recompiled. This is a completely
|
||
automatic process. Also, the compiled modules are platform-independent, so the
|
||
same library can be shared among systems with different architectures.</p>
|
||
<p>Python does not check the cache in two circumstances. First, it always
|
||
recompiles and does not store the result for the module that’s loaded directly
|
||
from the command line. Second, it does not check the cache if there is no
|
||
source module. To support a non-source (compiled only) distribution, the
|
||
compiled module must be in the source directory, and there must not be a source
|
||
module.</p>
|
||
<p>Some tips for experts:</p>
|
||
<ul class="simple">
|
||
<li><p>You can use the <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal notranslate"><span class="pre">-O</span></code></a> or <a class="reference internal" href="../using/cmdline.html#cmdoption-OO"><code class="xref std std-option docutils literal notranslate"><span class="pre">-OO</span></code></a> switches on the Python command
|
||
to reduce the size of a compiled module. The <code class="docutils literal notranslate"><span class="pre">-O</span></code> switch removes assert
|
||
statements, the <code class="docutils literal notranslate"><span class="pre">-OO</span></code> switch removes both assert statements and __doc__
|
||
strings. Since some programs may rely on having these available, you should
|
||
only use this option if you know what you’re doing. “Optimized” modules have
|
||
an <code class="docutils literal notranslate"><span class="pre">opt-</span></code> tag and are usually smaller. Future releases may
|
||
change the effects of optimization.</p></li>
|
||
<li><p>A program doesn’t run any faster when it is read from a <code class="docutils literal notranslate"><span class="pre">.pyc</span></code>
|
||
file than when it is read from a <code class="docutils literal notranslate"><span class="pre">.py</span></code> file; the only thing that’s faster
|
||
about <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files is the speed with which they are loaded.</p></li>
|
||
<li><p>The module <a class="reference internal" href="../library/compileall.html#module-compileall" title="compileall: Tools for byte-compiling all Python source files in a directory tree."><code class="xref py py-mod docutils literal notranslate"><span class="pre">compileall</span></code></a> can create .pyc files for all modules in a
|
||
directory.</p></li>
|
||
<li><p>There is more detail on this process, including a flow chart of the
|
||
decisions, in <span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a>.</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="standard-modules">
|
||
<span id="tut-standardmodules"></span><h2><span class="section-number">6.2. </span>Standard Modules<a class="headerlink" href="#standard-modules" title="Link to this heading">¶</a></h2>
|
||
<p id="index-4">Python comes with a library of standard modules, described in a separate
|
||
document, the Python Library Reference (“Library Reference” hereafter). Some
|
||
modules are built into the interpreter; these provide access to operations that
|
||
are not part of the core of the language but are nevertheless built in, either
|
||
for efficiency or to provide access to operating system primitives such as
|
||
system calls. The set of such modules is a configuration option which also
|
||
depends on the underlying platform. For example, the <a class="reference internal" href="../library/winreg.html#module-winreg" title="winreg: Routines and objects for manipulating the Windows registry. (Windows)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">winreg</span></code></a> module is only
|
||
provided on Windows systems. One particular module deserves some attention:
|
||
<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>, which is built into every Python interpreter. The variables
|
||
<code class="docutils literal notranslate"><span class="pre">sys.ps1</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.ps2</span></code> define the strings used as primary and secondary
|
||
prompts:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
|
||
<span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">ps1</span>
|
||
<span class="go">'>>> '</span>
|
||
<span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">ps2</span>
|
||
<span class="go">'... '</span>
|
||
<span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">ps1</span> <span class="o">=</span> <span class="s1">'C> '</span>
|
||
<span class="go">C> print('Yuck!')</span>
|
||
<span class="go">Yuck!</span>
|
||
<span class="go">C></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>These two variables are only defined if the interpreter is in interactive mode.</p>
|
||
<p>The variable <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is a list of strings that determines the interpreter’s
|
||
search path for modules. It is initialized to a default path taken from the
|
||
environment variable <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a>, or from a built-in default if
|
||
<span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> is not set. You can modify it using standard list
|
||
operations:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
|
||
<span class="gp">>>> </span><span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">'/ufs/guido/lib/python'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="the-dir-function">
|
||
<span id="tut-dir"></span><h2><span class="section-number">6.3. </span>The <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> Function<a class="headerlink" href="#the-dir-function" title="Link to this heading">¶</a></h2>
|
||
<p>The built-in function <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> is used to find out which names a module
|
||
defines. It returns a sorted list of strings:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">fibo</span><span class="o">,</span><span class="w"> </span><span class="nn">sys</span>
|
||
<span class="gp">>>> </span><span class="nb">dir</span><span class="p">(</span><span class="n">fibo</span><span class="p">)</span>
|
||
<span class="go">['__name__', 'fib', 'fib2']</span>
|
||
<span class="gp">>>> </span><span class="nb">dir</span><span class="p">(</span><span class="n">sys</span><span class="p">)</span>
|
||
<span class="go">['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',</span>
|
||
<span class="go"> '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',</span>
|
||
<span class="go"> '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',</span>
|
||
<span class="go"> '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',</span>
|
||
<span class="go"> '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',</span>
|
||
<span class="go"> 'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',</span>
|
||
<span class="go"> 'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',</span>
|
||
<span class="go"> 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',</span>
|
||
<span class="go"> 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',</span>
|
||
<span class="go"> 'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',</span>
|
||
<span class="go"> 'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',</span>
|
||
<span class="go"> 'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',</span>
|
||
<span class="go"> 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',</span>
|
||
<span class="go"> 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',</span>
|
||
<span class="go"> 'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',</span>
|
||
<span class="go"> 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',</span>
|
||
<span class="go"> 'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',</span>
|
||
<span class="go"> 'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',</span>
|
||
<span class="go"> 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',</span>
|
||
<span class="go"> 'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',</span>
|
||
<span class="go"> 'warnoptions']</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Without arguments, <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> lists the names you have defined currently:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">fibo</span>
|
||
<span class="gp">>>> </span><span class="n">fib</span> <span class="o">=</span> <span class="n">fibo</span><span class="o">.</span><span class="n">fib</span>
|
||
<span class="gp">>>> </span><span class="nb">dir</span><span class="p">()</span>
|
||
<span class="go">['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that it lists all types of names: variables, modules, functions, etc.</p>
|
||
<p id="index-7"><a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> does not list the names of built-in functions and variables. If you
|
||
want a list of those, they are defined in the standard module
|
||
<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>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">builtins</span>
|
||
<span class="gp">>>> </span><span class="nb">dir</span><span class="p">(</span><span class="n">builtins</span><span class="p">)</span>
|
||
<span class="go">['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',</span>
|
||
<span class="go"> 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',</span>
|
||
<span class="go"> 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',</span>
|
||
<span class="go"> 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',</span>
|
||
<span class="go"> 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',</span>
|
||
<span class="go"> 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',</span>
|
||
<span class="go"> 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',</span>
|
||
<span class="go"> 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',</span>
|
||
<span class="go"> 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',</span>
|
||
<span class="go"> 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',</span>
|
||
<span class="go"> 'NotImplementedError', 'OSError', 'OverflowError',</span>
|
||
<span class="go"> 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',</span>
|
||
<span class="go"> 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',</span>
|
||
<span class="go"> 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',</span>
|
||
<span class="go"> 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',</span>
|
||
<span class="go"> 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',</span>
|
||
<span class="go"> 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',</span>
|
||
<span class="go"> 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',</span>
|
||
<span class="go"> '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',</span>
|
||
<span class="go"> 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',</span>
|
||
<span class="go"> 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',</span>
|
||
<span class="go"> 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',</span>
|
||
<span class="go"> 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',</span>
|
||
<span class="go"> 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',</span>
|
||
<span class="go"> 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',</span>
|
||
<span class="go"> 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',</span>
|
||
<span class="go"> 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',</span>
|
||
<span class="go"> 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',</span>
|
||
<span class="go"> 'zip']</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="packages">
|
||
<span id="tut-packages"></span><h2><span class="section-number">6.4. </span>Packages<a class="headerlink" href="#packages" title="Link to this heading">¶</a></h2>
|
||
<p>Packages are a way of structuring Python’s module namespace by using “dotted
|
||
module names”. For example, the module name <code class="xref py py-mod docutils literal notranslate"><span class="pre">A.B</span></code> designates a submodule
|
||
named <code class="docutils literal notranslate"><span class="pre">B</span></code> in a package named <code class="docutils literal notranslate"><span class="pre">A</span></code>. Just like the use of modules saves the
|
||
authors of different modules from having to worry about each other’s global
|
||
variable names, the use of dotted module names saves the authors of multi-module
|
||
packages like NumPy or Pillow from having to worry about
|
||
each other’s module names.</p>
|
||
<p>Suppose you want to design a collection of modules (a “package”) for the uniform
|
||
handling of sound files and sound data. There are many different sound file
|
||
formats (usually recognized by their extension, for example: <code class="file docutils literal notranslate"><span class="pre">.wav</span></code>,
|
||
<code class="file docutils literal notranslate"><span class="pre">.aiff</span></code>, <code class="file docutils literal notranslate"><span class="pre">.au</span></code>), so you may need to create and maintain a growing
|
||
collection of modules for the conversion between the various file formats.
|
||
There are also many different operations you might want to perform on sound data
|
||
(such as mixing, adding echo, applying an equalizer function, creating an
|
||
artificial stereo effect), so in addition you will be writing a never-ending
|
||
stream of modules to perform these operations. Here’s a possible structure for
|
||
your package (expressed in terms of a hierarchical filesystem):</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sound/ Top-level package
|
||
__init__.py Initialize the sound package
|
||
formats/ Subpackage for file format conversions
|
||
__init__.py
|
||
wavread.py
|
||
wavwrite.py
|
||
aiffread.py
|
||
aiffwrite.py
|
||
auread.py
|
||
auwrite.py
|
||
...
|
||
effects/ Subpackage for sound effects
|
||
__init__.py
|
||
echo.py
|
||
surround.py
|
||
reverse.py
|
||
...
|
||
filters/ Subpackage for filters
|
||
__init__.py
|
||
equalizer.py
|
||
vocoder.py
|
||
karaoke.py
|
||
...
|
||
</pre></div>
|
||
</div>
|
||
<p>When importing the package, Python searches through the directories on
|
||
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> looking for the package subdirectory.</p>
|
||
<p>The <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> files are required to make Python treat directories
|
||
containing the file as packages (unless using a <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace package</span></a>, a
|
||
relatively advanced feature). This prevents directories with a common name,
|
||
such as <code class="docutils literal notranslate"><span class="pre">string</span></code>, from unintentionally hiding valid modules that occur later
|
||
on the module search path. In the simplest case, <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> can just be
|
||
an empty file, but it can also execute initialization code for the package or
|
||
set the <code class="docutils literal notranslate"><span class="pre">__all__</span></code> variable, described later.</p>
|
||
<p>Users of the package can import individual modules from the package, for
|
||
example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">sound.effects.echo</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This loads the submodule <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects.echo</span></code>. It must be referenced with
|
||
its full name.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sound</span><span class="o">.</span><span class="n">effects</span><span class="o">.</span><span class="n">echo</span><span class="o">.</span><span class="n">echofilter</span><span class="p">(</span><span class="nb">input</span><span class="p">,</span> <span class="n">output</span><span class="p">,</span> <span class="n">delay</span><span class="o">=</span><span class="mf">0.7</span><span class="p">,</span> <span class="n">atten</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>An alternative way of importing the submodule is:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">sound.effects</span><span class="w"> </span><span class="kn">import</span> <span class="n">echo</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This also loads the submodule <code class="xref py py-mod docutils literal notranslate"><span class="pre">echo</span></code>, and makes it available without its
|
||
package prefix, so it can be used as follows:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">echo</span><span class="o">.</span><span class="n">echofilter</span><span class="p">(</span><span class="nb">input</span><span class="p">,</span> <span class="n">output</span><span class="p">,</span> <span class="n">delay</span><span class="o">=</span><span class="mf">0.7</span><span class="p">,</span> <span class="n">atten</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Yet another variation is to import the desired function or variable directly:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">sound.effects.echo</span><span class="w"> </span><span class="kn">import</span> <span class="n">echofilter</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Again, this loads the submodule <code class="xref py py-mod docutils literal notranslate"><span class="pre">echo</span></code>, but this makes its function
|
||
<code class="xref py py-func docutils literal notranslate"><span class="pre">echofilter()</span></code> directly available:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">echofilter</span><span class="p">(</span><span class="nb">input</span><span class="p">,</span> <span class="n">output</span><span class="p">,</span> <span class="n">delay</span><span class="o">=</span><span class="mf">0.7</span><span class="p">,</span> <span class="n">atten</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that when using <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">package</span> <span class="pre">import</span> <span class="pre">item</span></code>, the item can be either a
|
||
submodule (or subpackage) of the package, or some other name defined in the
|
||
package, like a function, class or variable. The <code class="docutils literal notranslate"><span class="pre">import</span></code> statement first
|
||
tests whether the item is defined in the package; if not, it assumes it is a
|
||
module and attempts to load it. If it fails to find it, 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>
|
||
exception is raised.</p>
|
||
<p>Contrarily, when using syntax like <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">item.subitem.subsubitem</span></code>, each item
|
||
except for the last must be a package; the last item can be a module or a
|
||
package but can’t be a class or function or variable defined in the previous
|
||
item.</p>
|
||
<section id="importing-from-a-package">
|
||
<span id="tut-pkg-import-star"></span><h3><span class="section-number">6.4.1. </span>Importing * From a Package<a class="headerlink" href="#importing-from-a-package" title="Link to this heading">¶</a></h3>
|
||
<p id="index-8">Now what happens when the user writes <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sound.effects</span> <span class="pre">import</span> <span class="pre">*</span></code>? Ideally,
|
||
one would hope that this somehow goes out to the filesystem, finds which
|
||
submodules are present in the package, and imports them all. This could take a
|
||
long time and importing sub-modules might have unwanted side-effects that should
|
||
only happen when the sub-module is explicitly imported.</p>
|
||
<p>The only solution is for the package author to provide an explicit index of the
|
||
package. The <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statement uses the following convention: if a package’s
|
||
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> code defines a list named <code class="docutils literal notranslate"><span class="pre">__all__</span></code>, it is taken to be the
|
||
list of module names that should be imported when <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">package</span> <span class="pre">import</span> <span class="pre">*</span></code> is
|
||
encountered. It is up to the package author to keep this list up-to-date when a
|
||
new version of the package is released. Package authors may also decide not to
|
||
support it, if they don’t see a use for importing * from their package. For
|
||
example, the file <code class="file docutils literal notranslate"><span class="pre">sound/effects/__init__.py</span></code> could contain the following
|
||
code:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"echo"</span><span class="p">,</span> <span class="s2">"surround"</span><span class="p">,</span> <span class="s2">"reverse"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This would mean that <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sound.effects</span> <span class="pre">import</span> <span class="pre">*</span></code> would import the three
|
||
named submodules of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects</span></code> package.</p>
|
||
<p>Be aware that submodules might become shadowed by locally defined names. For
|
||
example, if you added a <code class="docutils literal notranslate"><span class="pre">reverse</span></code> function to the
|
||
<code class="file docutils literal notranslate"><span class="pre">sound/effects/__init__.py</span></code> file, the <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sound.effects</span> <span class="pre">import</span> <span class="pre">*</span></code>
|
||
would only import the two submodules <code class="docutils literal notranslate"><span class="pre">echo</span></code> and <code class="docutils literal notranslate"><span class="pre">surround</span></code>, but <em>not</em> the
|
||
<code class="docutils literal notranslate"><span class="pre">reverse</span></code> submodule, because it is shadowed by the locally defined
|
||
<code class="docutils literal notranslate"><span class="pre">reverse</span></code> function:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="s2">"echo"</span><span class="p">,</span> <span class="c1"># refers to the 'echo.py' file</span>
|
||
<span class="s2">"surround"</span><span class="p">,</span> <span class="c1"># refers to the 'surround.py' file</span>
|
||
<span class="s2">"reverse"</span><span class="p">,</span> <span class="c1"># !!! refers to the 'reverse' function now !!!</span>
|
||
<span class="p">]</span>
|
||
|
||
<span class="k">def</span><span class="w"> </span><span class="nf">reverse</span><span class="p">(</span><span class="n">msg</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span> <span class="c1"># <-- this name shadows the 'reverse.py' submodule</span>
|
||
<span class="k">return</span> <span class="n">msg</span><span class="p">[::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># in the case of a 'from sound.effects import *'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">__all__</span></code> is not defined, the statement <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sound.effects</span> <span class="pre">import</span> <span class="pre">*</span></code>
|
||
does <em>not</em> import all submodules from the package <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects</span></code> into the
|
||
current namespace; it only ensures that the package <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects</span></code> has
|
||
been imported (possibly running any initialization code in <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code>)
|
||
and then imports whatever names are defined in the package. This includes any
|
||
names defined (and submodules explicitly loaded) by <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code>. It
|
||
also includes any submodules of the package that were explicitly loaded by
|
||
previous <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a> statements. Consider this code:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">sound.effects.echo</span>
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">sound.effects.surround</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">sound.effects</span><span class="w"> </span><span class="kn">import</span> <span class="o">*</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In this example, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">echo</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">surround</span></code> modules are imported in the
|
||
current namespace because they are defined in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects</span></code> package
|
||
when the <code class="docutils literal notranslate"><span class="pre">from...import</span></code> statement is executed. (This also works when
|
||
<code class="docutils literal notranslate"><span class="pre">__all__</span></code> is defined.)</p>
|
||
<p>Although certain modules are designed to export only names that follow certain
|
||
patterns when you use <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">*</span></code>, it is still considered bad practice in
|
||
production code.</p>
|
||
<p>Remember, there is nothing wrong with using <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">package</span> <span class="pre">import</span>
|
||
<span class="pre">specific_submodule</span></code>! In fact, this is the recommended notation unless the
|
||
importing module needs to use submodules with the same name from different
|
||
packages.</p>
|
||
</section>
|
||
<section id="intra-package-references">
|
||
<span id="id2"></span><h3><span class="section-number">6.4.2. </span>Intra-package References<a class="headerlink" href="#intra-package-references" title="Link to this heading">¶</a></h3>
|
||
<p>When packages are structured into subpackages (as with the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound</span></code> package
|
||
in the example), you can use absolute imports to refer to submodules of siblings
|
||
packages. For example, if the module <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.filters.vocoder</span></code> needs to use
|
||
the <code class="xref py py-mod docutils literal notranslate"><span class="pre">echo</span></code> module in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sound.effects</span></code> package, it can use <code class="docutils literal notranslate"><span class="pre">from</span>
|
||
<span class="pre">sound.effects</span> <span class="pre">import</span> <span class="pre">echo</span></code>.</p>
|
||
<p>You can also write relative imports, with the <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">module</span> <span class="pre">import</span> <span class="pre">name</span></code> form
|
||
of import statement. These imports use leading dots to indicate the current and
|
||
parent packages involved in the relative import. From the <code class="xref py py-mod docutils literal notranslate"><span class="pre">surround</span></code>
|
||
module for example, you might use:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">.</span><span class="w"> </span><span class="kn">import</span> <span class="n">echo</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">..</span><span class="w"> </span><span class="kn">import</span> <span class="n">formats</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">..filters</span><span class="w"> </span><span class="kn">import</span> <span class="n">equalizer</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that relative imports are based on the name of the current module. Since
|
||
the name of the main module is always <code class="docutils literal notranslate"><span class="pre">"__main__"</span></code>, modules intended for use
|
||
as the main module of a Python application must always use absolute imports.</p>
|
||
</section>
|
||
<section id="packages-in-multiple-directories">
|
||
<h3><span class="section-number">6.4.3. </span>Packages in Multiple Directories<a class="headerlink" href="#packages-in-multiple-directories" title="Link to this heading">¶</a></h3>
|
||
<p>Packages support one more special attribute, <a class="reference internal" href="../reference/datamodel.html#module.__path__" title="module.__path__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__path__</span></code></a>. This is
|
||
initialized to be a <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a> of strings containing the name of the
|
||
directory holding the
|
||
package’s <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> before the code in that file is executed. This
|
||
variable can be modified; doing so affects future searches for modules and
|
||
subpackages contained in the package.</p>
|
||
<p>While this feature is not often needed, it can be used to extend the set of
|
||
modules found in a package.</p>
|
||
<p class="rubric">Footnotes</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id3" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
|
||
<p>In fact function definitions are also ‘statements’ that are ‘executed’; the
|
||
execution of a module-level function definition adds the function name to
|
||
the module’s global namespace.</p>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">6. Modules</a><ul>
|
||
<li><a class="reference internal" href="#more-on-modules">6.1. More on Modules</a><ul>
|
||
<li><a class="reference internal" href="#executing-modules-as-scripts">6.1.1. Executing modules as scripts</a></li>
|
||
<li><a class="reference internal" href="#the-module-search-path">6.1.2. The Module Search Path</a></li>
|
||
<li><a class="reference internal" href="#compiled-python-files">6.1.3. “Compiled” Python files</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#standard-modules">6.2. Standard Modules</a></li>
|
||
<li><a class="reference internal" href="#the-dir-function">6.3. The <code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code> Function</a></li>
|
||
<li><a class="reference internal" href="#packages">6.4. Packages</a><ul>
|
||
<li><a class="reference internal" href="#importing-from-a-package">6.4.1. Importing * From a Package</a></li>
|
||
<li><a class="reference internal" href="#intra-package-references">6.4.2. Intra-package References</a></li>
|
||
<li><a class="reference internal" href="#packages-in-multiple-directories">6.4.3. Packages in Multiple Directories</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="datastructures.html"
|
||
title="previous chapter"><span class="section-number">5. </span>Data Structures</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="inputoutput.html"
|
||
title="next chapter"><span class="section-number">7. </span>Input and Output</a></p>
|
||
</div>
|
||
<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/main/Doc/tutorial/modules.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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="inputoutput.html" title="7. Input and Output"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="datastructures.html" title="5. Data Structures"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Tutorial</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">6. </span>Modules</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |