A production ready python CLI template.
Project description
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, and isort 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.
- Docker images are automatically published to Docker Hub during every release. Images are tagged with a semantic version number which agrees with the git tag and the PyPI version number.
- Documentation is built using mkdocs and mkdocstrings. Docs are automatically deployed to github pages during every release.
- Release notes are automatically generated during every release using github actions.
Full 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
To begin local development, clone the PyTemplates/typer_cli repository and use one of the following methods to build it. Commands should be executed from inside of the project home folder.
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 = [
"mkdocs",
"mkdocstrings",
"mkdocstrings-python",
"mkdocs-material",
]
# Includes all optional dependencies
dev = [
"pytest",
"pytest-cov",
"black",
"isort",
"flake8",
"pylint",
"mypy",
"pre-commit",
"mkdocs",
"mkdocstrings",
"mkdocstrings-python",
"mkdocs-material",
"bump2version",
]
Using a local docker build
To build an image locally from the Dockerfile:
make build
To run the image:
docker run --rm pytemplates_typer_cli hello user
docker run --rm pytemplates_typer_cli goodbye user
docker run --rm pytemplates_typer_cli version
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 HTML documentation. -
make docs
- Generate 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 documentation, publish to the 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 wheel distribution, build a docker image, create a github release, and publish to PyPI and Docker Hub whenever a new tag is created. Linting and testing steps must pass before the release steps can begin. Documentation is automatically published to the docs branch and hosted on github pages. All github release tags, docker image tags, and PyPI version numbers are in agreement with one another and follow semantic versioning standrads.
Releases
A release should consist of the following two steps from a tested, linted, and up to date copy of the main branch:
-
make pre-release increment={major/minor/patch}
- Commit the version 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'. -
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
.
├── Dockerfile
├── docs
│ ├── app_reference
│ │ └── app.md
│ ├── code_reference
│ │ ├── module1.md
│ │ └── module2.md
│ ├── developer_guide
│ │ ├── commands.md
│ │ ├── developer_setup.md
│ │ ├── releases.md
│ │ └── workflows.md
│ ├── extras
│ │ ├── credits.md
│ │ └── file_tree.md
│ ├── index.md
│ └── user_guide
│ ├── installation.md
│ └── usage.md
├── LICENSE
├── Makefile
├── mkdocs.yml
├── poetry.lock
├── pyproject.toml
├── README.md
├── src
│ └── pytemplates_typer_cli
│ ├── core
│ │ ├── __init__.py
│ │ ├── module1.py
│ │ └── module2.py
│ ├── __init__.py
│ ├── main.py
│ └── __version__.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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pytemplates_typer_cli-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 91f36b56438e207cd2243057cdf8db186180699ad79a4c1f6631ce2fd6a5789f |
|
MD5 | 6583289642fe2aea48f4e4b3e6039459 |
|
BLAKE2b-256 | c581d68d8162fb5a678b76d721538356810d6df3d175ad17db83815709b31c04 |
Hashes for pytemplates_typer_cli-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c5e5dffe8fcfa4c9c5fcb0746d30a83a68f558426ea79f90f87fb97169741a47 |
|
MD5 | 672299fa033805a21c7987460918aef5 |
|
BLAKE2b-256 | afd7004227aebc6c1443fc97ee3c1e28d50241f753184b3ca336e8d6e6b2d62b |