How to properly import sub-modules in a Python package?
<p>I am a bit lost about how I should import and organise my sub-modules and I need some literature and some conventions.</p>

<h2>The problem</h2>

<p>We want to write a new package written in Python that is composed of several components: </p>

<ul>
<li>Classes and functions useful for the end user</li>
<li>Classes and functions rarely used </li>
<li>Utilities classes and functions only needed by the package itself</li>
<li>External modules</li>
</ul>

<p>We consider this architecture:</p>

<pre><code>pizzafactory
âââ __init__.py
âââ salt.py 
âââ water.py 
âââ vegetables
âÂ Â  âââ __init__.py 
â   âââ tomatoes.py 
âââ dough
 Â Â  âââ __init__.py 
    âââ flour.py 
</code></pre>

<h2>Some considerations</h2>

<ul>
<li>The end user don't need to use raw ingredients such as dough or water</li>
<li>The customer only need pizzas described in <code>pizzafactory/__init__.py</code></li>
<li>The dough factory requires salt and water</li>
<li>The customer may want to add some tomatoes on its pizza. </li>
</ul>

<p>The file <code>pizzafactory/__init__.py</code> needs almost all the modules, but because we don't want to pollute the end user namespace with useless things. I would propose to import the ingredients quietly except for those that may be used by the customer:</p>

<pre><code># pizzafactory/__init__.py
import salt as _salt
import dough as _dough
import vegetables.tomatoes

import oven as _oven # External package
</code></pre>

<p>The dough factory will require some water, but the user who need to use that sub-module (to make bread), may don't want to see the <code>water</code>. </p>

<pre><code># pizzafactory/dough/__init__.py
import pizzafactory.water as _water
</code></pre>

<h2>Discussion</h2>

<p>First, I feel it's always easier to directly import everything either the full package:</p>

<pre><code>import pizzafactory

def grab_tomato():
    return pizzafactory.vegetables.tomatoes.BeefsteakTomato()
</code></pre>

<p>or only the required elements:</p>

<pre><code>from pizzafactory.vegetables.tomatoes import BeefsteakTomato

def grab_tomato():
    return BeefsteakTomato()
</code></pre>

<p>Both of these methods are common, but it may pollute the <code>pizzafactory</code> namespace, so it may be preferable to mangle the import names. I relalized that nobody does that and I don't know why. </p>

<h2>Question</h2>

<p>In this generic example, I would like to know how to properly import modules,  sub-modules and external packages in order to: </p>

<ul>
<li>Minimize the namespace footprint</li>
<li>Help the end user to clearly see only what he is intended to used</li>
</ul>

<blockquote>
  <p>Both of these methods are common, but it may pollute the pizzafactory namespace, so it may be preferable to mangle the import names. I relalized that nobody does that and I don't know why.</p>
</blockquote>

<p>Python is a consenting adult language, we leave the doors unlocked and everything out in the open, for the most part. </p>

<p>If you're concern is just crowding the namespaces, you should define <code>__all__</code> as well as use single-leading underscores. -- PEP8 suggests that name mangling should only be used to avoid naming clashes, so that's probably why nobody does that. </p>

<p>See the <a href="https://www.python.org/dev/peps/pep-0008/#public-and-internal-interfaces" rel="nofollow">Public and internal interfaces</a> section of PEP8 as well as <a href="https://www.python.org/dev/peps/pep-0008/#naming-conventions" rel="nofollow">Naming Convensions.</a> </p>

<p>PEP8 is the guide for the "proper" way to do these kinds of things. Though, it is a <em>guide</em> not necessarily <em>law</em>. You have the flexibility to do what you feel is appropriate for your package, which leads to my favorite section of PEP8 - <a href="https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds" rel="nofollow">A Foolish Consistency is the Hobgoblin of Little Minds</a></p>

<p>Without being sufficiently intimate with the code in a package, one probably could not offer much advice beyond PEP8 on how it <em>should</em> be done. If you have the time, Raymond Hettinger's talk <a href="https://www.youtube.com/watch?v=wf-BqAjZb8M" rel="nofollow">Beyond PEP 8</a> is a worthwhile watch.</p>

python module package packages python-import