Skip to main content

Welcome to python-template-project

A feature-rich Python project template with auto-generated CLI, GUI and parameterized configuration.

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

This template provides a solid foundation for your next Python project, incorporating best practices for testing, automation, and distribution. It streamlines the development process with a comprehensive set of pre-configured tools and workflows, allowing you to focus on writing code.


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 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 Actions tab → Select Rename Action → Run workflow on the main branch.

  5. Wait for the workflow to finish

  6. Clone the repository
    Run:

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

  8. Install dependencies and create virtual environment Run:

    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 Run:

    make fmt
    

    This will auto-format your files and reorder imports (based on any name changes).

  13. Enable pre-commit hooks Run:

    uv run pre-commit install
    
  14. Add repository to ReadTheDocs 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 Run:

    make release
    

Feature overview

  • 📦 Package Management: Utilizes uv, an extremely fast Python package manager, with dependencies managed in pyproject.toml.
  • ✅ Code Formatting and Linting: Pre-commit hook with the RUFF auto-formatter to ensure consistent code style.
  • 🧪 Testing: Unit testing framework with pytest.
  • 📊 Code coverage reports using codecov
  • 🔄 CI/CD: GitHub Actions for automated builds (Windows, macOS), unit tests, and code checks.
  • 💾 Automated Builds: GitHub pipeline for automatically building a Windows executable and a macOS installer.
  • 💬 Parameter-Driven Automation:
    • Automatic generation of a configuration file from parameter definitions.
    • Automatic generation of a Command-Line Interface (CLI) from the same parameters.
    • Automatic generation of CLI API documentation.
    • Automatic generation of change log using gitchangelog to keep a HISTORY.md file up to date.
  • 📃 Documentation: Configuration for publishing documentation on Read the Docs using mkdocs .
  • 🖼️ Minimalist GUI: Comes with a basic GUI based on tkinker that includes an auto-generated settings menu based on your defined parameters.
  • 🖥️ Workflow Automation: A Makefile is included to simplify and automate common development tasks.
  • 🛳️ Release pipeline: Automated releases unsing the Makefile make release command, which creates a new tag and pushes it to the remote repo. The release pipeline will automatically create a new release on GitHub and trigger a release on [PyPI](https://pypi.org.
    • setuptools is used to package the project and manage dependencies.
    • setuptools-scm is used to automatically generate the _version.py file from the pyproject.toml file.

Installation

Get an impression of how your own project could be installed and look like.

Download from PyPI.

💾 For more installation options see install.

pip install python-template-project

Run GUI from command line

python-template-project-gui

Run application from command line using CLI

python -m python_template_project.cli [OPTIONS] path/to/file
python-template-project-cli [OPTIONS] path/to/file

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.2.6

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.2.6
File Size Uploaded Provenance Actions
python_template_project-0.2.6.tar.gz 216.7 kB Without provenance Details for python_template_project-0.2.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-template-project 0.2.6
File Interpreter ABI Platform Actions
python_template_project-0.2.6-py3-none-any.whl Python 3 none any Details for python_template_project-0.2.6-py3-none-any.whl

Total release size: 244.7 kB

Release files / python_template_project-0.2.6.tar.gz

Download URL python_template_project-0.2.6.tar.gz
Size 216.7 kB
Tags Source
SHA-256 checksum
How to use checksums
380c347c73fcea92d0736b1e5fa700d192f8d4f414f06545cb63e4fcbf5e5cab
BLAKE2b-256 checksum
How to use checksums
b733ef3fcb7a85065aa07ac1f6f5f1a9064781879b26c74d15cc937a627bf379
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.2.6-py3-none-any.whl

Download URL python_template_project-0.2.6-py3-none-any.whl
Size 28.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2438308b0a624c6b1eb5a6bbaf8b1987bb3d284dcffce20843b853256b3cb3f2
BLAKE2b-256 checksum
How to use checksums
bf4bdce8c82b135d9234db3ba4dd81426d11e7608f02493b5a9f46d45113f0e3
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.2.6

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