author: dotagents
name: general-python
description: Python stack hub: uv/ruff/ty workflows, builtins and collections, functions and classes, dataclasses, typing boundaries, pytest and NumPy-style docs. Use for any Python task in repos that follow this stack; pairs with python-reviewer, python-types, and python-refactor. Related skills: numpy-scientific, dataframes, numpy-docstrings, matplotlib-scientific, lab-instrumentation. Triggers on Python, uv, ruff, ty, pytest, dataclass, typing.
General Python
This skill is the hub for conventions that come from the project Python section (often merged into AGENTS.md), the Python Cursor rule on **/*.py, and the python-reviewer / python-types / python-refactor subagents. Load topic files below instead of drifting from project defaults.
Synergy map
| Source | Role |
|---|
| Python spec (AGENTS.md block) | Canonical tooling (uv, ruff, ty), style, pytest, numerics, tables, instruments |
| Python rule | Globs **/*.py: 3.12+, uv, NumPy-style public docstrings, pyvisa split |
| python-reviewer | Post-change review: uv hygiene, typing, numerics footguns, tests |
| python-types | Deep typing for Astral ty, PEP 695, exhaustive match |
| python-refactor | Structure: tuples vs dataclasses, composition vs inheritance, size |
| matplotlib-scientific | Figures only; keep plotting out of this hub |
| numpy-scientific | ndarray design: dtypes, views, broadcasting, ufuncs, linalg, I/O, random |
| dataframes | pandas + Polars: tables, lazy frames, joins, I/O, interop |
| numpy-docstrings | numpydoc sections for public API docstrings |
| lab-instrumentation | PyVISA, sockets, HALs, validation, PDF datasheets, instrument tests |
Quick decisions
- Dependencies:
uv add / uv remove / uv sync / uv run. Never hand-edit version pins in pyproject.toml. See reference-tooling.md.
- Quality gate:
ruff check (and format per project config), then ty check on touched code. See reference-tooling.md.
- Data: prefer the right builtin or collections ABC before a custom class; use dataclasses for labeled bundles of data. See reference-data-structures.md and reference-classes-dataclasses.md.
- APIs: small pure core, I/O at edges, explicit types on public boundaries. See reference-functions.md and reference-types-and-agents.md.
- Tests and docs:
uv run pytest; NumPy-style docstrings on public APIs. See reference-testing-docs.md.
Reference index
| Topic | File |
|---|
| uv, ruff, ty, layout, CI-style verification | reference-tooling.md |
list, dict, tuple, set, comprehensions, collections | reference-data-structures.md |
| Functions: purity, parameters, errors, resources | reference-functions.md |
| Classes, dataclasses, slots, immutability | reference-classes-dataclasses.md |
| Types, ty, when to delegate to python-types | reference-types-and-agents.md |
| pytest, docstrings, readability | reference-testing-docs.md |
| Vectorized numerics, tables, instruments, plotting boundary | reference-scientific-numerics.md |
External anchors
Modern practice snapshot
Reproducible projects combine locked deps, fast lint/format, and static typing on API surfaces; src layout avoids import ambiguity; automate checks in CI or pre-commit. See reference-tooling.md.
