Modern Python Project Instructions (uv + ruff + pytest)

# Project Instructions — Python (uv) ## Environment & dependencies This project is managed by **uv**. Never call `pip`, `poetry`, `pipenv`, or `python -m venv` directly. ```bash uv sync # create/update the venv from uv.lock uv add <package> # add a runtime dependency uv add --dev <package> # add a dev dependency uv run <cmd> # run anything inside the venv ``` - `pyproject.toml` is the single source of truth for dependencies. Never edit `uv.lock` by hand; it changes only as a side effect of `uv add`/`uv lock`. - Pin the Python version via `.python-version` (currently 3.12). Do not change it without asking. ## Quality gates All four must pass before committing: ```bash uv run ruff format . # formatter (not black) uv run ruff check --fix . # linter, autofix safe rules uv run mypy src/ # strict type checking uv run pytest # tests ``` If `ruff check` reports an error you believe is a false positive, add a targeted `# noqa: <RULE>` with a one-line justification — never disable a rule project-wide to silence one site. ## Type hints - Every function signature is fully annotated: parameters and return type, including `-> None`. - Use modern syntax: `list[str]`, `str | None`, `from collections.abc import Sequence`. No `typing.List`, `typing.Optional`, or `typing.Union`. - No `Any` in new code. If a third-party library is untyped, wrap it in a small typed adapter in `src/<your_package>/compat/`. - Public dataclasses and config objects use `pydantic.BaseModel` or `@dataclass(frozen=True, slots=True)` — pick whichever the surrounding module already uses. ## Tests - pytest only; no unittest classes. Test files mirror the source tree: `src/<pkg>/orders/service.py` → `tests/orders/test_service.py`. - Prefer plain functions + fixtures. Shared fixtures live in the nearest `conftest.py`. - Parametrize instead of copy-pasting near-identical tests: `@pytest.mark.parametrize`. - Tests must not hit the network. Mock at the boundary (the HTTP client wrapper), not deep internals. - Run a focused subset while iterating: `uv run pytest tests/orders -x -q`, then the full suite before committing. ## Layout ``` src/<your_package>/ # all importable code (src layout — never a top-level package dir) tests/ # mirrors src scripts/ # one-off maintenance scripts, run via uv run scripts/<name>.py ``` ## Rules - No bare `except:` and no `except Exception` without re-raising or logging with context. - Use `pathlib.Path` over `os.path`, f-strings over `%`/`.format`, `logging` over `print` in library code. - New modules need docstrings on public functions; skip docstrings on obvious private helpers. - Do not commit notebooks, `.env` files, or anything under `.venv/`.