template
Template repository for a Python project. It uses:
- uv to manage Python, the virtual environment and dependencies
pyproject.tomlfor the package metadata (built with hatchling)- pytest for the tests
- ruff for linting and formatting
- MkDocs with Material and mkdocstrings for the documentation
Layout
├── pyproject.toml # package metadata, dependencies and tool configuration
├── mkdocs.yml # documentation configuration
├── src/sample/ # the package (rename it, see below)
├── tests/ # pytest tests
├── docs/ # documentation pages (Markdown)
└── tools/ # standalone scripts with their own inline dependencies
Bootstrap the project
1. Install uv
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
You do not need to install Python yourself: uv downloads a matching interpreter if none is available.
2. Create the environment
uv sync
This creates .venv/, installs the package in editable mode with its runtime
dependencies, plus the dev (pytest, ruff) and docs (MkDocs) dependency groups. It
also writes uv.lock; commit it so everyone gets the same versions.
There is no need to activate the environment: prefix commands with uv run.
3. Everyday commands
| Task | Command |
|---|---|
| Run the tests | uv run pytest |
| Lint (and auto-fix) | uv run ruff check --fix |
| Format the code | uv run ruff format |
| Run the package entry point | uv run sample Alice |
| Serve the docs with live reload | uv run mkdocs serve |
Build the docs into site/ |
uv run mkdocs build |
| Build a wheel and sdist | uv build |
| Add a runtime dependency | uv add requests |
| Add a dev-only dependency | uv add --dev mypy |
| Upgrade the locked versions | uv lock --upgrade |
| Bump the version (patch/minor/major) | uv version --bump minor |
| Remove all generated files | git clean -fdX |
git clean -fdX deletes everything listed in .gitignore, including .venv;
run uv sync afterwards to recreate it.
Starting a new project from this template
- Rename the
src/sample/folder to your package name. - In
pyproject.toml, updatename,version,description,authors, the[project.scripts]entry and the path under[tool.hatch.build.targets.wheel]. - In
src/<package>/__init__.py, change the name passed toversion(). - In
mkdocs.yml, setsite_name, and indocs/reference.mdpoint the::: sample.helpersdirectives at your modules. - Fix the imports in
tests/, then runuv syncanduv run pytest. - Check the year in
LICENSE. The template is proprietary (all rights reserved); for an open-source project, replaceLICENSEand set the matching SPDX identifier in thelicensefield ofpyproject.toml.
The version is defined only in pyproject.toml; the package reads it back at
runtime with importlib.metadata, so sample.__version__ always matches.
The package lives under src/ so that tests run against the installed package,
not against the folder on disk: a file missing from the wheel fails the tests
instead of going unnoticed.
The Private :: Do Not Upload classifier makes PyPI reject the package if it is
ever published there by mistake.
Tools
tools/ holds standalone scripts that are not part of the package. Each one
declares its own Python version and dependencies in an inline metadata header
(PEP 723):
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "pandas",
# "rich",
# ]
# ///
uv reads that header and runs the script in its own cached environment, so the
dependencies never touch the project's .venv:
uv run tools/csv_summary.py data.csv
# or, thanks to the shebang (Linux / macOS):
./tools/csv_summary.py data.csv
To create a new tool, run uv init --script tools/my_tool.py and add its
dependencies with uv add --script tools/my_tool.py <package>.
Documentation
Pages live in docs/ as Markdown. API reference is generated from the
docstrings with mkdocstrings (::: module.path in a page). Docstrings use the
Sphinx :param: style; change docstring_style in mkdocs.yml to google or
numpy if you prefer.
Dev container
.devcontainer/ defines a VS Code dev container with Python 3.12 and uv. On
creation it runs uv sync, and it installs the Python and Ruff extensions.
.vscode/settings.json points VS Code at .venv and formats on save with ruff.
Continuous integration
Two Gitea workflows live in .gitea/workflows/:
tests.yamlruns on every push and pull request:uv sync --locked(fails ifuv.lockis out of date withpyproject.toml),ruff check,ruff format --checkandpytest.build_docs.yamlruns on pushes tomain: it builds the site and publishes it to the documentation server with rsync, into a folder named after the repository.
The documentation server is configured outside the repository, at the organisation (or repository) level under Settings → Actions:
| Kind | Name | Example |
|---|---|---|
| Variable | DOCS_HOST |
10.0.1.184 |
| Variable | DOCS_PORT |
32760 |
| Variable | DOCS_USER |
data |
| Secret | DEPLOY_DOCS_KEY |
SSH private key |