pytemplates-pypackage 0.0.8

A template for a python package.

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

Install the package using poetry:

poetry install

Install optional dependencies using the --extras flag:

poetry install --extras={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 lint - Run the linting tools. Includes pre-commit hooks, black, isort, flake8, pylint, and mypy.

• make test - Run the tests using pytest.

• make check - Run the lint and test 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

• lint - Run the linting tools on every push/pull_request to the main branch. Includes pre-commit hooks, black, isort, flake8, pylint, and mypy.

• 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.

• 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 docs branch and hosted on github pages.

Releases

A release should consist of the following three steps from a clean, 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 simply the version number prepended with a 'v'.

2. git push - Update the main branch with only the changes from the version bump. Wait until the test and lint workflows have completed successfully before starting the release workflow.

3. git push --tags - Publish the new tag to 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