Welcome to python-template-project

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

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