ProgrammingInPython/modules/Modules.html at gh-pages · UWPCE-PythonCert/ProgrammingInPython

483 lines (447 loc) · 40.4 KB
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Code Structure, Modules, and Namespaces &mdash; Programming in Python 7.0 documentation</title>
      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
        <script src="../_static/jquery.js"></script>
        <script src="../_static/underscore.js"></script>
        <script src="../_static/doctools.js"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Documentation" href="Documentation.html" />
    <link rel="prev" title="Style and Naming" href="NamingThings.html" /> 
<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #4b2e83" >
            <a href="../index.html">
            <img src="../_static/UWPCE_logo_full.png" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Topics in the Program</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../topics/01-setting_up/index.html">1. Setting up your Environment</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/02-basic_python/index.html">2. Basic Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/03-recursion_booleans/index.html">3. Booleans and Recursion</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/04-sequences_iteration/index.html">4. Sequences and Iteration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/05-text_handling/index.html">5. Basic Text Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/06-exceptions/index.html">6. Exception Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/07-unit_testing/index.html">7. Unit Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/08-dicts_sets/index.html">8. Dictionaries and Sets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/09-files/index.html">9. File Handling</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../topics/10-modules_packages/index.html">10. Modules and Packages</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="NamingThings.html">Style and Naming</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Code Structure, Modules, and Namespaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="Documentation.html">Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="Packaging.html">Packages and Packaging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../exercises/packaging/package_lab.html">A Small Example Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../exercises/mailroom/mailroom-pkg.html">Mailroom – as a Python Package</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/11-argument_passing/index.html">11. Advanced Argument Passing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/12-comprehensions/index.html">12. Comprehensions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/13-intro_oo/index.html">13. Intro to Object Oriented Programing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/14-magic_methods/index.html">14. Properties and Magic Methods</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/15-subclassing/index.html">15. Subclassing and Inheritance</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/16-multiple_inheritance/index.html">16. Multiple Inheritance</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/17-functional_programming/index.html">17. Introduction to Functional Programming</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/18-advanced_testing/index.html">18. Advanced Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../topics/99-extras/index.html">19. Extra Topics</a></li>
        </div>
      </div>
    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: #4b2e83" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">Programming in Python</a>
      </nav>
      <div class="wy-nav-content">
        <div class="rst-content style-external-links">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
          <li><a href="../topics/10-modules_packages/index.html"><span class="section-number">10. </span>Modules and Packages</a> &raquo;</li>
      <li>Code Structure, Modules, and Namespaces</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/modules/Modules.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
        <a href="NamingThings.html" class="btn btn-neutral float-left" title="Style and Naming" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="Documentation.html" class="btn btn-neutral float-right" title="Documentation" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
  <div class="section" id="code-structure-modules-and-namespaces">
<span id="modules-and-namespaces"></span><h1>Code Structure, Modules, and Namespaces<a class="headerlink" href="#code-structure-modules-and-namespaces" title="Permalink to this headline"></a></h1>
<p class="centered">
<strong><strong>How to get what you want when you want it</strong></strong></p><div class="section" id="code-structure">
<h2>Code Structure<a class="headerlink" href="#code-structure" title="Permalink to this headline"></a></h2>
<p>In Python, the structure of your code is determined by whitespace. This is nicely clear, and you’ve probably already figured it out, but we’ll formally spell it out here:</p>
<p>How you <em>indent</em> your code determines how it is structured</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">block</span> <span class="n">statement</span><span class="p">:</span>
    <span class="n">some</span> <span class="n">code</span> <span class="n">body</span>
    <span class="n">some</span> <span class="n">more</span> <span class="n">code</span> <span class="n">body</span>
    <span class="n">another</span> <span class="n">block</span> <span class="n">statement</span><span class="p">:</span>
        <span class="n">code</span> <span class="n">body</span> <span class="ow">in</span>
        <span class="n">that</span> <span class="n">block</span>
    <span class="n">end</span> <span class="n">of</span> <span class="s2">&quot;another&quot;</span> <span class="n">block</span> <span class="n">statement</span>
    <span class="n">still</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">first</span> <span class="n">block</span>
