README.md

Awesome Python Packaging

Python packaging recently got awesome!

pyproject.toml is the standard place to configure everything, defined in PEP 518. Because lack of pyproject.toml support in some tools is the only part about Python packaging that isn’t awesome already, each tool has a little ✅ or ❌ to indicate support.

Testing / Checking

Make sure your program behaves as you intended in different environments. Apart from locally running these, you also want to set up Continuous Integration (CI) like GitHub Actions or AppVeyor.

• pre-commit ❌ (.pre-commit-config.yaml)

  Automatically run checks (as e.g. the ones below) and formatters when committing changes. You probably want to configure this to run all checks except for slow ones like unit tests. Has its own CI provider that runs very quickly.

• tox ✅ (pyproject.toml, setup.cfg, tox.ini)

  Use this to define environments in which to test your package. Like continuous integration on your local machine. Can be integrated into CI.

• pytest ✅ (pyproject.toml, setup.cfg, tox.ini, pytest.ini)

  Unofficial standard for Python testing. Many Plugins, user-friendly error reporting using just assert. Good defaults make lack of pyproject.toml support painless.

• mypy ✅ (pyproject.toml, setup.cfg, mypy.ini) – since version 0.900

  Static type checking. It tests if the values you pass to and return from functions match the type annotations.

• Coverage.py ✅ (pyproject.toml, .coveragerc)

  Code coverage measurement for Python.

Code Style

Make sure feedback in PRs isn’t mostly about code style, but about actual content.

• pylint ✅ (pyproject.toml, setup.cfg, pylintrc, .pylintrc) – since version 2.5,
  flake8 ❌ (setup.cfg, tox.ini, .flake8)

  Generic style checkers for many possible code smells.

• pycodestyle ❌ (setup.cfg, tox.ini)

  A style checker focused on PEP 8 compliance. Is included in flake8.

• black ✅ (pyproject.toml)

  A optionless code formatter that frees your mind from having to think about style.

• isort ✅ (pyproject.toml, setup.cfg, tox.ini, .isort.cfg)

  A formatter for reordering imports. Many options!

Package Creation Tools

Manage your package’s dependencies, and publish it to the PyPI. All of the below tools come with a Command Line Interface (CLI) and a build backend. Except for flit, all of the CLIs allow you to manage package environments for your package’s dependencies.

• flit ✅ (pyproject.toml, flit.ini)

  A tool for simple packages without compilation step. Does not manage package environments, which makes it very obvious and unsurprising.

• PDM ✅ (pyproject.toml)

  Has advanced features entirely based on standards. if you e.g. want to use its environment management with hatch’s build plugins, do it. The only not yet standardized function: Allows to synchronize your package dependencies using a lockfile.

• poetry ✅ (pyproject.toml)

  Also has lockfile support, but does more things not following standards. As a result, it contributes/uses the ecosystem less, is less interoperable, but well-tread paths work very well.

• hatch ✅ (pyproject.toml, hatch.toml)

  (Optionally) allows a more fine grained and manual environment management than the above, similarly to tox. Has plugins, e.g. hatch-vcs which derives your package version from Git tags.

Tools you can rely on that are not project managers / build backends:

• build

  Allows you to call into any of the build backends above and use it to build a wheel file for your package. It has no configuration.

• twine

  Allows you to upload a built wheel to PyPI with little hassle. It has no configuration.

• setuptools_scm ✅ (pyproject.toml, setup.cfg)

  A package that allows you to have one true source of versions: Your SCM metadata (e.g. git tag). Installing a “dirty” untagged version will automatically give you a version string that comparse as newer than the last clean one. It can work at build time as a command line tool/Python API or as a runtime library. hatch-vcs wraps its functionality.

Package managers

These don’t need to be configured per project with pyproject.toml, but need to read its [build-system] section to install the project!

• pip ✅ (pyproject.toml, setup.py)

  Python’s classic package manager. Widespread like no other and therefore very robust. Except for actually resolving dependencies, which it does rather duct-tape-and-hope like.

• The Package Creation Tools above can be used as package managers.

• pipenv ❌ (Pipfile)

  pipenv is not a package creation tool, it’s an application creation tool. If you want to build a library, choose one of the package creation tools above.

Others

• dephell ✅ (pyproject.toml)

  A dependency management tool that converts between and allows reasoning about all above.