| 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:
- Lint, with autofix
uv run ruff check --fix .
- Format
uv run ruff format .
- Type check
uv run ty check .
- 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.
