Initial commit
This commit is contained in:
commit
24f61314a1
19 files changed
+2087
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# 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 |
|
||||
Reference in new issue
Block a user