pycliche - a Python project template with opinionated tooling.

Embracing Boring Technology, fighting bloat, striving for simplicity.

Projects created using pycliche include:

• A basic Python package and entrypoint, configured via a pyproject.toml.
• Dependencies managed via uv, using a uv.lock file for reproducible builds.
• IPython as the default shell.
• Simple configuration to enhance your logs with structlog.
• Scaffolding for unit tests run via pytest.
• Out-of-the-box code coverage reporting with coverage.py.
• Batteries-included prek pre-commit hook configuration to lint & format code, and run SAST.

Optionally, for projects intended to be hosted on GitHub, also include:

• GitHub Actions to:
  • Automate cutting releases via Release Please.
  • Run prek pre-commit hooks and pytest as part of a Continuous Integration pipeline.
• A dependabot configuration to keep Python packages & GitHub Actions up to date.

Starting a Django project? Try djereo, built on pycliche, as your Django project template.

Prerequisites

To use pycliche the following must be available locally:

• Python 3.13 or above
• uv

pycliche supports the last two versions of Python - the ones with bugfix support as per https://devguide.python.org/versions/.

Bootstrap a new Python project

Bootstrap a new Python project using pycliche:

1. Navigate to the directory under which you wish to create a new project.
2. Run uvx copier copy --trust gh:albertomh/pycliche <project_name> and follow the wizard.

This creates a directory under your current location. Follow the README in the new directory to get started with your project.

Please note:

• it is not necessary to clone pycliche. The gh:albertomh/pycliche argument will pull the latest tag from GitHub.
• the --trust flag is necessary since a post-creation task initialises the new directory as a git repository and generates a uv lockfile.

Update existing projects

To update a project created using an older version of pycliche to a newer version of the template:

cd ~/Projects/existing_project/
uvx copier update --skip-answered --trust [--vcs-ref=<TAG>]

If the --vcs-ref flag is not specified copier will use the latest pycliche tag.

Make your package installable

Projects generated using pycliche use the hatchling build system and the uv toolchain to package releases. Build a release by:

# merge a release-please PR to create a tag and a GitHub Release

# check out the tag locally

# in your project's root directory
uv build

# upload the artefacts as an asset linked to the release at
# <https://github.com/myusername/mypackage/releases/tag/vM.m.p>

To use your package as a dependency in a project:

# add the following line to the dependencies table in `pyproject.toml`:
"mypackage @ https://github.com/myusername/mypackage/releases/download/vM.m.p/mypackage-M.m.p-py3-none-any.whl"

# update the project's virtual environment
uv sync

You can also run modules directly once your package is installed as a dependency:

uv run python -m mypackage.some_module

---

Develop

The developer README (docs/README-dev.md) covers how to work on pycliche itself. It covers:

• Develop

  • Development prerequisites
  • Recursive pycliche
  • Git principles
  • Dependency management
    • Updating dependencies in the template
  • Generate project using development version
  • Style

• Test

• Tests in GitHub Actions

• Release

  • GitHub Personal Access Token

• Record demo

---

Acknowledgements

Several tooling choices have been guided by the work of Adam Johnson.

The pycliche logo is typeset in Allerta Stencil. Python icon generated using DALL·E.