Consolidate Python dependencies to pyproject.toml with uv as single source of truth

[IanWorley]

Summary

Use pyproject.toml as the only source of truth for Python dependencies and uv for installs and locking. Migrate from Poetry's format to PEP 621, update Docker and CI to install via uv, and remove or generate requirements.txt so the two files cannot drift. Use three dependency groups: runtime (non-dev), dev, and test (for CI/CD). uv is supported on macOS, Linux, and Windows.

Motivation

We currently maintain two dependency lists that are out of sync:

• src/python/requirements.txt — 4 runtime packages (bottle, cryptography, pexpect, tblib). Both Dockerfiles use this.
• src/python/pyproject.toml — 8 runtime packages (same four plus requests, timeout-decorator, urllib3, certifi) in Poetry format. Not used for Docker installs.

Having both leads to drift. The image only installs from requirements.txt, so any runtime deps only in pyproject.toml are missing in the container.

Current State

• Docker: docker-image/Dockerfile and test-image/Dockerfile copy and pip install -r requirements.txt; test image also installs pytest, parameterized, testfixtures, webtest, timeout-decorator manually.
• pyproject.toml: Poetry config ([tool.poetry], [tool.poetry.dependencies], [tool.poetry.group.dev.dependencies]); no lockfile in tree (removed per CHANGELOG).

Implementation

1. Migrate pyproject.toml to PEP 621 (uv format)

uv uses PEP 621, not Poetry's format. Convert in place:

• Replace [tool.poetry] / [tool.poetry.dependencies] with [project] (name, version, description, requires-python, dependencies as a list of strings).
• Replace [tool.poetry.group.dev.dependencies] with [dependency-groups] (PEP 735) and three groups:
  • Runtime (non-dev): Keep in [project].dependencies only — what the app needs to run (bottle, cryptography, pexpect, requests, tblib, timeout-decorator, urllib3, certifi). No separate "runtime" table; this is the default install when no groups are requested.
  • dev: Local development tooling (e.g. ruff, pyright, or other lint/format/type-check tools when added). Synced by default for local uv sync.
  • test: Testing dependencies for CI/CD (pytest, parameterized, testfixtures, webtest, timeout-decorator if only needed for tests). Used in test image and CI; not included in runtime image.
• Keep the same package names and version constraints; only the table layout and syntax change.

2. Add uv and lockfile

• Document or script uv install for local dev (e.g. install script, Homebrew, or pipx).
• Run uv lock and commit uv.lock so installs are reproducible.

3. Update Dockerfiles to use uv

• src/docker/build/docker-image/Dockerfile — Install uv, then uv sync --frozen --no-dev (and exclude test group) so only [project].dependencies are installed. No requirements.txt copy.
• src/docker/build/test-image/Dockerfile — Same base; use uv sync --frozen --group test (and optionally --no-group dev) so CI/test image gets runtime + test group only.

4. Resolve requirements.txt

• Either remove requirements.txt and stop using it everywhere, or generate it only (e.g. uv export --no-dev -o requirements.txt) in CI/script and never edit by hand.

5. CI

• Ensure CI (e.g. .github/workflows/ci.yml) installs Python deps via uv: install uv, then uv sync --frozen --group test (or equivalent) so CI has runtime + test group for running tests.

6. Verify

• Confirm runtime image has only runtime deps; test image and CI have runtime + test group.
• Run existing tests and smoke checks in the built images and in CI.

Acceptance Criteria

• Support a dev group, a non-dev (runtime) group, and a test group for CI/CD.
• pyproject.toml is PEP 621 (no Poetry tables); only source of truth for deps.
• Runtime (non-dev) in [project].dependencies; dev group for local tooling; test group for CI/CD (pytest, webtest, etc.).
• uv.lock committed; installs use uv sync --frozen with appropriate --no-dev / --group test for each context.
• uv used for dependency installs in Docker and CI and dev.
• Runtime Docker image installs only runtime deps; test image and CI install runtime + test group.
• No hand-maintained requirements.txt (removed or generated only).
• Docker builds and CI succeed; tests pass in the test image.

[nitrobass24]

Codebase audit findings

Reviewed the actual imports against both dependency files. The drift problem is real but pyproject.toml is the one that's wrong, not requirements.txt.

Dependency audit

Package	In pyproject.toml	In requirements.txt	Actually imported?
bottle	runtime	runtime	Yes — runtime
pexpect	runtime	runtime	Yes — runtime
tblib	runtime	runtime	Yes — runtime
cryptography	—	runtime	No — not imported anywhere. Dead dep.
requests	runtime	—	No — not imported anywhere. Dead dep.
urllib3	runtime	—	No — not imported anywhere. Dead dep.
certifi	runtime	—	No — not imported anywhere. Dead dep.
timeout-decorator	runtime	—	Test only — imported in 7 test files, zero runtime files. Misclassified as runtime.
pytest	dev	—	Test only
parameterized	dev	—	Test only
testfixtures	dev	—	Test only
webtest	dev	—	Test only

Key findings

1. 4 dead dependencies in pyproject.toml (requests, urllib3, certifi) and requirements.txt (cryptography) — not imported anywhere.
2. timeout-decorator is test-only but listed as runtime in pyproject.toml.
3. Nothing reads pyproject.toml — Poetry is not installed in Docker, CI, or local dev. No lockfile exists. It's effectively a dead config file.
4. requirements.txt is closer to correct — it has the 3 actual runtime deps (plus cryptography which is dead).

Prerequisite for future work

This is a prerequisite for:

• Full type safety with Pyright enforcement #249 (Pyright) — needs a dev dependency group
• Playwright E2E tests — replace broken Protractor suite #250 (Playwright E2E) — needs a test dependency group
• Add Ruff linting and formatting with CI enforcement #251 (Ruff) — needs a dev dependency group

Without proper groups, every new dev/test tool means manually editing Dockerfile strings.

Revised implementation plan

Phase 1: Clean up and migrate to PEP 621

1. Remove dead deps: requests, urllib3, certifi from pyproject.toml; investigate and likely remove cryptography from requirements.txt
2. Move timeout-decorator from runtime to test group
3. Convert pyproject.toml from Poetry format to PEP 621 with [dependency-groups] (PEP 735) for test and dev

Phase 2: Update Dockerfiles and CI
4. Production Dockerfile: install from pyproject.toml instead of hand-maintained requirements.txt
5. Test Dockerfile: install runtime + test group (no more appending package names as strings)
6. CI: ensure test runner uses the test group

Phase 3: Evaluate uv adoption (optional)
7. uv gives faster installs and a lockfile, but adds a new tool dependency. pip works fine for our scale. Can be deferred to a follow-up.

Proposed pyproject.toml

[project]
name = "seedsync"
version = "0.14.0"
description = "File synchronization tool for seedboxes"
requires-python = ">=3.12"
dependencies = [
    "bottle>=0.12,<1.0",
    "pexpect>=4.8",
    "tblib>=3.0",
]

[dependency-groups]
test = [
    "pytest>=7.0",
    "parameterized",
    "testfixtures",
    "webtest",
    "timeout-decorator>=0.5",
]
dev = [
    # Future: ruff, pyright, playwright
]

[nitrobass24]

Closed by PR #287 (merged to develop).