kevinoid/python-project-template

Project Template

A Python project template with pytest, tox, Sphinx (with sphinx-apidoc and sphinx-argparse), GitHub Actions, GitLab CI, coveralls, Codecov, and several linters including flake8 (with many plugins), Bandit, Black, pyroma, and others.

This template is the basis of my own Python projects, representing my current preferences. I am not advocating for these choices nor this template specifically, although I am happy to discuss or explain any choices made herein. It is being published both for my own convenience and in case it may be useful to others with similar tastes.

Introductory Example

import packagename

packagename.foo()

(Mis-)Features

All module sources are in src rather than the top-level directory. I was initially against this idea, but was swayed by Ionel Cristian Mărieș' Packaging a python library, Hynek Schlawack's Testing & Packaging, and pytest Good Integration Practices.
Minimally constrained top-level dependencies are declared in requirements/*.in files. Full, exact, hash-checked, known-good dependency versions are stored in requirements/*.txt. These can be generated using pip-compile from pip-tools or (if hashes are not required) pip install && pip freeze in a fresh virtual environment:
```
for requirements in requirements/*.in; do
    pip-compile --generate-hashes "$requirements"
done
```
This system has the benefit of allowing easy installation of fully or minimally constrained dependencies from many tools (setup.py, pip, tox, etc.) without duplication.

I have experimented with several other approaches, including pip constraint files (constraints.txt), Pipenv (Pipfile/Pipfile.lock), Poetry (pyproject.toml), and a few others, along with other tools to sync with or generate requirements.txt and setup.cfg. Although these approaches have several benefits, I think the additional complexity (both inherent and when integrating with other tools like tox) currently outweighs their value.
tox (used for CI) is configured to use minimally constrained dependencies. This is desirable for library packages, since user installs are minimally constrained. If the package will be deployed as an application using requirements.txt, consider changing requirements*.in to requirements*.txt in tox.ini to test using exact dependency versions.

Installation

This package can be installed using pip, by running:

pip install python-project-template

Recipes

import packagename

packagename.bar(packagename.baz())

Documentation

The project documentation is hosted on Read the Docs. See the CLI documentation for command-line options and usage, and the API documentation for the Python API.

Contributing

Contributions are welcome and very much appreciated! See the contributing guidelines for recommendations.

License

This project is available under the terms of the MIT License. See the summary at TLDRLegal

The template upon which this project is based is available under the terms of CC0 1.0 Universal.