Package: fact-test-001
python-blueprintExample Python project that demonstrates how to create a tested Python package using the latest
Python testing and linting tooling. The project contains afactpackage that provides a simple
implementation of thefactorial algorithm(fact.lib)
and a command line interface (fact.cli).RequirementsPython 3.6+.NoteBecausePython 2.7 support 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.Windows SupportSummary: On Windows, usepyinstead ofpython3for many of the examples in this documentation.This package fully supports Windows, along with Linux and macOS, but Python is
typicallyinstalled differently on Windows. Windows
users typically access Python through thepylauncher
rather than apython3link in theirPATH. Within a virtual environment, all platforms operate
the same and use apythonlink to access the Python version used in that virtual environment.DependenciesDependencies are defined in:requirements.inrequirements.txtdev-requirements.indev-requirements.txtVirtual EnvironmentsIt is best practice during development to create an
isolatedPython virtual environmentusing thevenvstandard 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-mvenvvenv
$sourcevenv/bin/activateOn Windowscmd:>py-mvenvvenv
>venv\Scripts\activate.batOnce activated, it is good practice to update core packaging tools (pip,setuptools,
andwheel) to the latest versions.(venv)$python-mpipinstall--upgradepipsetuptoolswheel(Applications Only) Locking DependenciesThis project usespip-toolsto lock project dependencies
and create reproducible virtual environments.Note:Libraryprojects should not lock theirrequirements.txt. Sincepython-blueprintalso has a CLI application, this end-user application example is used to demonstrate how to lock
application dependencies.To update dependencies:(venv)$python-mpipinstallpip-tools(venv)$python-mpiptoolscompile--upgraderequirements.in(venv)$python-mpiptoolscompile--upgradedev-requirements.inAfter upgrading dependencies, run the unit tests as described in theUnit Testingsection to ensure that none of the updated packages caused incompatibilities in the current
project.Syncing Virtual EnvironmentsTo cleanly install your dependencies into your virtual environment:(venv)$python-mpiptoolssyncrequirements.txtdev-requirements.txtPackagingThis 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.tomlsetup.pyMANIFEST.inTo package the project as both asource distributionand
awheel:(venv)$pythonsetup.pysdistbdist_wheelThis will generatedist/fact-1.0.0.tar.gzanddist/fact-1.0.0-py3-none-any.whl.Read more about theadvantages of wheelsto understand why generating
wheel distributions are important.Upload Distributions to PyPISource and wheel redistributable packages can
beuploaded to PyPIor installed
directly from the filesystem usingpip.To upload to PyPI:(venv)$python-mpipinstalltwine(venv)$twineuploaddist/*TestingAutomated testing is performed usingtox. tox
will automatically create virtual environments based ontox.inifor 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 ``piptools sync``# command above.(venv)$toxUnit TestingUnit testing is performed withpytest. pytest has become the defacto Python
unit testing framework. Some key advantages over the built
inunittestmodule 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.pyfiles prefixed withtestfor any functions prefixed bytest.Thetestsfolder is created as a Python package (i.e. there is an__init__.pyfile within it)
because this helpspytestuniquely 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 thepytest-covplugin.When running a unit test tox environment (e.g.tox -e py39), an HTML report is generated in
thehtmlcovfolder showing each source file and which lines were executed during unit testing.
Openhtmlcov/index.htmlin 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 inpyproject.toml.To pass arguments topytestthroughtox:(venv)$tox-epy39---kinvalid_factorialCode Style CheckingPEP8is the universally accepted style guide for
Python code. PEP8 code compliance is verified usingflake8. flake8 is
configured in the[flake8]section oftox.ini. Extra flake8 plugins are also included:pep8-naming: Ensure functions, classes, and variables are named with correct casing.Automated Code FormattingCode is automatically formatted usingblack. Imports are
automatically sorted and grouped usingisort.These tools are configured by:pyproject.tomlTo automatically format code, run:(venv)$tox-efmtTo verify code has been formatted, such as in a CI job:(venv)$tox-efmt-checkGenerated API DocumentationAPI Documentation for thefactPython project modules is automatically
generated using aSphinxtox environment. Sphinx is a documentation
generation tool that is the defacto tool for Python API documentation. Sphinx uses
theRSTmarkup language.This project uses
thenapoleonplugin 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 indocs/api/conf.py.This project uses thefuroSphinx theme for its elegant, simple to
use, dark theme.Build the docs using thedocs-apitox environment (e.g.toxortox -e docs-api). Once built,
opendocs/api/_build/index.htmlin a web browser.To configure Sphinx to automatically rebuild when it detects changes, runtox -e docs-api-serveand openhttp://127.0.0.1:8000in a browser.Generate a New Sphinx ProjectTo generate the Sphinx project shown in this project:# Note: Sphinx is installed into the virtual environment automatically by ``piptools sync``# command above.(venv)$mkdir-pdocs/api(venv)$cddocs/api(venv)$sphinx-quickstart--no-makefile--no-batchfile--extensionssphinx.ext.napoleon# When prompted, select all defaults.Modifyconf.pyappropriately:# Add the project's Python package to the path so that autodoc can find it.importosimportsyssys.path.insert(0,os.path.abspath("../../src"))Generating a User GuideMaterial for MkDocsis a powerful static site
generator that combines easy-to-write Markdown, with a number of Markdown extensions that increase
the power of Markdown. This makes it a great fit for user guides and other technical documentation.The example MkDocs project included in this project is configured to allow the built documentation
to be hosted at any URL or viewed offline from the file system.To build the user guide, runtox -e docs-user-guide. Opendocs/user_guide/site/index.htmlusing
a web browser.To build and serve the user guide with automatic rebuilding as you change the contents,
runtox -e docs-user-guide-serveand openhttp://127.0.0.1:8000in a browser.Each time themasterGit branch is updated, the.github/workflows/pages.ymlGitHub Action will
automatically build the user guide and publish it toGitHub Pages.
This is configured in thedocs-user-guide-github-pagestoxenvironment. This hosted user guide
can be viewed athttps://johnthagen.github.io/python-blueprint/Continuous IntegrationContinuous integration is provided byGitHub Actions. This
runs all tests and lints for every commit and pull request to the repository.GitHub Actions is configured in.github/workflows/python.ymlandtox.iniusing
thetox-gh-actions plugin.Project StructureTraditionally, 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.pyHowever, this structure
isknownto
have bad interactions withpytestandtox, 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,toxensures 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:Callingpythonin 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
packagefactis in the project root, it shadows thefactpackage installed in the tox
environment.Callingpytestdirectly anywhere that it can find the tests will also add the project root
tosys.pathif thetestsfolder is a a Python package (that is, it contains a__init__.pyfile).pytest adds all folders containing packagestosys.pathbecause 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__.pyfile fromtestsand runpytestdirectly as a tox command.Remove the__init__.pyfile from tests and change the working directory ofpython -m pytesttotests.Move the source packages to a dedicatedsrcfolder.The dedicatedsrcdirectory is therecommended solutionbypytestwhen 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.pyType HintingType hintingallows developers to include optional
static typing information to Python source code. This allows static analyzers such
asPyCharm,mypy,
orPyreto check that functions are used with the correct
types before runtime.ForPyCharm 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:deffactorial(n:int)->int:Type checking is performed by mypy viatox -e type-check. mypy is configured inpyproject.toml.See alsoawesome-python-typing.Distributing Type HintsPEP 561defines how a Python package should
communicate the presence of inline type hints to static type
checkers.mypy's documentationprovides further examples on how to do this as well.Mypy looks for the existence of a file namedpy.typedin the root of the installed package to
indicate that inline type hints should be checked.LicensingLicensing for the project is defined in:LICENSE.txtsetup.pyThis 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 inrequirements.txt(and their transitive
dependencies) usingpip-licenses:(venv)$tox-elicenses
...NameVersionLicensecolorama0.4.3BSDLicenseexitstatus1.3.0MITLicenseDockerDockeris 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.dockerignoreTo build the Docker image:$dockerbuild--tagfact.To run the image in a container:# Example calculating the factorial of 5.$dockerrun--rm--interactive--ttyfact5PyCharm ConfigurationTo 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: 99Settings | 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-insensitivelyStructure of "from" imports◎ Leave as is◉ Join imports with the same source◎ Always split importsSettings | Search "Docstrings"Tools | Python Integrated Tools | Docstrings | Docstring Format: GoogleSettings | Search "pytest"Tools | Python Integrated Tools | Testing | Default test runner: pytestSettings | Search "Force parentheses"Editor | Code Style | Python | Wrapping and Braces | "From" Import Statements☑ Force parentheses if multilineIntegrate Code FormattersTo integrate automatic code formatters into PyCharm, reference the following instructions:black integrationThe File Watchers method (step 6) is recommended. This will runblackon every save.isort integrationThe File Watchers method (option 1) is recommended. This will runisorton every save.TipThese tools work best if you properly mark directories as excluded from the project that should
be, such as.tox. Seehttps://www.jetbrains.com/help/pycharm/project-tool-window.html#content_pane_context_menuon
how to Right Click | Mark Directory as | Excluded.