155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# 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/<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](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 <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 |
|