Files
DiscScanner/README.md
T

154 lines
5.9 KiB
Markdown
Raw Normal View History

2026-10-22 08:45:37 +02:00
# 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 |