# template Template repository for a Python project. It uses: - [uv](https://docs.astral.sh/uv/) to manage Python, the virtual environment and dependencies - `pyproject.toml` for the package metadata (built with [hatchling](https://hatch.pypa.io/)) - [pytest](https://docs.pytest.org/) for the tests - [ruff](https://docs.astral.sh/ruff/) for linting and formatting - [MkDocs](https://www.mkdocs.org/) with [Material](https://squidfunk.github.io/mkdocs-material/) and [mkdocstrings](https://mkdocstrings.github.io/) 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 ```sh # 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 ```sh 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//__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](https://peps.python.org/pep-0723/)): ```python #!/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`: ```sh 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 `. ## 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 |