Metadata-Version: 2.1
Name: pytemplates-typer-cli
Version: 0.0.9
Summary: A production ready python CLI template.
Home-page: https://github.com/PyTemplate/typer_cli
License: MIT
Author: crabtr26
Author-email: crabtr26@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: lint
Provides-Extra: test
Requires-Dist: Sphinx (>=4.5.0,<5.0.0); extra == "docs" or extra == "dev"
Requires-Dist: black (>=22.3.0,<23.0.0); extra == "lint" or extra == "dev"
Requires-Dist: bump2version (>=1.0.1,<2.0.0); extra == "dev"
Requires-Dist: flake8 (>=4.0.1,<5.0.0); extra == "lint" or extra == "dev"
Requires-Dist: isort (>=5.10.1,<6.0.0); extra == "lint" or extra == "dev"
Requires-Dist: mypy (>=0.961,<0.962); extra == "lint" or extra == "dev"
Requires-Dist: pre-commit (>=2.19.0,<3.0.0); extra == "lint" or extra == "dev"
Requires-Dist: pylint (>=2.13.8,<3.0.0); extra == "lint" or extra == "dev"
Requires-Dist: pytest (>=7.1.2,<8.0.0); extra == "test" or extra == "dev"
Requires-Dist: pytest-cov (>=3.0.0,<4.0.0); extra == "test" or extra == "dev"
Requires-Dist: sphinx-rtd-theme (>=1.0.0,<2.0.0); extra == "docs" or extra == "dev"
Requires-Dist: typer (>=0.4.1,<0.5.0)
Project-URL: Repository, https://github.com/PyTemplate/typer_cli
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://user-images.githubusercontent.com/20674972/178172752-abd4497d-6a0e-416b-9eef-1b1c0dca8477.png">
    <img src="https://user-images.githubusercontent.com/20674972/178172752-abd4497d-6a0e-416b-9eef-1b1c0dca8477.png" alt="Pytemplates Banner" style="width:100%;">
  </a>
</p>

<p align="center">
  <a href="https://github.com/PyTemplate/typer_cli/actions/workflows/test.yaml">
    <img src="https://github.com/PyTemplate/typer_cli/actions/workflows/test.yaml/badge.svg" alt="Test status">
  </a>

  <a href="https://github.com/PyTemplate/typer_cli/actions/workflows/lint.yaml">
    <img src="https://github.com/PyTemplate/typer_cli/actions/workflows/lint.yaml/badge.svg" alt="Linting status">
  </a>

  <!-- <a href="https://github.com/PyTemplate/typer_cli/actions/workflows/release.yaml">
    <img src="https://github.com/PyTemplate/typer_cli/actions/workflows/release.yaml/badge.svg" alt="Release status">
  </a> -->

  <a href="https://results.pre-commit.ci/latest/github/PyTemplate/typer_cli/main">
    <img src="https://results.pre-commit.ci/badge/github/PyTemplate/typer_cli/main.svg" alt="pre-commit.ci status">
  </a>

  <a href="https://codecov.io/gh/PyTemplate/typer_cli">
    <img src="https://codecov.io/gh/PyTemplate/typer_cli/branch/main/graph/badge.svg?token=HG1NQ8HRA4" alt="Code coverage status">
  </a>

  <a href="https://pypi.org/project/pytemplates-typer-cli/">
    <img src="https://badge.fury.io/py/pytemplates_typer_cli.svg" alt="PyPI version">
  </a>
</p>

## Description

### A production ready python CLI template

- Metadata and dependency information is stored in the pyproject.toml for compatibility with both [pip](https://pip.pypa.io/en/stable/) and [poetry](https://python-poetry.org/docs/).
- [Flake8](https://flake8.pycqa.org/en/latest/), [pylint](https://pylint.pycqa.org/en/latest/index.html), [isort](https://pycqa.github.io/isort/), and [pytest](https://docs.pytest.org/en/latest/) configurations are defined to be compatible with the [black](https://black.readthedocs.io/en/stable/) autoformatter.
- Pylint settings are based on the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) and adapted for black compatibility.
- Linting tools run automatically before each commit using [pre-commit](https://pre-commit.com/), black, and isort.
- Test coverage reports are generated during every commit and pull request using [coverage](https://coverage.readthedocs.io/en/6.4.1/) and [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/). All reports are automatically uploaded and archived on [codecov.io](https://about.codecov.io/).
- Unit tests are written using [pytest](https://docs.pytest.org/en/latest/) and static type checking is provided by [mypy](http://mypy-lang.org/index.html).
- Package releases to [PyPI](https://pypi.org/) with dynamic versioning provided by [bump2version](https://github.com/c4urself/bump2version) begin automatically whenever a new tag is created in github.
- Docker images are automatically published to [Docker Hub](https://hub.docker.com/) during every release. Images are tagged with a semantic version number which agrees with the git tag and the PyPI version number.
- [Sphinx](https://www.sphinx-doc.org/en/master/) source code documentation is automatically generated and deployed to [github pages](https://docs.github.com/en/pages) during every release.
- Release notes are automatically generated during every release using [github actions](https://docs.github.com/en/actions).

### [Source code documentation](https://pytemplate.github.io/typer_cli/)

## Installation

To install the package using `pip`:

```bash
pip install pytemplates_typer_cli
```

To download the CLI application using `docker`:

```bash
docker pull pytemplates/typer_cli:latest
```

## Usage

Using the python package installation:

```bash
pytemplates hello user
pytemplates goodbye user
pytemplates version
```

Using the docker image:

```bash
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 this repository and use one of the following methods to build it. Commands should be executed from inside of the project home folder (i.e. the location of this README).

### Using poetry:

```bash
poetry install
```

Install optional dependencies using the `--extras` flag:

```bash
poetry install --extras=environment
```

### Using pip:

```bash
pip install .
```

Install optional dependencies using square brackets:

```bash
pip install .[environment]
```

### Environments

```python
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",
]
```

### Using a local docker build:

To build an image locally from the Dockerfile:

```bash
make build
```

To run the image:
```bash
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 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 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. Sphinx documentation is automatically published to the *sphinx-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:

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

```bash
.
├── 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

