Copier template to scaffold Python projects compliant with best practices and modern tooling.

Scaffolding¶

This Copier template enables you to quickly generate (scaffold) a Python package with fully functioning build and test automation:

Projects generated from this template can be easily updated to benefit from improvements and new features of the template.
During project generation, you can flexibly configure naming of the Python distribution, import package, main author, GitHub repository, organization, and many other aspects to match your specific requirements (see copier.yml for all available options).

Development Infrastructure¶

Projects generated with this template come with a comprehensive development toolchain and quality assurance framework that supports the entire software development lifecycle - from coding and testing to documentation, release management, and compliance auditing. This infrastructure automates routine tasks, enforces code quality standards, and streamlines the path to production:

Linting with Ruff
Static type checking with mypy
Complete set of pre-commit hooks including detect-secrets and pygrep
Unit and E2E testing with pytest including parallel test execution
Matrix testing in multiple environments with nox
Test coverage reported with Codecov and published as release artifact
CI/CD pipeline automated with GitHub Actions with parallel and reusable workflows, including scheduled testing, release automation, and multiple reporting channels and formats
CI/CD pipeline can be run locally with act
Code quality and security checks with SonarQube and GitHub CodeQL
Dependency monitoring and vulnerability scanning with pip-audit, trivy, Renovate, and GitHub Dependabot
Error monitoring and profiling with Sentry (optional)
Logging and metrics with Logfire (optional)
Prepared for uptime monitoring and scheduled tests with betterstack or alternatives
Licenses of dependencies extracted with pip-licenses, matched with allow list, and published as release artifacts in CSV and JSON format for further compliance checks
Generation of attributions from extracted licenses
Software Bill of Materials (SBOM) generated in CycloneDX and SPDX formats with cyclonedx-python resp. trivy, published as release artifacts
Version and release management with bump-my-version
Changelog and release notes generated with git-cliff
Documentation generated with Sphinx including reference documentation for the library, CLI, and API
Documentation published to Read The Docs including generation of PDF and single page HTML versions
Documentation including dynamic badges, setup instructions, contribution guide and security policy
Interactive OpenAPI specification with Swagger
Python package published to PyPI
Multi-stage build of fat (all extras) and slim (no extras) multi-arch (arm64 and amd64) Docker images, running non-root within immutable container
Docker images published to Docker.io and GitHub Container Registry with artifact attestations
One-click development environments with Dev Containers and GitHub Codespaces
Settings for use with VSCode
Settings and custom instructions for use with GitHub Copilot
API deployed as serverless function to Vercel (optional)

Multi-head Application Features¶

Beyond development tooling, projects generated with this template include the code, documentation, and configuration of a fully functioning service and multi-head application. This reference implementation serves as a starting point for your own business logic with modern patterns and enterprise practices already in place:

Usable as library with “Hello” module exposing a simple service that can say “Hello, world!” and echo utterances.
Comfortable command-line interface (CLI) with Typer
Versioned webservice API with FastAPI
Cross-platform Graphical User Interface (GUI) with NiceGUI running in a browser or native window
Interactive Jupyter notebook and reactive Marimo notebook
Simple Web UI with Streamlit
Modular architecture auto-discovers and registers services, CLI commands, API routes and GUI pages exposed by domain modules
Validation and settings management with pydantic
System module providing aggregate health and info to the runtime, compiled settings, and further info provided by domain modules
Health and Info available via command, webservice API (info passsword protected) and GUI
Flexible logging and instrumentation, including support for Sentry and Logfire
Hello service demonstrates use of custom real time metrics collected via Logfire
Configuration to run the CLI and API in a Docker container including setup for Docker Compose

Explore here for what’s generated out of the box. While this template comes with multiple application interfaces (“heads”) - Library, CLI, API, GUI, notebooks, and Streamlit; running native and within Docker - they’re included to demonstrate capabilities and provide implementation patterns. You’re expected to use this as a foundation, keeping only the interfaces relevant to your project’s requirements. The modular architecture makes it easy to:

Remove unnecessary interfaces to simplify your codebase
Adapt existing interfaces to your specific use cases
Focus on your core business logic without reimplementing infrastructure
Add new interfaces while leveraging the existing patterns

Generate a new project¶

To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:

Step 1: Execute the following command to install or update tooling.

# Install Homebrew, uv package manager, copier and further dev tools
curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh

Step 2: Create a repository on GitHub, clone to your local machine, and change into it’s directory.

Step 3: Execute the following command to generate a new project based on this template.

# Ensure to stand in your freshly created git repository before executing this command
copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .

