Enable ruff structure and import rules (INP, PLC, SLF, N, A, FAST, E)

[anth-volk]

Fixes #3919

Summary

Phase 1 step 1.8, group 7: structure and imports. Stacked on #3915.

• Test exemption (decided for this group): test files now also ignore SLF001, INP001 and PLC0415, alongside S101, D1, ANN and PLR2004. Tests deliberately reach into private members, pytest test directories aren't packages, and tests often import inside a test after patching the environment. Application code still gets every rule. api.quality.tests-ruff-exemptions is updated to match.
• Rules: select gains A, E, FAST, INP, N, PLC and SLF. All 289 findings left after the exemption are fixed or kept with an inline reason.
• FastAPI dependencies (FAST002, 21): ruff's own fix would break the v2 routes, which use from __future__ import annotations: FastAPI resolves string annotations against module globals, and the query dependencies were local closures. Each dependency is now a module-level alias instead, such as HouseholdCreateQueryDependency = Annotated[HouseholdCreateQuery, Depends(query_dependency(HouseholdCreateQuery))]. The OpenAPI is byte-identical.
• Imports inside functions (PLC0415):

  • Moved (8, plus 4 in the code Stage 12A: Sign-in identity and v1-anchored user associations #3891 added): imports that add no cycle, side effect or third-party load. A fresh-interpreter check of all 220 policyengine_api modules shows that policyengine_api.asgi, policyengine_api.api and 211 others load exactly the same modules. Seven route and dependency modules now also load the small, dependency-free readiness and fastapi_routes.dependencies modules.

  • Allowlisted as lazily loaded (28 suppressions removed): pyproject.toml lists 13 packages and modules in ruff's banned-module-level-imports, with TID253 selected:

    • policyengine and spm_calculator, which load country models;
    • data.v2.database, which registers an exit hook at import;
    • the nine v2 database_session modules;
    • libs.auth0_management.

    No application module imports any of them at module level. Importing one there now fails, though TYPE_CHECKING imports are fine, and PLC0415 accepts their in-function imports without a suppression. Tests and .github scripts may still import them at module level, so TID253 joins their file-level exceptions; find-api-model-versions.py imports policyengine.

  • Kept (32), each with a reason: modules that some application module also imports at module level, so they can't be allowlisted:

    • Google clients (data/orm.py imports google.cloud);
    • the v2 services modules, which sibling services import;
    • import-time I/O (simulation_entrypoint, specification, constants);
    • country models (country, metadata_service);
    • readiness's configuration imports;
    • one cycle;
    • two places where tests patch the name per call.
• Namespace packages (INP001, 45): policyengine_api has no __init__.py on purpose, and .github, dashboard/experiments, migrations/v1, migrations/v2 and rules/fixtures aren't packages. They're declared in ruff's top-level namespace-packages setting, with a comment. Compared with the full ruff check output before the change, the only other difference is a hyphenated .github script name (N999), kept with a reason because a shell script runs it by that path. No __init__.py was added, and the built wheel and sdist contain the same files.
• Names (N, A, SLF001): internal names are renamed: two constants in economy_comparison.py, the rules tool's BaseUnavailableError and assert_violation, SQLAlchemy's TimeoutError imported as PoolTimeoutError in tests, and 13 test function names that alone overflowed the line. Kept with a reason: country.py's class reform, since policyengine-core uses the class name as the reform key; two gRPC-stub Export methods in a test; and three private accesses with no public equivalent that tests patch.
• Line length (E501, 149): wrapped. Every split string has identical text, which a syntax-tree comparison confirms. The two published Field descriptions that were split are unchanged. Kept with a reason (6 findings, 4 suppressions): a dotted module path, two GPT-4 prompts in the dashboard experiment, and a docstring line that is a script's --help text.
• Registry: api.quality.ruff-lint now lists the seven families and TID253. The rules tool changed (wrapped lines and the renames above), and sim takes the same changes in Enable ruff structure and import rules (INP, PLC, SLF, N, A, FAST, E) policyengine-sim-api#799, which has the same allowlist mechanism.

Testing

• pytest tests/unit tests/contract, to_refactor and the dedupe integration test (the make test set): 2,420 passed, the same as the base. That run was before the stack was rebased onto the release commit; this branch differs from it only in that commit's CHANGELOG.md, pyproject.toml version, uv.lock and changelog fragment.
• make typecheck-v2 is clean. mypy on the 65 changed files outside that gate gives the same output as the base.
• ruff check and ruff format --check (0.15.12) are clean repo-wide.
• Every Pydantic model schema, the FastAPI OpenAPI with every native router enabled, the /v2/openapi.json preview and the legacy spec are byte-identical to the base, with and without OLD_SIMULATION_GATEWAY_URL set.
• The quality guards, the rules guard and the rules tool unittest pass.
• For the allowlist change, at each tip from Enable ruff structure and import rules (INP, PLC, SLF, N, A, FAST, E) #3920 to Register weighted-microdata rules, with AST guards and #767 proofs #3938:
  • ruff check (including RUF100 from Enable ruff argument, idiom and pytest-style rules (ARG, B, C4, FBT, PERF, PLW, PT, PTH, RUF, SIM and others) #3924 up, so no suppression is left unused) and ruff format --check are clean.
  • The guards and the rules tool unittests pass.
  • Rendered rules are fresh at every commit.
  • Project Python differs from the previous version only in noqa comments. The test suites weren't re-run for this comment-and-configuration change.
• CI/CD: no workflow changed. .github/find-api-model-versions.py gained only a suppression comment.
• CI: this PR is above the bottom of its stack, so it runs only CI complete, which fails and says why. Its full run starts once the PRs below it merge.

🤖 Generated with Claude Code