Skip to main content

Welcome to python-template-project

A slim, local-first Python project template with a browser-based image exporter.

Github CI Status GitHub release Read the Docs License GitHub issues PyPI Downloads

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.


  1. Create a new repository using GitHub template Click on Use this template.

  2. 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.)

  3. Set write permissions Go to: Repository -> Settings -> Actions -> General -> Workflow permissions Select: Read and write permissions, then click Save.

  4. Trigger rename workflow Navigate to the Actions tab, select Rename Action and run the workflow on the main branch.

  5. Wait for the workflow to finish

  6. Clone the repository

    git clone [your-github-url]
    
  7. Open the project in your IDE

  8. Install dependencies and create virtual environment

    make install
    
  9. Configure your IDE Set .venv as the local Python virtual environment.

  10. Adjust project metadata Modify pyproject.toml (e.g., project description, authors, license, etc.)

  11. Clean up template scripts Delete the files:

    • rename_project.yml
    • rename_project.sh
  12. Format your codebase

    make fmt
    
  13. Enable pre-commit hooks

    uv run pre-commit install
    
  14. Add repository to Read the Docs Visit: https://app.readthedocs.org/dashboard/import/

  15. 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.
  16. 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 argparse CLI with gui, export and config subcommands.
    • CLI and configuration documentation generated from the live parser and config definitions.
    • Automatic change log using gitchangelog to keep a HISTORY.md file 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 Makefile simplifies and automates common development tasks.
  • Agentic Workflows: Context-sparing OpenCode workflows (task, feature, autopilot, mission planning) — see docs/workflows.md.
  • Release pipeline: make release validates the tag, creates it and pushes it. The release workflow then creates a GitHub release and publishes to PyPI.
    • setuptools is used to package the project and manage dependencies.
    • setuptools-scm automatically generates _version.py from 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)

Source distribution for python-template-project 0.3.0
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)

Table of built distributions (wheels) for python-template-project 0.3.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page