pytemplates-typer-cli 0.0.8

A production ready python CLI template.

Description

A production ready python CLI 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_typer_cli

To download the CLI application using docker:

docker pull pytemplates/typer_cli:latest

Usage

Using the python package installation:

pytemplates hello user
pytemplates goodbye user
pytemplates version

Using the docker image:

docker run --rm pytemplates/typer_cli hello user
docker run --rm pytemplates/typer_cli goodbye user
docker run --rm pytemplates/typer_cli version

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.

• make build - Build a docker image locally using the Dockerfile. The image will be named pytemplates_typer_cli.

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

• docker - Build the docker image, tag it with the branch name, and publish it to dockerhub. 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
├── README.md
├── Makefile
├── Dockerfile
├── poetry.lock
├── pyproject.toml
├── src
│   └── pytemplates_typer_cli
│       ├── core
│       │   ├── __init__.py
│       │   ├── module1.py
│       │   └── module2.py
│       ├── __init__.py
│       ├── __version__.py
│       └── main.py
└── tests
    ├── __init__.py
    ├── test_app.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