General packaging

A common question facing developers is “How much code should go into a package?”. Where code to solve a research problem might be large and perform several tasks at once typically one should try to stick to a mantra of doing one thing well. The following questions can be helpful when trying to abide by this mantra:

  • What do I want my package to provide?
  • How will users interact with or use the code in my package?
  • Is everything I’m including in the package relevant or useful in supporting it’s main purpose?

In Python, a package is a collection of one or more modules to perform software tasks. Typically there is a separate git repository per package, and we recommend you stick to this. You can always add the packages as dependencies to a higher-level package which is effectively the same, but much easier to reuse.

Packaging tools

Name Short description 🚦
setuptools A widely used build backend, used to configure a Python package. Best
setuptools-scm Provides automatic versioning Python packages. Also automatically adds all files under source control to the sdist / wheel. Best
poetry A tool that lets you build and package your project as well as managing dependencies Good
twine Tool for publishing Python packages on PyPI. Good
bump2version Tool for version-bumping your software. No longer maintained Avoid
bump-my-version Tool for version-bumping your software. Superseded by setuptools_scm Avoid

Building

Name Short description 🚦
build Straightforward tool to build a Python package. Best
cibuildwheel Builds python wheels for the main operating systems on continuous integration runs (e.g. GitHub actions). Good

Package configuration file

Name Short description 🚦
pyproject.toml Contains build system requirements and information, which are used by pip to build the package. It is becoming the accepted standard and we strongly recommend it. Best
setup.py Strongly coupled with setuptools and therefore not recommended. Good
setup.cfg An ini file that contains defaults for setup.py commands. Good

Conda

These tools are helpful if you’re looking to publish your package on conda-forge, so users can install it through the Conda package manager.

Name Short description 🚦
GraySkull A tool for automatic Conda recipe generation (aimed at conda-forge, above). Best