<span class="n">outside</span> <span class="n">of</span> <span class="n">the</span> <span class="n">block</span> <span class="n">statement</span>
</pre></div>
<p>The colon that terminates a block statement is also important…</p>
<div class="section" id="one-liners">
<h3>One-liners<a class="headerlink" href="#one-liners" title="Permalink to this headline"></a></h3>
<p>You can put a one-liner after the colon:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [167]: </span><span class="n">x</span> <span class="o">=</span> <span class="mi">12</span>
<span class="gp">In [168]: </span><span class="k">if</span> <span class="n">x</span> <span class="o">&gt;</span> <span class="mi">4</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
<span class="go">12</span>
</pre></div>
<p>But this should only be done if it makes your code <em>more</em> readable. And that is rare.</p>
<p>So you need both the colon and the indentation to start a new a block.  But the end of the indented section is the only indication of the end of the block.</p>
<div class="section" id="spaces-vs-tabs">
<h3>Spaces vs. Tabs<a class="headerlink" href="#spaces-vs-tabs" title="Permalink to this headline"></a></h3>
<p>Whitespace is important in Python.</p>
<p>An indent <em>could</em> be:</p>
<ul class="simple">
<li><p>Any number of spaces</p></li>
<li><p>A tab</p></li>
<li><p>A mix of tabs and spaces:</p></li>
<p>If you want anyone to take you seriously as a Python developer:</p>
<p class="centered">
<strong><strong>Always use four spaces – really!</strong> (<a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a>)</strong></p><div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you <em>do</em> use tabs (and really, don’t do that!) python interprets them as the equivalent of <em>eight</em> spaces.  Text editors can display tabs as any number of spaces, and most modern editors default to four – so this can be <em>very</em> confusing! so again:</p>
<p class="centered">
<strong><strong>Never mix tabs and spaces in Python code</strong></strong></p></div>
<div class="section" id="spaces-elsewhere">
<h3>Spaces Elsewhere<a class="headerlink" href="#spaces-elsewhere" title="Permalink to this headline"></a></h3>
<p>Other than indenting – space doesn’t matter, technically.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="mi">3</span><span class="o">*</span><span class="mi">4</span><span class="o">+</span><span class="mi">12</span><span class="o">/</span><span class="n">func</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">y</span><span class="p">,</span><span class="n">z</span><span class="p">)</span>
<span class="n">x</span> <span class="o">=</span> <span class="mi">3</span><span class="o">*</span><span class="mi">4</span> <span class="o">+</span> <span class="mi">12</span> <span class="o">/</span>   <span class="n">func</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span>   <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">)</span>
</pre></div>
<p>These will give the exact same results.</p>
<p>But you should strive for proper style. Isn’t this easier to read?</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span> <span class="o">*</span> <span class="mi">4</span><span class="p">)</span> <span class="o">+</span> <span class="p">(</span><span class="mi">12</span> <span class="o">/</span> <span class="n">func</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">))</span>
</pre></div>
<p class="centered">
<strong><strong>Read</strong> <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a> <strong>and install a linter in your editor.</strong></strong></p></div>
<div class="section" id="modules-and-packages">
<h2>Modules and Packages<a class="headerlink" href="#modules-and-packages" title="Permalink to this headline"></a></h2>
<p>Python is all about <em>namespaces</em> – the “dots”</p>
<p><code class="docutils literal notranslate"><span class="pre">name.another_name</span></code></p>
<p>The “dot” indicates that you are looking for a name in the <em>namespace</em> of the given object. It could be:</p>
<ul class="simple">
<li><p>A name in a module</p></li>
<li><p>A module in a package</p></li>
<li><p>An attribute of an object</p></li>
<li><p>A method of an object</p></li>
<p>The only way to know is to know what type of object the name refers to.  But in all cases, it is looking up a name in the namespace of the object.</p>
<p>So what <em>are</em> all these different types of namespaces?</p>
<div class="section" id="modules">
<h3>Modules<a class="headerlink" href="#modules" title="Permalink to this headline"></a></h3>
<p>A module is simply a namespace. But a module more or less maps to a file with python code in it.</p>
<p>It might be a single file, or it could be a collection of files that define a shared API.</p>
<p>But in the common and simplest case, a single file is a single module.</p>
<p>So you can think of the files you write that end in <code class="docutils literal notranslate"><span class="pre">.py</span></code> as modules.</p>
<p>When a module is imported, the code in that file is run, and any names defined in that file are now available in the module namespace.</p>
<p>For a really simple example, if you have the following in the <code class="docutils literal notranslate"><span class="pre">trivial.py</span></code> file:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">1</span>
<span class="linenos">2</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">2</span>
<span class="linenos">3</span>
<span class="linenos">4</span> <span class="k">def</span> <span class="nf">do_nothing</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span>
<span class="linenos">5</span>     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;do_nothing was called with:&quot;</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">)</span>
<span class="linenos">6</span>
<span class="linenos">7</span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;at the end of the trivial module&quot;</span><span class="p">)</span>
</pre></div>
<p>What do you think happens when you import that module? What will get printed?</p>
<p>What names will be defined in that module?</p>
<p>How would you access those names?</p>
<p>Before running this code, think about it a bit. Recall what happens when you import a module:</p>
<ul class="simple">
<li><p>The code is run in the module, top to bottom.</p></li>
<li><p>The names defined in the module (its global namespace) are made available in the modules namespace.</p></li>
<p>So: Lines 1-2 assign two names, <code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code>. lines 4-5 define a function, named <code class="docutils literal notranslate"><span class="pre">do_nothing</span></code>. Line 7 prints something.</p>
<p>So: when run, there are three names defined, and one print function run.</p>
<p>Now try it:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">trivial</span>
<span class="go">at the end of the trivial module</span>
</pre></div>
<p>yes, we got that print function run.</p>
<p>Let’s see if the names are there:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">trivial</span><span class="o">.</span><span class="n">x</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">trivial</span><span class="o">.</span><span class="n">y</span>
<span class="go">2</span>
</pre></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">trivial</span><span class="o">.</span><span class="n">do_nothing</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="go">do_nothing was called with: 3 4 5</span>
</pre></div>
<p>yes, there are, in the <code class="docutils literal notranslate"><span class="pre">trivial</span></code> namespace.</p>
<div class="section" id="packages">
<h3>Packages<a class="headerlink" href="#packages" title="Permalink to this headline"></a></h3>
<p>A package is a module with other modules in it.</p>
<p>On a filesystem, this is represented as a directory that contains one or more <code class="docutils literal notranslate"><span class="pre">.py</span></code> files, one of which <strong>must</strong> be called <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>. The <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file can be empty (and often is) – but it must be there.</p>
<p>When there is a package available, you can import only the package, or any of the modules inside it. When a package is imported, the code in the <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file is run, and any names defined in that file are available in the <em>package namespace</em>.</p>
<p>Here we define about the simplest package possible:</p>
<p>Create a directory (folder) for your package:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mkdir my_package
</pre></div>
<p>Save a file in that package, called <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>, and put this in it:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">name1</span> <span class="o">=</span> <span class="s2">&quot;Fred&quot;</span>
<span class="n">name2</span> <span class="o">=</span> <span class="s2">&quot;Bob&quot;</span>
</pre></div>
<p>Save another file in your my_package dir called <code class="docutils literal notranslate"><span class="pre">a_module.py</span></code>, and put this in it:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">name3</span> <span class="o">=</span> <span class="s2">&quot;Mary&quot;</span>
<span class="n">name4</span> <span class="o">=</span> <span class="s2">&quot;Jane&quot;</span>
<span class="k">def</span> <span class="nf">a_function</span><span class="p">():</span>
    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;a_function has been called&quot;</span><span class="p">)</span>
