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 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 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.12 or above
• uv

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.

---

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.