Editing Python Packaging (section)

== Configuration ==

=== Setup.py ===

A setup config file, `setup.py`, in the repo root directory should contain a single call to `setuptools.setup()`, like so: <ref>[https://python-packaging.readthedocs.io/en/latest/minimal.html How To Package Your Python Code] - Python Packaging Tutorial</ref>

<syntaxhighlight lang="python">
from setuptools import setup

setup(name='namespace-my-package',
      version='0.1',
      description='My package description',
      url='http://github.com/dbarchowsky/namespace-my-package',
      author='Damien Barchowsky',
      author_email='dbarchowsky@gmail.com',
      license='MIT',
      packages=['namespace.my_package'],
      install_requires=['list', 
            'of', 
            'dependencies',
            ],    
      zip_safe=False)
</syntaxhighlight>

After which the package can be installed locally with

<syntaxhighlight lang="bash">
$ pip install .
</syntaxhighlight>

And once installed the package can be used like this:

<syntaxhighlight lang="python">
>>> from namespace.my_package import my_module
>>> my_module.some_routine()
</syntaxhighlight>

=== Namespaces ===

It's recommended to use namespaces when creating packages. <ref>[https://packaging.python.org/guides/packaging-namespace-packages/ Packaging Namespace Packages] - PyPA Packaging Guide</ref> Even if the package is not being publicly distributed, the names of dependencies from other packages can clash.

The recommended file structure is this:

<pre>
mynamespace-subpackage-a/
    setup.py
    mynamespace/
        subpackage_a/
            __init__.py
            module_aa.py
</pre>

Note that there is no `__init__.py` in the `mynamespace` directory. Only packages should have `__init__.py` files.

=== Including sub-packages in distribution ===

Each module in the package must be explicitly added to the distribution under the `packages` setting in `setup.py`.

For a project with packages under the top-level package, e.g.:

<pre>
mynamespace-subpackage-a/
    setup.py
    mynamespace/
        my_package/
            __init__.py
            subpackage_a/
                __init__.py
            subpackage_b/
                __init__.py
            module_aa.py
</pre>

To include the non-top-level packages, add them to `packages` in `setup.py`:

<syntaxhighlight lang="python">
from setuptools import setup

setup(name='mynamespace-my-package',
    ''' [...] '''
    packages=['mynamespace.my_package',
              'mynamespace.my_package.subpackage_a',
              'mynamespace.my_package.subpackage_b',
    ],
    ''' [...] '''

</syntaxhighlight>