A template Python project (template-python)

This project contains sample code for a Python CLI app. It attempts to create a Python development environment that is simple but allows a fast development cycle to produce high-quality code. This is inspired by the “Boring Python” posts ¹² by James Bennett.

✨ Features

The following libraries and frameworks are configured and working out of the box.

• hatch (MIT License): Project and dependency management.
• flake8 (MIT License): Code linter, with several plugins configured.
• black (MIT License): Code style formatter.
• isort (MIT License): Import organizer.
• mypy (MIT License): Static typing.
• bandit (Apache License): Security linter.
• pytest (MIT License): Tests.
• pytest-cov (MIT License): Test coverage.
• typer (MIT License): Library for parsing CLI arguments and storing configuration.
• GitHub Actions: Continuous integration.
• GitHub Dependabot: Automated dependency updates.
• EditorConfig: Generic editor config.
• Some niceties for VS Code (see below).

⚙️ Setup

Do either of the following.

• Use this template button on GitHub to create a new project
• Open in a codespace button on GitHub to start playing with the project
• Download, copy, or clone the project

Visual Studio Code

You can skip this section if you prefer an editor that is not VSCode.

The fastest route to productivity will come from opening this project remotely in a Dev Container. The only requirement is Docker Desktop. Everything else will be automatically installed into the Dev Container. A Docker account is not needed. If you open the project locally, VSCode will prompt to open inside the configured Dev Container.

Once the container is ready, the project will be buildable, lintable, and testable. Linting and formatting will be automatically done as you save. Check the Problems tab for lint issues. Test cases will be automatically discovered in the Testing tab. You can run all the tests or start debugging from here.

If running locally instead, you will need Python3 with hatch (pip install hatch). In this scenario, it might be worthwhile to point VSCode to the Python interpreter of the dev environment in the project (hatch run dev:python -c "import sys;print(sys.executable)").

Other editors

Skip this section if you are using Dev Containers or Codespaces.

All following setup is optional. They are meant to increase life-of-quality during development.

• To run 'hatch' commands (see below):

pip install hatch

💻 Development cycle

• Run your CLI app

hatch run my-cli --help

• Run lint checks

hatch run dev:lint

• Run all tests

hatch run test:test

Check out the example app code to get accustomed to the setup. You will need to change any name that starts with “my”, like my description.

🤖 Continuous integration

There is a robust CI pipeline already setup. It contains the following jobs.

• lint: Checks that all lint checkers are happy amd would succeed.
• fmt: Format code with black and isort.
• test: Checks that all unit tests are passing on Linux, Mac, and Windows, with different Python versions.
• coverage: Checks that code coverage is above 80%. Optionally, uploads coverage to Codecov.
• build: Checks that a wheel is buildable and runs standard smoke tests against it.

Make sure your integration flow includes pull requests. Merge PRs only when the CI is successful, and you will have a good integration setup. Commit to main directly, and you will become a sad developer.

📦 Dependency management

All dependencies are pinned to a specific version. Dependabot will send occasional pull requests to update dependencies to available versions. Merge them only when CI is passing.

This is not a strict implementation of reproducible builds, since indirect dependencies are not locked to specific versions. If an indirect dependency has a new version that is incompatible with our app, it might break our integration. This will be remedied with a lock file once hatch supports locking dependencies.

👋 Help and contributions

I hope you will find this template useful. You can create an issue if you have a question, or if something is not working right for you. PRs are welcome if you would like to fix or add anything.

🚩 Roadmap

The project scaffolds a basic CLI application. You can build upon this for your own, or you can strip the CLI parts altogether to build a different type of Python package. Actual templating a la Cookiecuter could be useful.

This project does not yet include an end-to-end test. It would be an improvement to automatically download CI artifacts from the main branch and run tests against them.

Footnotes

1. Boring Python: dependency management ↩

2. Boring Python: code quality ↩