2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00
2026-10-22 08:45:37 +02:00

template

Template repository for a Python project. It uses:

  • uv to manage Python, the virtual environment and dependencies
  • pyproject.toml for 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

  1. Rename the src/sample/ folder to your package name.
  2. In pyproject.toml, update name, version, description, authors, the [project.scripts] entry and the path under [tool.hatch.build.targets.wheel].
  3. In src/<package>/__init__.py, change the name passed to version().
  4. In mkdocs.yml, set site_name, and in docs/reference.md point the ::: sample.helpers directives at your modules.
  5. Fix the imports in tests/, then run uv sync and uv run pytest.
  6. Check the year in LICENSE. The template is proprietary (all rights reserved); for an open-source project, replace LICENSE and set the matching SPDX identifier in the license field of pyproject.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.yaml runs on every push and pull request: uv sync --locked (fails if uv.lock is out of date with pyproject.toml), ruff check, ruff format --check and pytest.
  • build_docs.yaml runs on pushes to main: 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
S
Description
Scanner rotatif
Readme
131 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 100%