Step 4: Execute the following commands to push your initial commit to GitHub.

git add .
git commit -m "chore: Initial commit"
git push

Check the Actions tab of your GitHub repository: The CI/CD workflow of your project is already running!

The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository. We will configure SonarQube and other services in the next step!

Notes:

Check out this manual on how to set up signed commits

Step 5: Follow the instructions to wire up external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, and Streamlit Community Cloud.

Step 6: Release the first version of your project

make bump

Notes:

You can remove the above sections - from “Scaffolding” to this notes - post having successfully generated your project.
The following sections refer to the dummy application and service generated into the tests and src folder by this template. Use the documentation and code as inspiration, adapt to your business logic, or remove and start documenting and coding from scratch.

Overview¶

Adding OE Python Template to your project as a dependency is easy. See below for usage examples.

uv add oe-python-template             # add dependency to your project

If you don’t have uv installed follow these instructions. If you still prefer pip over the modern and fast package manager uv, you can install the library like this:

pip install oe-python-template        # add dependency to your project

Executing the command line interface (CLI) in an isolated Python environment is just as easy:

uvx oe-python-template hello world               # prints "Hello, world! [..]"
uvx oe-python-template hello echo "Lorem Ipsum"  # echos "Lorem Ipsum"
uvx oe-python-template gui                       # opens the graphical user interface (GUI)
uvx --with "oe-python-template[examples]" oe-python-template gui  # opens the graphical user interface (GUI) with support for scientific computing
uvx oe-python-template system serve              # serves web API
uvx oe-python-template system serve --port=4711  # serves web API on port 4711
uvx oe-python-template system openapi            # serves web API on port 4711

Notes:

The API is versioned, mounted at /api/v1 resp. /api/v2
While serving the web API go to http://127.0.0.1:8000/api/v1/hello-world to see the respons of the hello-world operation.
Interactive documentation is provided at http://127.0.0.1:8000/api/docs

The CLI provides extensive help:

uvx oe-python-template --help                # all CLI commands
uvx oe-python-template hello world --help    # help for specific command
uvx oe-python-template hello echo --help
uvx oe-python-template gui --help
uvx oe-python-template system serve --help
uvx oe-python-template system openapi --help

Operational Excellence¶

This project is designed with operational excellence in mind, using modern Python tooling and practices. It includes:

Various examples demonstrating usage: a. Simple Python script b. Streamlit web application deployed on Streamlit Community Cloud c. Jupyter and Marimo notebook
Complete reference documentation for the library, for the CLI and for the API on Read the Docs
Transparent test coverage including unit and E2E tests (reported on Codecov)
Matrix tested with multiple python versions to ensure compatibility (powered by Nox)
Compliant with modern linting and formatting standards (powered by Ruff)
Up-to-date dependencies (monitored by Renovate and Dependabot)
A-grade code quality in security, maintainability, and reliability with low technical debt and codesmell (verified by SonarQube)
Additional code security checks using CodeQL
Security Policy
License compliant with the Open Source Initiative (OSI)
1-liner for installation and execution of command line interface (CLI) via uv(x) or Docker
Setup for developing inside a devcontainer included (supports VSCode and GitHub Codespaces)

Usage Examples¶

The following examples run from source - clone this repository using git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template.git.

Minimal Python Script:¶

"""Example script demonstrating the usage of the service provided by OE Python Template."""

from rich.console import Console

from oe_python_template.hello import Service

console = Console()

message = Service.get_hello_world()
console.print(f"[blue]{message}[/blue]")

Show script code - Read the reference documentation

Streamlit App¶

Serve the functionality provided by OE Python Template in the web by easily integrating the service into a Streamlit application.

Try it out! - Show the code

… or serve the app locally .. code-block:: shell

uv sync –all-extras # Install streamlit dependency part of the examples extra, see pyproject.toml uv run streamlit run examples/streamlit.py # Serve on localhost:8501, opens browser

Vercel Serverless Function¶

Serve the API as a serverless function on Vercel

Notebooks¶

Jupyter¶

Show the Jupyter code

… or run within VSCode

uv sync --all-extras                                # Install dependencies required for examples such as Juypyter kernel, see pyproject.toml

Install the Jupyter extension for VSCode

Click on examples/notebook.ipynb in VSCode and run it.

Marimo¶

Show the marimo code

Execute the notebook as a WASM based web app

uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
uv run marimo run examples/notebook.py --watch      # Serve on localhost:2718, opens browser

or edit interactively in your browser

uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
uv run marimo edit examples/notebook.py --watch     # Edit on localhost:2718, opens browser

