Welcome to python-template-project
A slim, local-first Python project template with a browser-based image exporter.
This template provides a solid foundation for your next Python project. It keeps a battle-tested tooling setup (uv, Ruff, pytest, mkdocs, PyInstaller, tag-based releases) while staying small: the only runtime dependencies are PyYAML and Pillow.
How to use this template
Getting started on developing your own project based on this template.
DO NOT FORK This project is meant to be used from the Use this template feature.
-
Create a new repository using GitHub template Click on Use this template.
-
Give a name to your project For example:
my-python-project(Hyphens may be used as project name; they are converted during renaming internally to underscores for packages.) -
Set write permissions Go to:
Repository -> Settings -> Actions -> General -> Workflow permissionsSelect:Read and write permissions, then click Save. -
Trigger rename workflow Navigate to the
Actionstab, select Rename Action and run the workflow on themainbranch. -
Wait for the workflow to finish
-
Clone the repository
git clone [your-github-url]
-
Open the project in your IDE
-
Install dependencies and create virtual environment
make install -
Configure your IDE Set
.venvas the local Python virtual environment. -
Adjust project metadata Modify
pyproject.toml(e.g., project description, authors, license, etc.) -
Clean up template scripts Delete the files:
rename_project.ymlrename_project.sh
-
Format your codebase
make fmt -
Enable pre-commit hooks
uv run pre-commit install
-
Add repository to Read the Docs Visit: https://app.readthedocs.org/dashboard/import/
-
Configure PyPI publishing
- Generate a PyPI API token from your PyPI account.
- Go to GitHub -> Settings -> Secrets and variables -> Actions.
- Add the secret as
PYPI_API_TOKEN.
-
Release your first version
make release
Feature overview
- Package Management: Uses uv, an extremely fast Python package manager, with dependencies managed in
pyproject.toml. - Code Formatting and Linting: Ruff auto-formatter and linter for consistent code style.
- Testing: Unit testing framework with pytest.
- Code coverage reports using coverage.py.
- CI/CD: GitHub Actions Linux checks on every push and pull request.
- Automated Builds: GitHub pipeline for a single-file Linux executable with PyInstaller.
- Parameter-Driven Automation:
- A self-contained configuration layer (no external config framework).
- A stdlib
argparseCLI withgui,exportandconfigsubcommands. - CLI and configuration documentation generated from the live parser and config definitions.
- Automatic change log using gitchangelog to keep a
HISTORY.mdfile up to date.
- Documentation: Publishing on Read the Docs using mkdocs.
- Local Web UI: A lightweight, local-first browser UI served by the standard library
http.server, using Pillow for thumbnails and export. No native desktop GUI and no client framework. - Workflow Automation: A
Makefilesimplifies and automates common development tasks. - Agentic Workflows: Context-sparing OpenCode workflows (task, feature, autopilot, mission planning) — see docs/workflows.md.
- Release pipeline:
make releasevalidates the tag, creates it and pushes it. Thereleaseworkflow then creates a GitHub release and publishes to PyPI.- setuptools is used to package the project and manage dependencies.
- setuptools-scm automatically generates
_version.pyfrom the Git tag.
Installation
Get an impression of how your own project could be installed and used.
Download from PyPI.
For more installation options see install.
pip install python-template-project
Open the web UI (also the default when the installed command is run without arguments):
python-template-project
Run the CLI directly:
python-template-project export --source ./photos --output ~/Pictures --format jpg
python-template-project config --show
From a source checkout the module equivalents are:
python -m python_template_project --help
python -m python_template_project export --source ./photos
Troubleshooting
Problems with release pipeline
If you get this error below:
/home/runner/work/_temp/xxxx_xxx.sh: line 1: .github/release_message.sh: Permission denied
You have to run these commands in your IDE Terminal or the git bash and then push the changes.
git update-index --chmod=+x ./.github/release_message.sh
Metadata
Release files for python-template-project 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| python_template_project-0.3.0.tar.gz | 1.1 MB | Without provenance | Details for python_template_project-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_template_project-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for python_template_project-0.3.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / python_template_project-0.3.0.tar.gz
| Download URL | python_template_project-0.3.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29334d41095d2edbf7db4415ff0eaaf20695ce8eed3ee4d3264b5d74d1b253c4
|
|
BLAKE2b-256 checksum How to use checksums |
ec6ba7ee7d68239ae72ff6486473a113abb488b2d2d76de3ee35c324a0aae272
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / python_template_project-0.3.0-py3-none-any.whl
| Download URL | python_template_project-0.3.0-py3-none-any.whl |
|---|---|
| Size | 28.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
94b216f11001f905865e225c8f094892368ee33c85023f9dd276c81050655556
|
|
BLAKE2b-256 checksum How to use checksums |
26894390e500ce8d3c852fdfd5e818d2b7673fcbc36e9e8602cccef476943882
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for python-template-project 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.