A small, typed Python package and CLI template for starting a library or command-line application without assembling a toolchain from scratch. Typer handles the CLI, Pydantic Settings validates configuration, and uv manages the locked environment. Containers, notebooks, and deployment are optional.
Start with Python 3.12+, uv 0.12.19, and GNU Make. Python 3.13 is the full CI baseline; compatibility tests also cover 3.12 and 3.14. See the uv installation guide if uv is not installed. Docker, actionlint, and deployment credentials are not needed to run the example or unit tests.
From a terminal:
git clone https://github.com/ks6088ts/template-python.git
cd template-python
make install-deps-dev
uv run --locked template-python hello --name AdaExpected output:
Hello, Ada!
Then run make test. No virtual environment activation or .env file is
required. The equivalent module entry point is
uv run --locked python -m template_python hello --name Ada.
Read only the guide needed for the change:
| I want to... | Start here |
|---|---|
| Change behavior, run checks, or resolve a setup failure | Development guide |
| Decide where code belongs or whether to add an abstraction | Architecture and engineering guide |
| Configure the CLI | Configuration reference |
| Turn this template into a new project | Template adoption checklist |
| Preview or edit documentation | Documentation workflow |
CLI (settings + logging) -> reusable core behavior
| Location | Responsibility |
|---|---|
| core.py | Deterministic behavior, independent of CLI and environment |
| cli.py | Commands, user-facing errors, and application setup |
| settings.py, logging.py | Configuration validation and logging setup |
| tests/ | Behavior and CLI contract tests |
| Makefile | Supported local and CI commands; run make help to list them |
| pyproject.toml, uv.lock | Dependencies, tool configuration, and resolved versions |
| docs/ | Task-oriented guides in English and Japanese |
| Changed area | Check |
|---|---|
| Python, dependencies, or workflows | make ci-test |
| Documentation | make ci-test-docs |
| Container assets | make ci-test-docker |
The Python gate requires actionlint
on PATH. The container gate requires a running Docker daemon. If a change spans
areas, run each corresponding check. See the
development guide for focused checks
and Git hooks.
Use these only when your project needs them:
| Asset | Entry point |
|---|---|
| Container example | make docker-build docker-run or docker compose up --build |
| Documentation site | make docs-serve |
| Notebook example | make jupyterlab |
| VS Code Dev Container | .devcontainer/ |
| Image publishing and site deployment | .github/workflows/ |
No registry or cloud account is needed for local development. Remove unused assets and their related dependencies, Make targets, workflows, and links together; follow the adoption checklist.
Tags matching v* publish images to Docker Hub and GHCR only after checking that
the tag matches the package version. This template does not publish to PyPI.
See delivery rules before enabling releases.
MIT.