pytemplates-pypackage 0.1.5

A production ready python library template.

Description

A production ready python library template

• Metadata and dependency information is stored in the pyproject.toml for compatibility with both pip and poetry.
• Flake8, pylint, isort, and pytest configurations are defined to be compatible with the black autoformatter.
• Pylint settings are based on the Google Python Style Guide and adapted for black compatibility.
• Linting tools run automatically before each commit using pre-commit, black, and isort.
• Test coverage reports are generated during every commit and pull request using coverage and pytest-cov. All reports are automatically uploaded and archived on codecov.io.
• Unit tests are written using pytest and static type checking is provided by mypy.
• Package releases to PyPI with dynamic versioning provided by bump2version begin automatically whenever a new tag is created in github.
• Sphinx documentation is automatically generated and deployed to github pages during every release.
• Release notes are automatically generated during every release using github actions.

Source code documentation

Installation

To install the package using pip:

pip install pytemplates_pypackage

To add the package as a dependency using poetry:

poetry add pytemplates_pypackage

Usage

From a .py file:

import pytemplates_pypackage
print(pytemplates_pypackage.__version__)
pytemplates_pypackage.greet(user="Jacob")

from pytemplates_pypackage import wish_farewell
wish_farewell(user="Jacob")

Developer Setup

Using poetry

poetry install

Install optional dependencies using the --extras flag:

poetry install --extras=environment

Using pip

pip install .

Install optional dependencies using square brackets:

pip install .[environment]

Environments

test = [
    "pytest",
    "pytest-cov",
]

lint = [
    "black",
    "isort",
    "flake8",
    "pylint",
    "mypy",
    "pre-commit",
]

docs = [
    "Sphinx",
    "sphinx-rtd-theme",
]

# Includes all optional dependencies
dev = [
    "pytest",
    "pytest-cov",
    "black",
    "isort",
    "flake8",
    "pylint",
    "mypy",
    "pre-commit",
    "Sphinx",
    "sphinx-rtd-theme",
    "bump2version",
]

Commands

• make clean - Remove all build, testing, and static documentation files.

• make test - Run the tests using pytest.

• make lint - Run the linting tools. Includes pre-commit hooks, black, isort, flake8, pylint, and mypy.

• make check - Run the test and lint commands, followed by the clean command.

• make gen-docs - Generate Sphinx HTML documentation.

• make docs - Generate Sphinx HTML documentation and serve it to the browser.

• make pre-release increment={major/minor/patch} - Bump the version and create a release tag. Should only be run from the main branch. Passes the increment value to bump2version to create a new version number dynamically. The new version number will be added to _version_.py and pyproject.toml and a new commit will be logged. The tag will be created from the new commit.

Workflows

• test - Run the tests on every push/pull_request to the main branch. Writes a coverage report using pytest-cov and uploads it to codecov.io. Tests run against python versions 3.8 and 3.9. Optional manual trigger in the github actions tab.

• lint - Run the linting tools on every push/pull_request to the main branch. Includes pre-commit hooks, black, isort, flake8, pylint, and mypy. Optional manual trigger in the github actions tab.

• docs - Build the sphinx documentation, publish to the sphinx-docs branch, and release to github pages. Runs on a manual trigger in the github actions tab.

• release - Build a package distribution, create a github release, and publish the distribution to PyPI whenever a new tag is created. Linting and testing steps must pass before the release steps can begin. Sphinx documentation is automatically published to the sphinx-docs branch and hosted on github pages.

Releases

A release should consist of the following two steps from a tested, linted, and up to date copy of the main branch:

1. make pre-release increment={major/minor/patch} - Commit the version number bump and create a new tag locally. The version number follows semantic versioning standards (major.minor.patch) and the tag is the version number prepended with a 'v'.

2. git push --follow-tags - Update the main branch with only the changes from the version bump. Publish the new tag and kick off the release workflow.

File Tree

.
├── docs/
├── LICENSE
├── Makefile
├── poetry.lock
├── pyproject.toml
├── README.md
├── src
│   └── pytemplates_pypackage
│       ├── core
│       │   ├── __init__.py
│       │   ├── module1.py
│       │   └── module2.py
│       ├── __init__.py
│       └── __version__.py
└── tests
    ├── __init__.py
    ├── test_module1.py
    └── test_module2.py

Credits

Other python package templates

• https://github.com/waynerv/cookiecutter-pypackage
• https://github.com/AllenCellModeling/cookiecutter-pypackage

Actions

• https://github.com/JamesIves/github-pages-deploy-action
• https://github.com/softprops/action-gh-release