python-starter-package 1.0.0

Python starter project

python-starter

Example Python project that demonstrates how to create a tested Python package using the latest Python testing and linting tooling. The project contains a div package that provides a simple implementation of division (div.lib) and a command line interface (div.cli).

Requirements

Python 3.6+.

Note

Because Python 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.

Running CLI application

• export PYTHONPATH="${PYTHONPATH}:<path_to_directory>/python-starter/src"
• python cli.py -a 5 -b 2

Dependencies

Dependencies are defined in:

• requirements.txt
• dev-requirements.txt

Virtual Environments

It is best practice during development to create an isolated Python virtualenv wrapper using the mkvirtualenv command. This will keep dependant Python packages from interfering with other Python projects on your system.

On *Nix:

$ mkvirtualenv -p python3.x venv

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

Installing Dependencies

To update dependencies:

(venv) $ pip install -r requirements.txt
(venv) $ pip install -r dev-requirements.txt

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.

Packaging

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/div-1.0.0.tar.gz and dist/div-1.0.0-py3-none-any.whl.

Read more about the advantages of wheels to understand why generating wheel distributions are important.

Upload Distributions to PyPI

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/*

Testing

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
# command above.
(venv) $ tox

Unit Testing

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:

1. Significantly less boilerplate needed for tests.
2. PEP8 compliant names (e.g. pytest.raises() instead of self.assertRaises()).
3. 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 py36), 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 py36 -- -k invalid_divide

Code Style Checking

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.

Automated Code Formatting

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

Generated API Documentation

Generate a New Sphinx Project

To generate the Sphinx project shown in this project:

(venv) $ mkdir -p docs/api
(venv) $ cd docs/api
(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"))

You might also need to add apidoc/modules.rst in index.rst file (See line number 13). This has already been done for this project but might be helpful if you start a project of your own.

API Documentation for the div Python project modules is automatically generated using a Sphinx tox environment. Sphinx is a documentation generation tool that is the defacto tool for Python API 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.

"""Divides first input with the second input.

Args:
    a: Numerator
    b: Denominator

Raises:
    InvalidDivideError: If denominator is 0

Returns:
    Computed division.
"""

The Sphinx project is configured in docs/api/conf.py.

This project uses the furo Sphinx theme for its elegant, simple to use, dark theme.

Build the docs using the docs-api tox environment (e.g. tox or tox -e docs-api). Once built, open docs/api/_build/index.html in a web browser.

To configure Sphinx to automatically rebuild when it detects changes, run tox -e docs-api-serve and open http://127.0.0.1:8000 in a browser.