… or edit interactively within VSCode

Install the Marimo extension for VSCode

Click on examples/notebook.py in VSCode and click on the caret next to the Run icon above the code (looks like a pencil) > “Start in marimo editor” (edit).

… or without prior cloning of the repository

uvx marimo run https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/refs/heads/main/examples/notebook.py

Command Line Interface (CLI)¶

Run with uvx ¶

Show available commands:

uvx oe-python-template --help

Execute commands:

uvx oe-python-template hello world
uvx oe-python-template hello echo --help
uvx oe-python-template hello echo "Lorem"
uvx oe-python-template hello echo "Lorem" --json
uvx oe-python-template gui
uvx --with "oe-python-template[examples]" oe-python-template gui  # opens the graphical user interface (GUI) with support for scientific computing
uvx oe-python-template system info
uvx oe-python-template system health
uvx oe-python-template system openapi
uvx oe-python-template system openapi --output-format=json
uvx oe-python-template system serve

See the reference documentation of the CLI for detailed documentation of all CLI commands and options.

Environment¶

The service loads environment variables including support for .env files.

cp .env.example .env              # copy example file
echo "THE_VAR=MY_VALUE" > .env    # overwrite with your values

Now run the usage examples again.

Run with Docker¶

You can as well run the CLI within Docker.

docker run helmuthva/oe-python-template --help
docker run helmuthva/oe-python-template hello world
docker run helmuthva/oe-python-template hello echo --help
docker run helmuthva/oe-python-template hello echo "Lorem"
docker run helmuthva/oe-python-template hello echo "Lorem" --json
docker run helmuthva/oe-python-template system info
docker run helmuthva/oe-python-template system health
docker run helmuthva/oe-python-template system openapi
docker run helmuthva/oe-python-template system openapi --output-format=json
docker run helmuthva/oe-python-template system serve

The default Docker image includes all extras. Additionally a slim image is provided, with no extras. Run as follows

docker run helmuthva/oe-python-template-slim --help
docker run helmuthva/oe-python-template-slim hello world

You can pass environment variables as parameters:

docker run --env OE_PYTHON_TEMPLATE_HELLO_LANGUAGE=de_DE helmuthva/oe-python-template hello world
docker run --env OE_PYTHON_TEMPLATE_HELLO_LANGUAGE=en_US helmuthva/oe-python-template hello world

A docker compose stack is provided. Clone this repository using git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template.git and enter the repository folder.

The .env is passed through from the host to the Docker container.

docker compose run --remove-orphans oe-python-template --help
docker compose run --remove-orphans oe-python-template hello world
docker compose run --remove-orphans oe-python-template hello echo --help
docker compose run --remove-orphans oe-python-template hello echo "Lorem"
docker compose run --remove-orphans oe-python-template hello echo "Lorem" --json
docker compose run --remove-orphans oe-python-template system info
docker compose run --remove-orphans oe-python-template system health
docker compose run --remove-orphans oe-python-template system openapi
docker compose run --remove-orphans oe-python-template system openapi --output-format=json
echo "Running OE Python Template's API container as a daemon ..."
docker compose up -d
echo "Waiting for the API server to start ..."
sleep 5
echo "Checking health of v1 API ..."
curl http://127.0.0.1:8000/api/v1/healthz
echo ""
echo "Saying hello world with v1 API ..."
curl http://127.0.0.1:8000/api/v1/hello/world
echo ""
echo "Swagger docs of v1 API ..."
curl http://127.0.0.1:8000/api/v1/docs
echo ""
echo "Checking health of v2 API ..."
curl http://127.0.0.1:8000/api/v2/healthz
echo ""
echo "Saying hello world with v1 API ..."
curl http://127.0.0.1:8000/api/v2/hello/world
echo ""
echo "Swagger docs of v2 API ..."
curl http://127.0.0.1:8000/api/v2/docs
echo ""
echo "Shutting down the API container ..."
docker compose down

See the reference documentation of the API for detailed documentation of all API operations and parameters.

Extra: Lorem Ipsum¶

Dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam.

Scaffolding¶

Development Infrastructure¶

Multi-head Application Features¶

Generate a new project¶

Overview¶

Operational Excellence¶

Usage Examples¶

Minimal Python Script:¶

Streamlit App¶

Vercel Serverless Function¶

Notebooks¶

Jupyter¶

Marimo¶

Command Line Interface (CLI)¶

Run with uvx¶

Environment¶

Run with Docker¶

Extra: Lorem Ipsum¶

Run with uvx ¶