Project Structure

Why a src directory?

Some good blogs that explain this:

• https://blog.ionelmc.ro/2014/05/25/python-packaging/
• https://hynek.me/articles/testing-packaging/
• http://andrewsforge.com/article/python-new-package-landscape/
• https://docs.pytest.org/en/latest/goodpractices.html#choosing-a-test-layout-import-rules

The setuptools documentation itself has some info:

• https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html#using-a-src-layout

Packaging

Use a pyproject.toml?

Yes! At least eventually; it's just a question of when (now?).

PEP517 A build-system independent format for source trees should eventually let us get rid of all the pip install -U pip setuptools stuff in the GitHub Actions workflows (not to mention local development).

As of python 3.9, the official documentation still recommends using setuptools, wheel, and twine:

The currently recommended build and distribution tools can be installed by invoking the pip module at the command line:

python -m pip install setuptools wheel twine

The python packaging landscape is pretty full with tools trying to be compatible with the pyproject.toml.

• build

  Adopted into PyPA. This tool is currently recommended on the setuptools site.

  To build the package, use PyPA build

• pep517

  This project used to be a CLI program but is currently reposition itself as only a library. For folks who want a CLI, it is currently (April 2021) pointing people to build. See: https://github.com/pypa/pep517/issues/91

• poetry

• pipenv

  Recommended by PyPA. Uses a (non-standard) Pipfile and Pipfile.lock. Pipenv poineered some great ideas in the Python ecosystem. A lot of people love Pipenv because it forces everyone into roughly the same workflow.

  Opinion: Personally I avoid pipenv because, I think, it tries to do too much, and ends up creating as many problems for me as it solves. I think the folks over at PyPA have done a disservice by recommending pipenv in their Tool Recommendations and their guide on Managing Application Dependencies. It's telling that they do not use pipenv in their guide on Packaging and distributing projects, nor in their sample project.

  Mostly, pipenv clashes the ethos of programming that I try to follow, which is one of Programming with Hand Tools. Pipenv is not a simple, composable tool; you either go all-in (and force everyone else you work with to do so as well), or you don't use it at all. Pipenv might be a great choice for you; I just don't think it's difinitively "the winner", and it should not be publicized as such by PyPA.