Migrate the backend from pip to uv
CI / Build and push docker image (push) Successful in 2m42s

Replace requirements.txt with a uv workspace and lockfile, install the five tavolo packages from packages/* in development and non-editable in the image, and build the Docker image with uv. Move dev tools to a PEP 735 dependency group and refresh the locked dependency versions.
This commit is contained in:
2026-10-20 07:25:25 +08:00
parent 03a571a6a5
commit 2d5c64218f
15 changed files with 1975 additions and 252 deletions
+5 -5
View File
@@ -7,11 +7,11 @@
.env.example
**/.venv/
**/__pycache__/
*.pyc
*.pyo
*.egg-info/
.mypy_cache/
.pytest_cache/
**/*.pyc
**/*.pyo
**/*.egg-info/
**/.mypy_cache/
**/.pytest_cache/
web/target/
web/dist/
server/tests/
+12 -10
View File
@@ -110,20 +110,22 @@ live-play websocket lives.
## Development
Backend (from `server/`):
Backend (from `server/`), using [uv](https://docs.astral.sh/uv/):
```sh
cd server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
.venv/bin/python -m unittest discover -s tests -t .
.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
uv sync --package tavolo-app --extra otel
uv run python -m unittest discover -s tests -t .
uv run python -m unittest discover -s packages/tavolo-platform/tests
uv run python -m unittest discover -s packages/tavolo-scopone/tests
uv run python -m unittest discover -s packages/tavolo-scopa/tests
uv run python -m unittest discover -s packages/tavolo-briscola/tests
```
The `otel` extra is optional; without it the telemetry integration tests
skip. Development tools (`mypy`, `httpx-ws`) are installed by default from
the workspace's `dev` dependency group.
Frontend (from `web/`), with the backend running on :8080:
```sh
@@ -142,7 +144,7 @@ OIDC_0_CLIENT_ID=tavolo \
OIDC_0_REDIRECT_URI=http://localhost:8080/auth/default/callback \
OIDC_0_POST_LOGIN_REDIRECT=http://localhost:8000/ \
OIDC_0_POST_LOGOUT_REDIRECT=http://localhost:8000/ \
.venv/bin/granian --host 127.0.0.1 --port 8080 tavolo.app:app
uv run granian --host 127.0.0.1 --port 8080 tavolo.app:app
```
Card images are committed under `web/assets/cards/`; `web/fetch-cards.sh`
+1 -1
View File
@@ -128,7 +128,7 @@ services:
# (HTTP/WebSocket, Postgres, Redis), metrics and logs via OTLP/HTTP,
# disabled unless OTEL_ENABLED is set.
# The image bundles the otel extra (see packages/tavolo-app/pyproject.toml
# and server/requirements.txt).
# and server/uv.lock).
OTEL_ENABLED: ${OTEL_ENABLED:-}
OTEL_SERVICE_NAME: ${OTEL_SERVICE_NAME:-}
OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-}
+1
View File
@@ -0,0 +1 @@
3.14
+32 -18
View File
@@ -7,7 +7,7 @@
# builder alpine python -> python venv with the backend + deps
# runtime alpine python + the venv + the compiled frontend
#
# apk and pip both use BuildKit cache mounts (type=cache): the package
# apk and uv both use BuildKit cache mounts (type=cache): the package
# caches persist in the builder's cache across builds instead of being
# re-downloaded, and never land in the image layers.
@@ -49,29 +49,43 @@ RUN --mount=type=cache,target=/usr/local/cargo/registry \
# --- Python builder ----------------------------------------------------------
FROM alpine:3.24 AS builder
# The official uv image ships a statically linked musl binary, so it works
# on Alpine. Pin the version so image builds do not change implicitly.
COPY --from=ghcr.io/astral-sh/uv:0.13.1 /uv /uvx /bin/
RUN --mount=type=cache,target=/var/cache/apk \
apk add python3 py3-pip build-base python3-dev
apk add python3 build-base python3-dev
# Use Alpine's Python instead of downloading a managed interpreter, install
# the venv at the same path the runtime stage uses, and copy rather than
# hardlink from the cache mount (cache and target are different filesystems).
ENV UV_PYTHON_DOWNLOADS=0 \
UV_PROJECT_ENVIRONMENT=/opt/venv \
UV_LINK_MODE=copy
WORKDIR /build
# uv needs the workspace root plus the member pyprojects to know which
# package to sync. Copying only the manifests lets the third-party
# dependency layer stay cached while application sources change.
# server/pyproject.toml also carries [tool.aerich], read by the db-migrate
# compose service with working_dir=/app, next to ./migrations.
COPY server/uv.lock server/pyproject.toml ./
COPY server/packages/tavolo-platform/pyproject.toml packages/tavolo-platform/
COPY server/packages/tavolo-scopone/pyproject.toml packages/tavolo-scopone/
COPY server/packages/tavolo-scopa/pyproject.toml packages/tavolo-scopa/
COPY server/packages/tavolo-briscola/pyproject.toml packages/tavolo-briscola/
COPY server/packages/tavolo-app/pyproject.toml packages/tavolo-app/
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --frozen --no-install-workspace --package tavolo-app --extra otel --no-dev
COPY server/requirements.txt ./
RUN --mount=type=cache,target=/root/.cache/pip \
python3 -m venv /opt/venv \
&& /opt/venv/bin/pip install --upgrade pip \
&& /opt/venv/bin/pip install -r requirements.txt
# The five sibling distributions, installed from the local tree (PEP 420
# namespace packages sharing the `tavolo` namespace). --no-deps: every
# third-party dependency — including the tavolo-app `otel` extra — is
# already pinned in requirements.txt.
# The five sibling distributions are workspace members (PEP 420 namespace
# packages sharing the `tavolo` namespace). --no-editable installs them as
# wheels, so the runtime image does not need their source tree.
COPY server/packages/ ./packages/
RUN --mount=type=cache,target=/root/.cache/pip \
/opt/venv/bin/pip install --no-deps ./packages/tavolo-platform ./packages/tavolo-scopone ./packages/tavolo-scopa ./packages/tavolo-briscola ./packages/tavolo-app
# server/pyproject.toml only carries the [tool.aerich] section (the
# db-migrate compose service runs `aerich upgrade` with working_dir=/app,
# next to ./migrations).
COPY server/pyproject.toml ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-editable --package tavolo-app --extra otel --no-dev
# aerich migration files are a release artifact: the db-migrate compose
# service runs `aerich upgrade` from this image before the app starts.
COPY server/migrations/ ./migrations/
+27 -17
View File
@@ -99,7 +99,7 @@ All configuration comes from environment variables (see `.env.example`):
| `CORS_ALLOW_CREDENTIALS` | `false` | `1`/`true`/`yes`/`on` allow cookies/credentials on cross-origin requests |
| `CORS_EXPOSE_HEADERS` | unset | Comma-separated response headers exposed to the browser |
| `CORS_MAX_AGE` | `600` | Seconds browsers may cache the preflight response |
| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces, metrics and logs (the Docker image bundles the `otel` extra; non-image installs need `pip install tavolo-app[otel]`) |
| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces, metrics and logs (the Docker image bundles the `otel` extra; non-image installs need `uv sync --package tavolo-app --extra otel`) |
| `OTEL_SERVICE_NAME` | `tavolo` | `service.name` resource attribute of the exported telemetry |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Base URL of an OTLP/HTTP collector (e.g. `http://localhost:4318`); unset uses the exporter default |
| `OTEL_EXPORTER_OTLP_HEADERS` | unset | Comma-separated `key=value` headers sent to the collector (e.g. authentication) |
@@ -276,7 +276,7 @@ rebuild every rating and aggregate from the recorded match history (e.g.
to backfill matches recorded before ratings existed):
```sh
.venv/bin/python -m tavolo.platform.backfill_elo \
uv run python -m tavolo.platform.backfill_elo \
--database-url postgres://tavolo:tavolo@localhost:5432/tavolo
```
@@ -511,24 +511,33 @@ rejected with an `illegal_move` error.
## Development
The backend is a [uv](https://docs.astral.sh/uv/) workspace: `pyproject.toml`
declares the five packages under `packages/` as members, and `uv.lock` pins
their full dependency closure. The checked-in `.python-version` selects
Python 3.14, matching the Docker image. Install uv, then from `server/`:
```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
uv sync --package tavolo-app --extra otel
# app integration suite:
.venv/bin/python -m unittest discover -s tests -t .
uv run python -m unittest discover -s tests -t .
# per-package suites (each package is self-contained):
.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
uv run python -m unittest discover -s packages/tavolo-platform/tests
uv run python -m unittest discover -s packages/tavolo-scopone/tests
uv run python -m unittest discover -s packages/tavolo-scopa/tests
uv run python -m unittest discover -s packages/tavolo-briscola/tests
# type checks (see packages/tavolo-app/README.md for the app modules):
.venv/bin/python -m mypy -p tavolo.platform
.venv/bin/python -m mypy -p tavolo.scopone
.venv/bin/python -m mypy -p tavolo.scopa
.venv/bin/python -m mypy -p tavolo.briscola
uv run mypy -p tavolo.platform
uv run mypy -p tavolo.scopone
uv run mypy -p tavolo.scopa
uv run mypy -p tavolo.briscola
```
`uv sync` installs the workspace's `dev` dependency group (`mypy`,
`httpx-ws`) automatically; pass `--no-dev` for a runtime-only environment.
The `otel` extra is optional, but without it the telemetry integration tests
skip. The lockfile is committed: use `uv lock --upgrade` (or
`uv lock --upgrade-package <name>`) to update dependencies deliberately.
Tests run fully in-process: in-memory sqlite for Postgres, in-memory stores
for Redis, a fake OIDC user patched onto the mixins, and `httpx` /
`httpx-ws` ASGI transports for HTTP and WebSocket coverage. The platform
@@ -543,8 +552,8 @@ To add a migration after changing
`packages/tavolo-platform/src/tavolo/platform/models.py`:
```sh
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich migrate
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich upgrade
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo uv run aerich migrate
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo uv run aerich upgrade
```
(`aerich init-db` produces sqlite-flavored DDL when pointed at sqlite;
@@ -605,7 +614,8 @@ packages/tavolo-app/ # deployable app: composition root (own pyproject)
├── aerich_config.py # aerich CLI configuration
├── logging_config.py # logging setup
└── static.py # SPA shell hosting
pyproject.toml # tooling shim: [tool.aerich] + [tool.mypy] for server/ CWD
pyproject.toml # uv workspace root + [tool.aerich] / [tool.mypy]
uv.lock # locked dependency set for the whole workspace
migrations/ # aerich migrations for the platform models
tests/ # app integration suite (platform + games wired together)
```
+1 -1
View File
@@ -29,7 +29,7 @@ The deployable tavolo application: the composition root wiring
## Development (from `packages/tavolo-app/`)
```sh
.venv/bin/python -m mypy --namespace-packages --explicit-package-bases \
uv run mypy --namespace-packages --explicit-package-bases \
src/tavolo/app.py \
src/tavolo/config.py \
src/tavolo/telemetry.py \
+6 -4
View File
@@ -31,10 +31,6 @@ dependencies = [
]
[project.optional-dependencies]
dev = [
"mypy",
"httpx-ws",
]
otel = [
"kaya-otel>=0.0.7",
"opentelemetry-instrumentation-asyncpg>=0.66b0",
@@ -42,6 +38,12 @@ otel = [
"opentelemetry-instrumentation-system-metrics>=0.66b0",
]
[dependency-groups]
dev = [
"mypy",
"httpx-ws",
]
[tool.setuptools.packages.find]
where = ["src"]
namespaces = true
+2 -2
View File
@@ -92,8 +92,8 @@ the match), so the hand-ack timeout is accepted but unused.
## Development (from `server/`)
```sh
.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
.venv/bin/python -m mypy -p tavolo.briscola
uv run python -m unittest discover -s packages/tavolo-briscola/tests
uv run mypy -p tavolo.briscola
```
`test_engine.py`/`test_plugin.py` cover the two classic variants;
+2 -2
View File
@@ -58,8 +58,8 @@ examples are [`tavolo-scopone`](../tavolo-scopone/README.md),
## Development (from `server/`)
```sh
.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
.venv/bin/python -m mypy -p tavolo.platform
uv run python -m unittest discover -s packages/tavolo-platform/tests
uv run mypy -p tavolo.platform
```
Tests run fully in-process against a `DummyEngine` (a two-player toy game
+2 -2
View File
@@ -36,8 +36,8 @@ application composition root.
## Development (from `server/`)
```sh
.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
.venv/bin/python -m mypy -p tavolo.scopa
uv run python -m unittest discover -s packages/tavolo-scopa/tests
uv run mypy -p tavolo.scopa
```
`test_engine.py` covers the pure rules; `test_plugin.py` covers the
+2 -2
View File
@@ -31,8 +31,8 @@ application composition root.
## Development (from `server/`)
```sh
.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
.venv/bin/python -m mypy -p tavolo.scopone
uv run python -m unittest discover -s packages/tavolo-scopone/tests
uv run mypy -p tavolo.scopone
```
`test_engine.py` covers the pure rules; `test_plugin.py` covers the
+30 -4
View File
@@ -1,11 +1,37 @@
# NOTE: the tavolo-app distribution lives in packages/tavolo-app/ (same
# kaya-style layout as tavolo-platform and tavolo-scopone). This file
# exists only for tooling that reads configuration from the working
# directory:
# NOTE: the five tavolo distributions live in packages/ (same kaya-style
# layout as tavolo-platform and tavolo-scopone). This file is the root of
# the uv workspace and also holds tooling configuration that is read from
# the working directory:
# - uv locks and syncs the whole workspace from here;
# - aerich reads [tool.aerich] from here (server/ locally, /app in the
# db-migrate compose service), next to ./migrations;
# - mypy reads [tool.mypy] from here when run from server/.
# See the Migrations section in README.md.
[tool.uv]
# The old pip-compile setup used --index-url for the private Gitea index
# plus --extra-index-url for PyPI, so the best version across both indexes
# won. Match that behavior with uv.
index-strategy = "unsafe-best-match"
[[tool.uv.index]]
name = "gitea"
url = "https://gitea.woggioni.net/api/packages/woggioni/pypi/simple"
default = true
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
[tool.uv.workspace]
members = ["packages/*"]
[tool.uv.sources]
tavolo-platform = { workspace = true }
tavolo-scopone = { workspace = true }
tavolo-scopa = { workspace = true }
tavolo-briscola = { workspace = true }
[tool.aerich]
tortoise_orm = "tavolo.aerich_config.TORTOISE_ORM"
location = "./migrations"
-184
View File
@@ -1,184 +0,0 @@
#
# This file is autogenerated by pip-compile with Python 3.14
# by the following command (run from server/packages/tavolo-app/):
#
# pip-compile --allow-unsafe --extra otel --extra-index-url=https://pypi.org/simple --index-url=https://gitea.woggioni.net/api/packages/woggioni/pypi/simple --output-file=../../requirements.txt pyproject.toml
#
# NOTE: the tavolo-platform, tavolo-scopone, tavolo-scopa, tavolo-briscola
# and tavolo-app sibling packages are NOT pinned here: they are installed
# from ./packages in
# the Dockerfile and in development (pip install -e ./packages/tavolo-platform
# -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa
# -e ./packages/tavolo-briscola
# -e ./packages/tavolo-app). All of their
# third-party dependencies are direct dependencies of tavolo-app, so this
# lock covers the full closure. The otel extra (kaya-otel and its
# OpenTelemetry dependencies) IS included, so OTEL_ENABLED works in the
# Docker image; pip-compile cannot resolve the unpublishable sibling
# packages, so regeneration drops them from a copy of the input file (the
# existing pins constrain the rest).
#
--index-url https://gitea.woggioni.net/api/packages/woggioni/pypi/simple
--extra-index-url https://pypi.org/simple
aerich==0.10.1
# via tavolo-app (pyproject.toml)
aiosqlite==0.22.1
# via tortoise-orm
anyio==4.15.1
# via
# aerich
# httpx
# tortoise-orm
asyncclick==8.4.2.1
# via aerich
asyncpg==0.31.0
# via tavolo-app (pyproject.toml)
certifi==2026.7.22
# via
# httpcore
# httpx
cffi==2.1.1
# via cryptography
click==8.5.0
# via granian
cryptography==50.0.1
# via pyjwt
dictdiffer==0.10.0
# via aerich
googleapis-common-protos==1.75.4
# via opentelemetry-exporter-otlp-proto-http
granian==2.8.3
# via
# kaya-rsgi
# tavolo-app (pyproject.toml)
h11==0.16.0
# via httpcore
httpcore==1.0.9
# via httpx
httpx==0.28.1
# via
# kaya-oidc
# tavolo-app (pyproject.toml)
idna==3.20
# via
# anyio
# httpx
iso8601==2.1.0
# via tortoise-orm
kaya-core==0.0.7
# via
# kaya-cors
# kaya-oidc
# kaya-openapi
# kaya-otel
# kaya-rsgi
# kaya-session
# tavolo-app (pyproject.toml)
kaya-cors==0.0.7
# via tavolo-app (pyproject.toml)
kaya-oidc==0.0.7
# via tavolo-app (pyproject.toml)
kaya-openapi==0.0.8
# via tavolo-app (pyproject.toml)
kaya-otel==0.0.7
# via tavolo-app (pyproject.toml)
kaya-rsgi==0.0.7
# via tavolo-app (pyproject.toml)
kaya-session==0.0.7
# via
# kaya-oidc
# kaya-session-redis
# tavolo-app (pyproject.toml)
kaya-session-redis==0.0.7
# via tavolo-app (pyproject.toml)
opentelemetry-api==1.45.0
# via
# opentelemetry-exporter-http-transport
# opentelemetry-exporter-otlp-proto-http
# opentelemetry-instrumentation
# opentelemetry-instrumentation-asyncpg
# opentelemetry-instrumentation-redis
# opentelemetry-instrumentation-system-metrics
# opentelemetry-sdk
# opentelemetry-semantic-conventions
opentelemetry-exporter-http-transport[urllib3]==0.66b0
# via opentelemetry-exporter-otlp-proto-http
opentelemetry-exporter-otlp-common==0.66b0
# via opentelemetry-exporter-otlp-proto-http
opentelemetry-exporter-otlp-proto-common==1.45.0
# via opentelemetry-exporter-otlp-proto-http
opentelemetry-exporter-otlp-proto-http==1.45.0
# via kaya-otel
opentelemetry-instrumentation==0.66b0
# via
# opentelemetry-instrumentation-asyncpg
# opentelemetry-instrumentation-redis
# opentelemetry-instrumentation-system-metrics
opentelemetry-instrumentation-asyncpg==0.66b0
# via tavolo-app (pyproject.toml)
opentelemetry-instrumentation-redis==0.66b0
# via tavolo-app (pyproject.toml)
opentelemetry-instrumentation-system-metrics==0.66b0
# via tavolo-app (pyproject.toml)
opentelemetry-proto==1.45.0
# via
# opentelemetry-exporter-otlp-proto-common
# opentelemetry-exporter-otlp-proto-http
opentelemetry-sdk==1.45.0
# via
# kaya-otel
# opentelemetry-exporter-otlp-common
# opentelemetry-exporter-otlp-proto-http
opentelemetry-semantic-conventions==0.66b0
# via
# opentelemetry-instrumentation
# opentelemetry-instrumentation-asyncpg
# opentelemetry-instrumentation-redis
# opentelemetry-instrumentation-system-metrics
# opentelemetry-sdk
packaging==26.3
# via opentelemetry-instrumentation
protobuf==7.36.2
# via
# googleapis-common-protos
# opentelemetry-proto
psutil==7.2.2
# via opentelemetry-instrumentation-system-metrics
pwo==0.1.2
# via
# kaya-core
# kaya-rsgi
# kaya-session
# tavolo-app (pyproject.toml)
pycparser==3.0
# via cffi
pyjwt[crypto]==2.15.1
# via
# kaya-oidc
# tavolo-app (pyproject.toml)
pypika-tortoise==0.6.5
# via tortoise-orm
pyyaml==6.0.3
# via tavolo-app (pyproject.toml)
redis==8.1.0
# via
# kaya-session-redis
# tavolo-app (pyproject.toml)
tortoise-orm==1.1.8
# via aerich
typing-extensions==4.16.0
# via
# anyio
# kaya-core
# opentelemetry-api
# opentelemetry-exporter-otlp-proto-http
# opentelemetry-sdk
# opentelemetry-semantic-conventions
# pwo
urllib3==2.8.0
# via opentelemetry-exporter-http-transport
wrapt==2.5.0
# via
# opentelemetry-instrumentation
# opentelemetry-instrumentation-redis
+1852
View File
File diff suppressed because it is too large Load Diff