Packaging guide

First things first, you need to properly structure your project. A quick guide on how to structure a python library can be found at the following links: in french and in english.

We will take one example: the sample python package…which only purpose is to explain how to properly structure and distribute a project. The sources can be found on GitHub.

Here is how the library is structured:

qdouasbin@jolly:~/Desktop/sampleproject>find . | sed -e "s/[^-][^\/]*\//  |/g" -e "s/|\([^ ]\)/|-\1/"
.
  |-tests
  |  |-test_simple.py
  |  |-__init__.py
  |-MANIFEST.in
  |-README.md
  |-setup.py
  |-tox.ini
  |-sample
  |  |-__init__.py
  |  |-package_data.dat
  |-setup.cfg
  |-LICENSE.txt
  |-data
  |  |-data_file

In short:

• the repository must contain a setup.py file to easily install your library using the nice and simple install mechanisms described above. You can also specify your configuration in the setup.cfg but the setup.py still need to be present. More info here
• your sources must be contained in a folder named as the library name (here the sample directory) you want to create,
• you should have a LICENSE.txt or LICENSE.md explicitly explaining under which software license your packages falls into,
• the README.md (or README.rst) should explain what your library does and how you install it. (The MANIFEST.in is
• you should have a tests folder containing unit tests,
• the documentation related to you project should be contained in the docs folder
• a requirement.txt file containing all the dependencies (i.e. the python packages needed by your library)

To create a pip-installable package you need to create a setup.py. To test that your setup.py works you need to run the pip install . in the folder containing the setup.py. If it doesn’t work you need to:

1. pip uninstall my_project
2. modify the setup.py
3. re-run the pip install . command

There are a lot of ways to populate a setup.py file as there are many options. The best option here is to start from an existing one and modify it to your needs. You can take the one of the sample project for example or the template_module example if you have access to Nitrox (you might need to ask the rights to access this repository to Corentin Lapeyre).

More on this topic can be found in the setuptools’ documentation setuptools’ documentation.

Like this post? Share on: Twitter ❄ Facebook ❄ Email