</pre></div>
<p>You now have about the simplest package you can have. Make sure your current working dir is the dir that <code class="docutils literal notranslate"><span class="pre">my_package</span></code> is in, and start python or iPython. Then try this code:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [1]: </span><span class="kn">import</span> <span class="nn">my_package</span>
<span class="gp">In [2]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">name1</span>
<span class="gh">Out[2]: </span><span class="go">&#39;Fred&#39;</span>
<span class="gp">In [3]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">name2</span>
<span class="gh">Out[3]: </span><span class="go">&#39;Bob&#39;</span>
</pre></div>
<p>The names you’ve defined are available in the package namespace.</p>
<p>What about the module?</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [4]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">a_module</span>
<span class="gt">---------------------------------------------------------------------------</span>
<span class="ne">AttributeError</span><span class="g g-Whitespace">                            </span>Traceback (most recent call last)
<span class="nn">&lt;ipython-input-4-8b9269cdf0e5&gt;</span> in <span class="ni">&lt;module&gt;</span><span class="nt">()</span>
<span class="ne">----&gt; </span><span class="mi">1</span> <span class="n">my_package</span><span class="o">.</span><span class="n">a_module</span>
<span class="ne">AttributeError</span>: module &#39;my_package&#39; has no attribute &#39;a_module&#39;
</pre></div>
<p>the <code class="docutils literal notranslate"><span class="pre">a_module</span></code> name does not exist. It must be imported explicitly:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [1]: </span><span class="kn">import</span> <span class="nn">my_package.a_module</span>
</pre></div>
<p>Now the names defined in the <code class="docutils literal notranslate"><span class="pre">a_module.py</span></code> file are all there:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [2]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">a_module</span><span class="o">.</span><span class="n">name3</span>
<span class="gh">Out[2]: </span><span class="go">&#39;Mary&#39;</span>
<span class="gp">In [3]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">a_module</span><span class="o">.</span><span class="n">name4</span>
<span class="gh">Out[3]: </span><span class="go">&#39;Jane&#39;</span>
<span class="gp">In [4]: </span><span class="n">my_package</span><span class="o">.</span><span class="n">a_module</span><span class="o">.</span><span class="n">a_function</span><span class="p">()</span>
<span class="go">a_function has been called</span>
</pre></div>
<p>Note that you can also put a package inside a package. So you can create arbitrarily deeply nested hierarchy of packages. This can be helpful for a large, complex collection of related code, such as an entire Web Framework. But from the <em>Zen of Python</em>:</p>
<blockquote>
<div><p>“Flat is better than nested.”</p>
</div></blockquote>
<p>So don’t overdo it – only go as deep as you really need to to keep your code organized.</p>
<div class="section" id="importing-modules">
<h3>Importing modules<a class="headerlink" href="#importing-modules" title="Permalink to this headline"></a></h3>
<p>You have probably imported a module or two already:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">import</span> <span class="nn">math</span>
</pre></div>
<p>But there a handful of ways to import modules and packages.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">modulename</span>
</pre></div>
<p>Is the simplest way: this adds the name of the module to the global namespace, and lets you access the names defined in that module:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">modulename</span><span class="o">.</span><span class="n">a_name_in_the_module</span>
</pre></div>
<p>If you want only a few names in a module, and don’t want to type the module name each time, you can import only the names you want:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">modulename</span> <span class="kn">import</span> <span class="n">this</span><span class="p">,</span> <span class="n">that</span>
</pre></div>
<p>This brings only the names specified (<code class="docutils literal notranslate"><span class="pre">this</span></code>, <code class="docutils literal notranslate"><span class="pre">that</span></code>) into the global namespace. All the code in the module is run, but the module’s name is not available. But the explicitly imported names are directly available.</p>
<p>Sometimes you want the entire module, but maybe not want to type its entire name eadh time you use. So you can rename a module when you import it. (you may also want to do this if a module has the same name as a variable you want to use…)</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">modulename</span> <span class="k">as</span> <span class="nn">a_new_name</span>
</pre></div>
<p>This imports the module, and gives it a new name in the global namespace. For example, the numpy package is usually imported as:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
</pre></div>
<p>Because numpy has a LOT of names, some of which may conflict with builtins or other modules, and users want to be able to reference them without too much typing.</p>
<p>You can also import a name within a module and rename it at the same time:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">modulename</span> <span class="kn">import</span> <span class="n">this</span> <span class="k">as</span> <span class="n">that</span>
</pre></div>
<p>This imports only one name from a module, while also giving it a new name in the global namespace.</p>
<div class="section" id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h3>
<p>You can play with some of this with the standard library:</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="gp">In [1]: </span><span class="kn">import</span> <span class="nn">math</span>
<span class="gp">In [2]: </span><span class="n">math</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="mf">1.2</span><span class="p">)</span>
<span class="gh">Out[2]: </span><span class="go">0.9320390859672263</span>
<span class="gp">In [3]: </span><span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">cos</span>
<span class="gp">In [4]: </span><span class="n">cos</span><span class="p">(</span><span class="mf">1.2</span><span class="p">)</span>
<span class="gh">Out[4]: </span><span class="go">0.3623577544766736</span>
<span class="gp">In [5]: </span><span class="kn">import</span> <span class="nn">math</span> <span class="k">as</span> <span class="nn">m</span>
<span class="gp">In [6]: </span><span class="n">m</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gh">Out[6]: </span><span class="go">0.8414709848078965</span>
<span class="gp">In [7]: </span><span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">cos</span> <span class="k">as</span> <span class="n">cosine</span>
<span class="gp">In [8]: </span><span class="n">cosine</span><span class="p">(</span><span class="mf">1.2</span><span class="p">)</span>
<span class="gh">Out[8]: </span><span class="go">0.3623577544766736</span>
</pre></div>
<div class="section" id="my-rules-of-thumb">
<h3>My rules of thumb<a class="headerlink" href="#my-rules-of-thumb" title="Permalink to this headline"></a></h3>
<p>If you only need a few names from a module, import only those:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">sin</span><span class="p">,</span> <span class="n">cos</span><span class="p">,</span> <span class="n">tan</span>
</pre></div>
<p>If you need a lot of names from that module, just import the module:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">math</span>
<span class="n">math</span><span class="o">.</span><span class="n">cos</span><span class="p">(</span><span class="mi">2</span> <span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
</pre></div>
<p>Or import it with a nice short name:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">math</span> <span class="k">as</span> <span class="nn">m</span>
<span class="n">m</span><span class="o">.</span><span class="n">cos</span><span class="p">(</span><span class="mi">2</span> <span class="o">*</span> <span class="n">m</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
</pre></div>
<div class="section" id="import">
<h3>import * ?<a class="headerlink" href="#import" title="Permalink to this headline"></a></h3>
<p class="centered">
<strong><strong>Warning:</strong></strong></p><p>You can also import all the names in a module with:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">modulename</span> <span class="kn">import</span> <span class="o">*</span>
</pre></div>
<p>But this leads to name conflicts, and a cluttered namespace. It is NOT recommended practice anymore.</p>
<div class="section" id="importing-from-packages">
<h3>Importing from packages<a class="headerlink" href="#importing-from-packages" title="Permalink to this headline"></a></h3>
<p>Packages can contain modules, which can be nested – ideally not very deeply.</p>
<p>In that case, you can simply add more “dots” and follow the same rules as above.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">packagename</span> <span class="kn">import</span> <span class="n">my_funcs</span><span class="o">.</span><span class="n">this_func</span>
</pre></div>
<p><a class="reference internal" href="Packaging.html#packaging"><span class="std std-ref">Packages and Packaging</span></a> goes into more detail about creating (and distributing!) your own package.</p>
<div class="section" id="what-does-import-actually-do">
<h3>What does <code class="docutils literal notranslate"><span class="pre">import</span></code> actually do?<a class="headerlink" href="#what-does-import-actually-do" title="Permalink to this headline"></a></h3>
<p>When you import a module, or a symbol from a module, the Python code is <em>compiled</em> to <em>bytecode</em>.</p>
<p>The result is a <code class="docutils literal notranslate"><span class="pre">module.pyc</span></code> file.</p>
<p>Then after compiling, all the code in the module is run <strong>at the module scope</strong> – that is, in the namespace of the module.</p>
<p>For this reason, it is good to avoid module-scope statements that have global side-effects. This includes things as simple as a <code class="docutils literal notranslate"><span class="pre">print()</span></code> – it will only print the first time the module is imported.</p>
<div class="section" id="re-import">
<h3>Re-import<a class="headerlink" href="#re-import" title="Permalink to this headline"></a></h3>
<p>The code in a module is <em>not</em> re-run when imported again. This makes it efficient to import the same module multiple places in a program. But it means that if you change the code in a module after importing it, that change will not be reflected when it is imported again.</p>
<p>If you DO want a change to be reflected, you can explicitly reload a module:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">importlib</span>
<span class="n">importlib</span><span class="o">.</span><span class="n">reload</span><span class="p">(</span><span class="n">modulename</span><span class="p">)</span>
</pre></div>
<p>This is rarely needed (which is why it’s a bit buried in the <code class="docutils literal notranslate"><span class="pre">importlib</span></code> module), but is good to keep in mind when you are interactively working on code under development.</p>
<div class="section" id="import-interactions">
<h3>Import Interactions<a class="headerlink" href="#import-interactions" title="Permalink to this headline"></a></h3>
<p>Another key point to keep in mind is that all code files in a given python program are sharing the same modules. So if you change a value in a module, that value’s change will be reflected in other parts of the code that have imported that same module.</p>
<p>This can create dangerous side effects and hard to find bugs if you change anything in an imported module, but it can also be used as a handy way to store truly global state, like application preferences, for instance.</p>
<p>A rule of thumb for managing global state is to have only <em>one</em> part of your code change the values, and everywhere else considers them read-only. You can’t enforce this, but you can structure you own code that way.</p>
<p>Let’s take a look at an example of this.</p>
<p>Create three modules (python files):</p>
<p><code class="docutils literal notranslate"><span class="pre">mod1.py</span></code>, <code class="docutils literal notranslate"><span class="pre">mod2.py</span></code>, <code class="docutils literal notranslate"><span class="pre">mod3.py</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">mod1.py</span></code> is very simple – one name declared:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="mi">5</span>
</pre></div>
<p><code class="docutils literal notranslate"><span class="pre">mod2.py</span></code> is where a bit actually goes on:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python3</span>
<span class="kn">import</span> <span class="nn">mod1</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;In mod2: mod1.x = </span><span class="si">{</span><span class="n">mod1</span><span class="o">.</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="nb">input</span><span class="p">(</span><span class="s2">&quot;pausing (hit enter to continue &gt;&quot;</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;importing mod3&quot;</span><span class="p">)</span>
<span class="kn">import</span> <span class="nn">mod3</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Still in mod2: mod1.x = </span><span class="si">{</span><span class="n">mod1</span><span class="o">.</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;mod3 changed the value in mod1, and that change shows up in mod2&quot;</span><span class="p">)</span>
</pre></div>
<p>Here, we import <code class="docutils literal notranslate"><span class="pre">mod1</span></code>, and we can now see the names defined in it, and print the value of <code class="docutils literal notranslate"><span class="pre">x</span></code>. Then it pauses, waiting for input. After the user hits the &lt;enter&gt; key, it then imports <code class="docutils literal notranslate"><span class="pre">mod3</span></code>, and again prints the value of <code class="docutils literal notranslate"><span class="pre">x</span></code> that is in <code class="docutils literal notranslate"><span class="pre">mod1</span></code>. Let’s now look at <code class="docutils literal notranslate"><span class="pre">mod3.py</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">mod1</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;In mod3 -- changing the value of mod1.x&quot;</span><span class="p">)</span>
<span class="n">mod1</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="mi">555</span>
</pre></div>
<p>Other than the print – all <code class="docutils literal notranslate"><span class="pre">mod3</span></code> does is re-set the value of <code class="docutils literal notranslate"><span class="pre">x</span></code> that is on <code class="docutils literal notranslate"><span class="pre">mod1</span></code>.
Running <code class="docutils literal notranslate"><span class="pre">mod2.py</span></code> results in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python mod2.py
In mod2: mod1.x = 5
pausing (hit enter to continue &gt;
importing mod3
In mod3 -- changing the value of mod1.x
Still in mod2: mod1.x = 555
mod3 changed the value in mod1, and that change shows up in mod2
</pre></div>
<p>You can see that when <code class="docutils literal notranslate"><span class="pre">mod2</span></code> changed the value of <code class="docutils literal notranslate"><span class="pre">mod1.x</span></code>, that changed the value everywhere that <code class="docutils literal notranslate"><span class="pre">mod1</span></code> is imported. You want to be very careful about this.</p>
<p>If you are writing <code class="docutils literal notranslate"><span class="pre">mod2.py</span></code>, and did not write <code class="docutils literal notranslate"><span class="pre">mod3</span></code> (or wrote it long enough ago that you don’t remember its details), you might be very surprised that a value in <code class="docutils literal notranslate"><span class="pre">mod1</span></code> changes simply because you imported <code class="docutils literal notranslate"><span class="pre">mod3</span></code>.  This is known as a “side effect”, and you generally want to avoid them!</p>
           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="NamingThings.html" class="btn btn-neutral float-left" title="Style and Naming" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="Documentation.html" class="btn btn-neutral float-right" title="Documentation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
  <div role="contentinfo">
    <p>&#169; Copyright 2020, University of Washington, Natasha Aleksandrova, Christopher Barker, Brian Dorsey, Cris Ewing, Christy Heaton, Jon Jacky, Maria McKinley, Andy Miles, Rick Riehle, Joseph Schilz, Joseph Sheedy, Hosung Song. Creative Commons Attribution-ShareAlike 4.0 license.</p>
  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
        </div>
      </div>
    </section>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
  </script> 
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

Modules.html

Latest commit

History

Modules.html

File metadata and controls
