python-lint

name	python-lint
description	Lint, format, and type-check Python code with ruff and ty, then run pytest, before considering any Python change done. Use whenever Python source files are added or edited in a uv-managed project.

Python Lint & Test

jyje's Python projects are uv-managed and require three checks to pass before a change is considered finished: ruff (lint + format), ty (type check), and pytest (tests). Skipping any one of them is not acceptable for a "done" change.

Required dev dependencies

Every uv project that ships Python source must declare these as dev dependencies (add once per project, not per change):

uv add --dev ruff ty pytest

This populates [dependency-groups] dev = [...] in pyproject.toml. Do not substitute alternatives (e.g. mypy, black, flake8, unittest) — ruff replaces lint+format, ty replaces mypy, pytest replaces unittest, and mixing tools fragments config for no benefit.

Steps

Run these in order after editing Python files, and again right before declaring the task complete:

1. Lint, with autofix

   uv run ruff check --fix .
   

2. Format

   uv run ruff format .
   

3. Type check

   uv run ty check .
   

4. Test

   uv run pytest
   

All four must exit clean (ruff/ty report no remaining issues, pytest reports no failures) before the change is done. If ty or ruff flag something that can't be fixed immediately (e.g. a third-party stub gap), say so explicitly rather than silently ignoring the finding — don't suppress with blanket # noqa / # type: ignore unless the suppression targets the exact rule and includes a short reason.

Test coverage expectations ("appropriate pytest")

• New functions/modules with non-trivial logic get at least one test that exercises the golden path and one that exercises a realistic edge case (empty input, error path, boundary value) — not just a smoke test that imports the module.
• Tests live under tests/, named test_*.py, mirroring the source layout they cover.
• Don't write tests for trivial pass-through code (e.g. a one-line wrapper with no branching) — match effort to actual risk, per jyje's general no-superfluous-abstraction preference.

Notes

• Run these commands from the uv project root (where pyproject.toml lives), not from a subdirectory — uv run resolves the project from there.
• If ruff or ty aren't yet in pyproject.toml's dev group, add them first (see above) rather than invoking a global/ad-hoc install.