Example project scaffolded and kept up to date with OE Python Template (oe-python-template).

Overview¶

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

uv add oe-python-template-example             # 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-example        # add dependency to your project

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

uvx oe-python-template-example hello world               # prints "Hello, world! [..]"
uvx oe-python-template-example hello echo "Lorem Ipsum"  # echos "Lorem Ipsum"
uvx oe-python-template-example gui                       # opens the graphical user interface (GUI)
uvx --with "oe-python-template-example[examples]" oe-python-template-example gui  # opens the graphical user interface (GUI) with support for scientific computing
uvx oe-python-template-example system serve              # serves web API
uvx oe-python-template-example system serve --port=4711  # serves web API on port 4711
uvx oe-python-template-example 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-example --help                # all CLI commands
uvx oe-python-template-example hello world --help    # help for specific command
uvx oe-python-template-example hello echo --help
uvx oe-python-template-example gui --help
uvx oe-python-template-example system serve --help
uvx oe-python-template-example 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-example.git.

Minimal Python Script:¶

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

from rich.console import Console

from oe_python_template_example.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 Example in the web by easily integrating the service into a Streamlit application.

Try it out! - Show the code

… or serve the app locally

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-example/refs/heads/main/examples/notebook.py

Command Line Interface (CLI)¶

Run with uvx ¶

Show available commands:

uvx oe-python-template-example --help

Execute commands:

uvx oe-python-template-example hello world
uvx oe-python-template-example hello echo --help
uvx oe-python-template-example hello echo "Lorem"
uvx oe-python-template-example hello echo "Lorem" --json
uvx oe-python-template-example gui
uvx --with "oe-python-template-example[examples]" oe-python-template-example gui  # opens the graphical user interface (GUI) with support for scientific computing
uvx oe-python-template-example system info
uvx oe-python-template-example system health
uvx oe-python-template-example system openapi
uvx oe-python-template-example system openapi --output-format=json
uvx oe-python-template-example 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-example --help
docker run helmuthva/oe-python-template-example hello world
docker run helmuthva/oe-python-template-example hello echo --help
docker run helmuthva/oe-python-template-example hello echo "Lorem"
docker run helmuthva/oe-python-template-example hello echo "Lorem" --json
docker run helmuthva/oe-python-template-example system info
docker run helmuthva/oe-python-template-example system health
docker run helmuthva/oe-python-template-example system openapi
docker run helmuthva/oe-python-template-example system openapi --output-format=json
docker run helmuthva/oe-python-template-example 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-example-slim --help
docker run helmuthva/oe-python-template-example-slim hello world

You can pass environment variables as parameters:

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

A docker compose stack is provided. Clone this repository using git clone git@github.com:helmut-hoffer-von-ankershoffen/oe-python-template-example.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-example --help
docker compose run --remove-orphans oe-python-template-example hello world
docker compose run --remove-orphans oe-python-template-example hello echo --help
docker compose run --remove-orphans oe-python-template-example hello echo "Lorem"
docker compose run --remove-orphans oe-python-template-example hello echo "Lorem" --json
docker compose run --remove-orphans oe-python-template-example system info
docker compose run --remove-orphans oe-python-template-example system health
docker compose run --remove-orphans oe-python-template-example system openapi
docker compose run --remove-orphans oe-python-template-example system openapi --output-format=json
echo "Running OE Python Template Example'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¶

Nothing yet