https://github.com/albertomh/pycliche
A Python project template with opinionated tooling
https://github.com/albertomh/pycliche
copier-template project-template python template uv
Last synced: 4 months ago
JSON representation
A Python project template with opinionated tooling
- Host: GitHub
- URL: https://github.com/albertomh/pycliche
- Owner: albertomh
- License: mit
- Created: 2024-01-17T23:01:47.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-11-26T08:40:09.000Z (6 months ago)
- Last Synced: 2025-11-28T07:40:31.114Z (6 months ago)
- Topics: copier-template, project-template, python, template, uv
- Language: Python
- Homepage:
- Size: 8.41 MB
- Stars: 34
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
`pycliche` - a Python project template with opinionated tooling.
Embracing [Boring Technology](https://boringtechnology.club/), fighting bloat, striving for
simplicity.
[](https://docs.python.org/3.13/whatsnew/3.13.html)
[](https://github.com/copier-org/copier)
[](https://github.com/astral-sh/uv)
[](https://ipython.readthedocs.io/en/stable/)
[](https://github.com/hynek/structlog)
[](https://github.com/j178/prek)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pytest-dev/pytest)
[](https://coverage.readthedocs.io/)
[](https://github.com/wntrblm/nox)
[](https://github.com/PyCQA/bandit)
[](https://github.com/googleapis/release-please)
[](https://github.com/albertomh/pycliche/actions/workflows/ci.yaml)
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.
> [](https://docs.djangoproject.com/en/stable/)
> Starting a Django project? Try [djereo](https://github.com/albertomh/djereo), built on
> pycliche, as your Django project template.
## Prerequisites
To use `pycliche` the following must be available locally:
- [Python 3.13](https://docs.python.org/3.13/) or above
- [uv](https://docs.astral.sh/uv/)
`pycliche` supports the last two versions of Python - the ones with bugfix support as per
.
## 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.
1. Run `uvx copier copy --trust gh:albertomh/pycliche ` 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:
```sh
cd ~/Projects/existing_project/
uvx copier update --skip-answered --trust [--vcs-ref=]
```
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](https://pypi.org/project/hatchling/)
and the `uv` toolchain to package releases. Build a release by:
```sh
# 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
#
```
To use your package as a dependency in a project:
```sh
# 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:
```sh
uv run python -m mypackage.some_module
```
---
## Develop
The developer README ([docs/README-dev.md](docs/README-dev.md)) covers how to work on
`pycliche` itself. It covers:
- [Develop](docs/README-dev.md#develop)
- [Development prerequisites](docs/README-dev.md#development-prerequisites)
- [Recursive pycliche](docs/README-dev.md#recursive-pycliche)
- [Git principles](docs/README-dev.md#git-principles)
- [Dependency management](docs/README-dev.md#dependency-management)
- [Updating dependencies in the template](docs/README-dev.md#updating-dependencies-in-the-template)
- [Generate project using development version](docs/README-dev.md#generate-project-using-development-version)
- [Style](docs/README-dev.md#style)
- [Test](docs/README-dev.md#test)
- [Tests in GitHub Actions](docs/README-dev.md#tests-in-github-actions)
- [Release](docs/README-dev.md#release)
- [GitHub Personal Access Token](docs/README-dev.md#github-personal-access-token)
- [Record demo](docs/README-dev.md#record-demo)
---
## Acknowledgements
Several tooling choices have been guided by the work of [Adam Johnson](https://adamj.eu/tech/).
The `pycliche` logo is typeset in [Allerta Stencil](https://fonts.google.com/specimen/Allerta+Stencil).
Python icon generated using DALL·E.