project_template

Build status: Linux and OSX Build status: Windows Documentation status Latest PyPI version Python versions supported

This is a sample project generated by generator-python for Yeoman. [1] It has a number of features, each with its own chapter in the documentation:

  • ISC license (a shorter MIT license)
  • All package metadata in pyproject.toml (reaching standardization in PEP 518)
  • Cross-platform scripts for common development tasks (linting, testing, building documentation)
  • Testing with pytest, doctests, and coverage
  • Continuous integration on Linux and OSX with Travis CI and Windows with AppVeyor
  • Documentation with Sphinx and Read the Docs

Why?

Imagine you’re working on a Python project, and you take a detour to write a subpackage or submodule with some useful functions or a clever abstraction. This package depends on nothing else in your project; it can actually be a dependency of your project. It might be useful in some of your other projects, or it might be useful to other people in their projects. You would like to extract that package into its own project (while following best practices for directory structure, code style, tests, documentation, and continuous integration) that you can quickly and easily package and share through the Python Package Index (PyPI).

I consider this use case representative of the vast majority: an all-Python library that you want to share with yourself and others on PyPI. Common development tasks should be easy:

  • running tests (across multiple versions of Python TBD);
  • running a suite of state-of-the-art static analyses (including style checkers);
  • building and publishing documentation (using the most common extensions);
  • continuous integration on the big three platforms (Linux, OSX, and Windows); and
  • publishing to PyPI (even without knowing the intricacies of Python packaging).

Tangentially, I spent a bunch of time on the documentation walking through each feature and explaining it from the ground up so that a newcomer can understand. I want the documentation to leave users with no unanswered questions. That means if you have a question, then the documentation is incomplete! Please let me know so that I can fill any gaps.

Why did you choose X?

This project makes choices for each of its features, and there are bound to be people who do not like them or understand them. The rest of the documentation tries to explain each individual choice, but I will outline here the general philosophy.

For dependency management and packaging, there is one tool emerging that both

  1. offers a good user experience to the point that you might never need to manually edit your package metadata file or learn the history and pain of Python packaging, and
  2. uses a single, standard (PEP 518) package metadata file (pyproject.toml).

That tool is Poetry. Shout to Pipenv for leading the way on the first point, but in my opinion it has been overtaken.

For the rest of the tools (style checkers, static analyzers, test, docs, CI), I have tried to choose the most popular, battle-tested solutions. As the landscape changes, this project will change with it.

Why didn’t you choose Y?

If you think I’ve made an error, please let me know in the issues. Please remember that each choice is the result of a significant investment of my time in researching alternatives. I have not yet documented why I chose against the ones that I did, but I am open to having that discussion (and I would like to link back to those discussions from a “graveyard” chapter in the documentation).

[1]With the exception of a few additions. Most notably, the content of this documentation is not generated (but its boilerplate is).