Example Python project that demonstrates how to create a tested Python package using the latest
Python testing and linting tooling. The project contains a fact
package that provides a
simple implementation of the factorial algorithm
(fact.lib
) and a command line interface (fact.cli
).
Python 3.6+.
Note
Because Python 2.7 supports ended January 1, 2020, new projects should consider supporting Python 3 only, which is simpler than trying to support both. As a result, support for Python 2.7 in this example project has been dropped.
Summary: On Windows, use py
instead of python3
for many of the examples in this
documentation.
This package fully supports Windows, along with Linux and macOS, but Python is typically
installed differently on Windows.
Windows users typically access Python through the
py launcher rather than a python3
link in their PATH
. Within a virtual environment, all platforms operate the same and use a
python
link to access the Python version used in that virtual environment.
Dependencies are defined in:
requirements.in
requirements.txt
dev-requirements.in
dev-requirements.txt
It is best practice during development to create an isolated
Python virtual environment using the
venv
standard library module. This will keep dependant Python packages from interfering
with other Python projects on your system.
On *Nix:
# On Python 3.9+, add --upgrade-deps
$ python3 -m venv venv
$ source venv/bin/activate
On Windows cmd
:
> py -m venv venv
> venv\Scripts\activate.bat
Once activated, it is good practice to update core packaging tools (pip
, setuptools
, and
wheel
) to the latest versions.
(venv) $ python -m pip install --upgrade pip setuptools wheel
This project uses pip-tools to lock project dependencies and create reproducible virtual environments.
Note: Library projects should not lock their requirements.txt
. Since python-blueprint
also has a CLI application, this end-user application example is used to demonstrate how to
lock application dependencies.
To update dependencies:
(venv) $ python -m pip install pip-tools
(venv) $ pip-compile --upgrade
(venv) $ pip-compile --upgrade dev-requirements.in
After upgrading dependencies, run the unit tests as described in the Unit Testing section to ensure that none of the updated packages caused incompatibilities in the current project.
To cleanly install your dependencies into your virtual environment:
(venv) $ pip-sync requirements.txt dev-requirements.txt
This project is designed as a Python package, meaning that it can be bundled up and redistributed as a single compressed file.
Packaging is configured by:
pyproject.toml
setup.py
MANIFEST.in
To package the project as both a source distribution and a wheel:
(venv) $ python setup.py sdist bdist_wheel
This will generate dist/fact-1.0.0.tar.gz
and dist/fact-1.0.0-py3-none-any.whl
.
Read more about the advantages of wheels to understand why generating wheel distributions are important.
Source and wheel redistributable packages can be
uploaded to PyPI or installed
directly from the filesystem using pip
.
To upload to PyPI:
(venv) $ python -m pip install twine
(venv) $ twine upload dist/*
Automated testing is performed using tox.
tox will automatically create virtual environments based on tox.ini
for unit testing,
PEP8 style guide checking, and documentation generation.
# Run all environments.
# To only run a single environment, specify it like: -e lint
# Note: tox is installed into the virtual environment automatically by pip-sync command above.
(venv) $ tox
Unit testing is performed with pytest. pytest has become the defacto Python unit testing framework. Some key advantages over the built in unittest module are:
- Significantly less boilerplate needed for tests.
- PEP8 compliant names (e.g.
pytest.raises()
instead ofself.assertRaises()
). - Vibrant ecosystem of plugins.
pytest will automatically discover and run tests by recursively searching for folders and .py
files prefixed with test
for any functions prefixed by test
.
The tests
folder is created as a Python package (i.e. there is an __init__.py
file
within it) because this helps pytest
uniquely namespace the test files. Without this,
two test files cannot be named the same, even if they are in different sub-directories.
Code coverage is provided by the pytest-cov plugin.
When running a unit test tox environment (e.g. tox -e py37
), an HTML report is
generated in the htmlcov
folder showing each source file and which lines were executed during
unit testing. Open htmlcov/index.html
in a web browser to view the report. Code coverage
reports help identify areas of the project that are currently not tested.
Code coverage is configured in pyproject.toml
.
To pass arguments to pytest
through tox
:
(venv) $ tox -e py37 -- -k invalid_factorial
PEP8 is the universally accepted style
guide for Python code. PEP8 code compliance is verified using flake8.
flake8 is configured in the [flake8]
section of tox.ini
. Extra flake8 plugins
are also included:
pep8-naming
: Ensure functions, classes, and variables are named with correct casing.
Code is automatically formatted using black. Imports are automatically sorted and grouped using isort.
These tools are configured by:
pyproject.toml
To automatically format code, run:
(venv) $ tox -e fmt
To verify code has been formatted, such as in a CI job:
(venv) $ tox -e fmt-check
Documentation that includes the README.rst
and the Python project modules is automatically
generated using a Sphinx tox environment. Sphinx is a documentation
generation tool that is the defacto tool for Python documentation. Sphinx uses the
RST markup language.
This project uses the napoleon plugin for Sphinx, which renders Google-style docstrings. Google-style docstrings provide a good mix of easy-to-read docstrings in code as well as nicely-rendered output.
"""Computes the factorial through a recursive algorithm.
Args:
n: A positive input value.
Raises:
InvalidFactorialError: If n is less than 0.
Returns:
Computed factorial.
"""
The Sphinx project is configured in docs/conf.py
.
Build the docs using the docs
tox environment (e.g. tox
or tox -e docs
). Once built,
open docs/_build/index.html
in a web browser.
To generate the Sphinx project shown in this project:
# Note: Sphinx is installed into the virtual environment automatically by pip-sync command
# above.
(venv) $ mkdir docs
(venv) $ cd docs
(venv) $ sphinx-quickstart --no-makefile --no-batchfile --extensions sphinx.ext.napoleon
# When prompted, select all defaults.
Modify conf.py
appropriately:
# Add the project's Python package to the path so that autodoc can find it.
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
...
html_theme_options = {
# Override the default alabaster line wrap, which wraps tightly at 940px.
'page_width': 'auto',
}
Modify index.rst
appropriately:
.. include:: ../README.rst apidoc/modules.rst
Continuous integration is provided by GitHub Actions. This runs all tests and lints for every commit and pull request to the repository.
GitHub Actions is configured in .github/workflows/python.yml
and tox.ini
using the
tox-gh-actions plugin.
Traditionally, Python projects place the source for their packages in the root of the project structure, like:
fact ├── fact │ ├── __init__.py │ ├── cli.py │ └── lib.py ├── tests │ ├── __init__.py │ └── test_fact.py ├── tox.ini └── setup.py
However, this structure is known to have bad
interactions with pytest
and tox
, two standard tools maintaining Python projects. The
fundamental issue is that tox creates an isolated virtual environment for testing. By installing
the distribution into the virtual environment, tox
ensures that the tests pass even after the
distribution has been packaged and installed, thereby catching any errors in packaging and
installation scripts, which are common. Having the Python packages in the project root subverts
this isolation for two reasons:
- Calling
python
in the project root (for example,python -m pytest tests/
) causes Python to add the current working directory (the project root) tosys.path
, which Python uses to find modules. Because the source packagefact
is in the project root, it shadows thefact
package installed in the tox environment. - Calling
pytest
directly anywhere that it can find the tests will also add the project root tosys.path
if thetests
folder is a a Python package (that is, it contains a__init__.py
file). pytest adds all folders containing packages tosys.path
because it imports the tests like regular Python modules.
In order to properly test the project, the source packages must not be on the Python path. To prevent this, there are three possible solutions:
- Remove the
__init__.py
file fromtests
and runpytest
directly as a tox command. - Remove the
__init__.py
file from tests and change the working directory ofpython -m pytest
totests
. - Move the source packages to a dedicated
src
folder.
The dedicated src
directory is the recommended solution
by pytest
when using tox and the solution this blueprint promotes because it is the least
brittle even though it deviates from the traditional Python project structure. It results is a
directory structure like:
fact ├── src │ └── fact │ ├── __init__.py │ ├── cli.py │ └── lib.py ├── tests │ ├── __init__.py │ └── test_fact.py ├── tox.ini └── setup.py
Type hinting allows developers to include optional static typing information to Python source code. This allows static analyzers such as PyCharm, mypy, or pytype to check that functions are used with the correct types before runtime.
For PyCharm in particular, the IDE is able to provide much richer auto-completion, refactoring, and type checking while the user types, resulting in increased productivity and correctness.
This project uses the type hinting syntax introduced in Python 3:
def factorial(n: int) -> int:
Type checking is performed by mypy via tox -e type-check
. mypy is configured in setup.cfg
.
PEP 561 defines how a Python package should communicate the presence of inline type hints to static type checkers. mypy's documentation provides further examples on how to do this as well.
mypy
looks for the existence of a file named py.typed
in the root of the installed
package to indicate that inline type hints should be checked.
Licensing for the project is defined in:
LICENSE.txt
setup.py
This project uses a common permissive license, the MIT license.
You may also want to list the licenses of all of the packages that your Python project depends on.
To automatically list the licenses for all dependencies in requirements.txt
(and their
transitive dependencies) using
pip-licenses:
(venv) $ tox -e licenses
...
Name Version License
colorama 0.4.3 BSD License
exitstatus 1.3.0 MIT License
Docker is a tool that allows for software to be packaged into isolated containers. It is not necessary to use Docker in a Python project, but for the purposes of presenting best practice examples, a Docker configuration is provided in this project. The Docker configuration in this repository is optimized for small size and increased security, rather than simplicity.
Docker is configured in:
Dockerfile
.dockerignore
To build the Docker image:
$ docker build --tag fact .
To run the image in a container:
# Example calculating the factorial of 5.
$ docker run --rm --interactive --tty fact -n 5
To configure PyCharm 2018.3 and newer to align to the code style used in this project:
Settings | Search "Hard wrap at"
- Editor | Code Style | General | Hard wrap at: 99
Settings | Search "Optimize Imports"
Editor | Code Style | Python | Imports
☑ Sort import statements
- ☑ Sort imported names in "from" imports
- ☐ Sort plain and "from" imports separately within a group
- ☐ Sort case-insensitively
Structure of "from" imports
- ◎ Leave as is
- ◉ Join imports with the same source
- ◎ Always split imports
Settings | Search "Docstrings"
- Tools | Python Integrated Tools | Docstrings | Docstring Format: Google
Settings | Search "Force parentheses"
Editor | Code Style | Python | Wrapping and Braces | "From" Import Statements
- ☑ Force parentheses if multiline
To integrate automatic code formatters into PyCharm, reference the following instructions:
-
- The File Watchers method (step 3) is recommended. This will run
black
on every save.
- The File Watchers method (step 3) is recommended. This will run
-
- The File Watchers method (option 1) is recommended. This will run
isort
on every save.
- The File Watchers method (option 1) is recommended. This will run
Tip
These tools work best if you properly mark directories as excluded from the project that should
be, such as .tox
. See
https://www.jetbrains.com/help/pycharm/project-tool-window.html#content_pane_context_menu
on how to Right Click | Mark Directory as | Excluded.