agentleFS
arxdsilvaarxdsilva/ai-loops/skills/lang-python/SKILL.md

lang-python

Skill0 starsChanged 7 days agoMITView on GitHub

Use when writing, reviewing, testing or setting up Python backend code in a loops run (the python language pack) - toolchain, layout, race policy, coverage, idioms and footguns.

  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run uv sync --locked (never plain uv sync) so a stale lock breaks the build (PY-REPO-05).

    line 36
  2. Very specific:

    never pass -p no:randomly, a fixed order, a retry plugin or -n 0 to the gate run.

    line 41
  3. Distinctive:

    if the host cannot run the substitute (plugin missing, no pytest-xdist), the gate fails with a preflight message.

    line 45
  4. Very specific:

    Import-time side effects and cycles: wire in compose.py, enforce with import-linter.

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Python language pack

Rules: specs/languages/python/RULES.md (IDs PY-<SEC>-NN). Pack data: specs/languages/python/pack.json (loops lang show python). Layers, ports, errors and consistency are language-neutral: specs/ARCHITECTURE.md, skills/hexagonal, skills/consistency. Gate, roles and the race rule: specs/WORKFLOW.md §6.

1. When it applies

loops lang detect reports python for a root (pyproject.toml, uv.lock or requirements.txt). Several packs can apply to one repo: gate each root with its own pack.

2. Project rules first

The repository's own configuration wins over the pack defaults: pyproject.toml ([tool.ruff], [tool.mypy], [tool.pytest.ini_options], [tool.coverage], [tool.importlinter]), ruff.toml, mypy.ini, pyrightconfig.json, tox.ini, .pre-commit-config.yaml, framework conventions (Django apps, Flask blueprints). Read them before writing code (config_files in the pack). Poetry, pip-tools, black, flake8, unittest or a flat layout are legitimate project choices: follow them and log each deviation with loops run override --rule "<loops rule>" --project "<project rule, file:line>" --note "<what you did>".

3. The toolchain the gate runs

loops gate runs these in order (agents may run the single commands while iterating; QA scopes with --only/--pkgs; {pkgs} = src, {pkg_dirs} = .):

CheckCommandRequired
sync (deps)uv sync --locked when uv.lock exists, else python -m pip install -e . --group devno
ruff-formatruff format --check .only when ruff config is committed (D14)
ruffruff check --output-format=concise .yes
mypy / pyrightmypy --strict src / pyright (the one the project configures; each skips if not installed)no
import-linter (arch)lint-imports, when .importlinter existsno
testpytest -p randomly -n 2 -W error --cov --cov-branch --cov-report=xml:{coverage} with PYTHONDEVMODE=1yes
coveragenew-code coverage >= 70% from the Cobertura file (loops computes it)yes
banditbandit -r src -ll -qno
pip-auditpip-audit --locked ., only with --vulnoff by default

A missing optional tool skips with its install hint (D12); missing pytest, pytest-cov, pytest-randomly or pytest-xdist fails the required test check. Tools must resolve on PATH: activate .venv, or run the gate as uv run loops gate. After a file edit the post-edit hook runs ruff format <file> and ruff check <dir>. See PY-TOOL-03..10, PY-REPO-04/05.

Run uv sync --locked (never plain uv sync) so a stale lock breaks the build (PY-REPO-05).

4. Race policy: none plus the substitute

CPython has no data-race detector, so the required test check is the substitute (PY-CONC-05/06, WORKFLOW §6): random order (-p randomly, printed seed), two xdist workers (-n 2), warnings as errors (-W error), dev mode (PYTHONDEVMODE=1: asyncio debug, ResourceWarning). To satisfy it:

  • never pass -p no:randomly, a fixed order, a retry plugin or -n 0 to the gate run;
  • reproduce a failure with --randomly-seed=<seed from the output>; fix the shared state, never the flag;
  • for changed test files, also run them under two other --randomly-seed values;
  • threaded code on a free-threaded interpreter (3.14t/3.15t): add PYTHON_GIL=0 pytest --parallel-threads=4 --iterations=10 (concurrency.md);
  • if the host cannot run the substitute (plugin missing, no pytest-xdist), the gate fails with a preflight message; install it, do not skip.

5. Coverage recipe

Cobertura XML at {coverage}, branch coverage on. Project prerequisites the architect or python-engineer adds in wave 0 (D13, logged as an override if the project differs):

  • [dependency-groups] with test = [pytest, pytest-cov, pytest-randomly, pytest-xdist] and lint = [mypy, import-linter, bandit]; uv.lock committed;
  • [tool.coverage.run] source = ["src"], branch = true; [tool.coverage.report] exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError", "\\.\\.\\."];
  • [tool.pytest.ini_options]: testpaths = ["tests"], addopts = ["--import-mode=importlib", "--strict-markers", "--strict-config"], filterwarnings = ["error"];
  • [tool.ruff] with explicit rule selection (PY-TOOL-04), [tool.mypy] strict = true, .importlinter, .python-version, .gitignore entries (PY-REPO-13).

Excluded from the gate's coverage: tests, conftest.py, *.pyi, migrations, compose.py, main.py, __main__.py, generated files. Do not add omit entries to hit a number (PY-TEST-09).

6. Layer map

src/<pkg>/
  domain/        pure: frozen dataclasses, enums, errors; no I/O, no clock, no os/requests/sqlalchemy/pydantic
  application/   use cases + ports (typing.Protocol, owned by the consumer)
  adapters/
    inbound/     http (FastAPI/Flask routers), cli, worker
    outbound/    db (SQLAlchemy, Alembic), clock, http clients
  compose.py     composition root: build_app(settings)
  main.py        create_app() only
tests/unit  tests/integration  conftest.py

loops arch does not parse Python (arch.parser: none): import-linter enforces direction, forbidden imports and cycles. Purity, clock and RNG injection stay review items (PY-ARCH-07). Django keeps its app layout (frameworks.md).

7. Footguns

  1. Mutable default arguments: None plus create inside, or default_factory.
  2. Blocking calls in async def: httpx.AsyncClient or asyncio.to_thread.
  3. Bare except, swallowed CancelledError: narrow the type, re-raise cancellation.
  4. asyncio.create_task without keeping a reference: TaskGroup.
  5. pickle/yaml.load on untrusted data: JSON, safe_load, Pydantic.
  6. Naive or utcnow() datetimes: datetime.now(UTC) via an injected clock.
  7. assert for validation: raise a real exception.
  8. Import-time side effects and cycles: wire in compose.py, enforce with import-linter.
  9. Float money, mutable hash keys: Decimal, frozen dataclasses.
  10. "The GIL makes it thread-safe": it does not; use a Lock or a queue.

8. Load on demand

  • repo.md: layout, pyproject, uv, lockfile, CI order, hygiene (PY-REPO, PY-TOOL).
  • architecture.md: hexagon in Python, Protocol ports, import-linter contracts (PY-ARCH).
  • idioms.md: errors, typing, dataclasses, datetimes, money, imports (PY-IDIOM, PY-PERF).
  • testing.md: pytest layout, fixtures, fakes, randomly/xdist, coverage (PY-TEST).
  • concurrency.md: asyncio, threads, free-threading, the substitute check (PY-CONC).
  • security.md: injection, deserialisation, SSRF, secrets, supply chain (PY-SEC).
  • data-api.md: SQLAlchemy, migrations, HTTP, logging, metrics, config, packaging (PY-DATA, PY-API, PY-OBS, PY-OPS).
  • frameworks.md: FastAPI, Django, Flask conventions (PY-FW, PY-DOC).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.