Python Library Packaging

SOURCE: https://python-packaging.readthedocs.io/en/latest/minimal.html

This is a simple python packaging example

Project Structure

py-lib
    py-lib/
        __init__py
    docs/                    <-- optional
    README.md
    requirements.txt
    setup.py
    tests/                   <-- optional

tests are something you should do, but are NOT a must to publish

Now we can install the package locally (for use on our system), with:

$ pip install .

We can also install the package with a symlink, so that changes to the source files will be immediately available to other users of the package on our system:

$ pip install -e .

Anywhere else in our system using the same Python, we can do this now:

>>> import funniest
>>> print funniest.joke()

Publishing On PyPI

The setup.py script is also our main entrypoint to register the package name on PyPI and upload source distributions.

To “register” the package (this will reserve the name, upload package metadata, and create the pypi.python.org webpage):

$ python setup.py register

If you haven’t published things on PyPI before, you’ll need to create an account by following the steps provided at this point.

At this point you can view the (very minimal) page on PyPI describing funniest:

http://pypi.python.org/pypi/funniest/0.1

Although users can follow the URL link to find our git repository, we’ll probably want to upload a source distribution so that the package can be installed without cloning the repository. This will also enable automated installation and dependency resolution tools to install our package.

First create a source distribution with:

$ python setup.py sdist

This will create dist/funniest-0.1.tar.gz inside our top-level directory. If you like, copy that file to another host and try unpacking it and install it, just to verify that it works for you.

That file can then be uploaded to PyPI with:

$ python setup.py sdist upload

You can combine all of these steps, to update metadata and publish a new build in a single step:

$ python setup.py register sdist upload

For a detailed list of all available setup.py commands, do:

$ python setup.py --help-commands

Installing the Package

At this point, other consumers of this package can install the package with pip:

$ pip install funniest

They can specify it as a dependency for another package, and it will be automatically installed when that package is installed (we’ll get to how to do that later). Adding Additional Files

Most of the time we’ll want more than one file containing code inside of our module. Additional files should always be added inside the inner funniest directory.

For example, let’s move our one function to a new text submodule, so our directory hierarchy looks like this:

funniest/
    funniest/
        __init__.py
        text.py
    setup.py

In __init__.py:

from .text import joke

In text.py:

def joke():
    return (u'Wenn ist das Nunst\u00fcck git und Slotermeyer? Ja! ... '
            u'Beiherhund das Oder die Flipperwaldt gersput.')

All additional Python code belongs in the funniest/funniest/ directory. Ignoring Files (.gitignore, etc)

There’s one more thing we’ll probably want in a ‘bare bones’ package: a .gitignore file, or the equivalent for other SCMs. The Python build system creates a number of intermediary files we’ll want to be careful to not commit to source control. Here’s an example of what .gitignore should look like for funniest:

Compiled python modules. *.pyc

Setuptools distribution folder. /dist/

Python egg metadata, regenerated from source files by setuptools. /*.egg-info

That’s All You Need

The structure described so far is all that’s necessary to create reusable simple packages with no ‘packaging bugs’. If every published Python tool or library used followed these rules, the world would be a better place.