[anth-volk]

Fixes #3923

Summary

Phase 1 step 1.8, group 8a: arguments, idioms and pytest style. Stacked on #3920. Group 8b follows with the complexity refactors and the switch to select = ["ALL"].

• Test stand-ins exempt from unused-argument rules (added 2026-10-16): test fakes and stand-ins mirror the signatures of what they replace, because callers pass those arguments by keyword.
  • ARG001, ARG002 and ARG005 join the **/tests/** file-level exceptions (api.quality.tests-ruff-exemptions). That removes 32 inline codes from 16 test files here and 37 by Register weighted-microdata rules, with AST guards and #767 proofs #3938.
  • Application code doesn't get this exception. Its findings are fixed in code, or kept inline where listed under "Inline suppressions".
• Unittest exemption (decided for this group): the shared rules tool's tests use unittest on purpose, because the tool needs only the standard library. scripts/rules/tests/** is exempt from ruff's pytest-style rules (PT), registered as api.quality.unittest-ruff-exemptions.
• Rules: select gains ARG, ASYNC, B, C4, FBT, PD, PERF, PGH, PLW, PT, PTH, RUF and SIM. All 912 findings are fixed, covered by the tests' file-level exceptions, or kept with one of the 8 inline suppressions listed below. There's one commit per family.
• Unused arguments (ARG, 468):
  • 118 tests now request side-effect fixtures with @pytest.mark.usefixtures; the collected test IDs are identical.
  • Unused *args/**kwargs became *_args/**_kwargs. A named lambda or callback parameter is underscored only where every caller passes it positionally, as in the v2 Alembic environment's include_object hook.
  • Methods that override a base method or implement a protocol are decorated with @override from typing_extensions, which works on Python 3.11 (typing.override needs 3.12). Ruff doesn't report unused arguments of an @override method. This covers every DisabledCacheBackend method in runtime_cache/fake.py, and RegistryCapability.get_spm_capability in worker_spm_release.py, which now subclasses the SPMCapabilitySource protocol explicitly.
  • typing-extensions is now a direct dependency (>=4.4,<5; override was added in 4.4). It was already installed indirectly at 4.15.0. The uv.lock diff only records the new direct dependency: no package version changes, and the lock was written with uv 0.12.1, the version CI pins, so its format revision is unchanged.
  • Flask views that receive the <country_id> URL variable by keyword keep an inline reason (see "Inline suppressions").
• Keyword-only booleans (FBT): PolicyEngineCountry.calculate and prepare_calculation (spm_requested, prepared), EconomyService._setup_sim_options, and the cache backend protocol's pipeline(*, transaction=True). Every caller already passed these by keyword. The FastAPI current query parameter and Alembic's positional include_object hook are kept, with reasons.
• Bugbear (B):
  • B904: the simulation and report-output routes' create and update handlers now raise BadRequest(...) from e. The 400 responses are unchanged; only the traceback's chaining text changes.
  • B905: zip(..., strict=True) where the lengths are fixed by literals.
  • B023: loop variables bound in closures that only run within their own iteration.
• Module-level state (PLW0603): no function rebinds a module global any more.
  • readiness.py: the lock and boolean pair is one threading.Event, set at import because the default is ready. mark_not_ready clears it and mark_ready sets it. is_ready still returns False without running the configuration check when the event is clear, and runs the check otherwise.
  • data/orm.py: the Cloud SQL connector, engine and session factory are fields of one private _CloudSqlState instance.
  • data/v2/database.py: the engine, the ID of the process that created it, its URL fingerprint and the session factory are fields of one private _V2EngineState instance. _state_lock and the fork handling are unchanged.
  • Two tests reach these names. tests/unit/data/test_sqlalchemy_v2.py patches the orm state, and tests/unit/v2/test_database.py reads the v2 engine's process ID. Both now use the state objects. No test patches the readiness state.
• Best-effort swallows (SIM105): Enable ruff exception rules (TRY, EM, BLE) #3913 and Enable ruff security, logging and debugging rules (S, T20, LOG, G, DTZ, ERA, TD, FIX, EXE) #3915 already turned every try: … except Exception: pass around a telemetry or logging call into with contextlib.suppress(Exception):, with the reason in a comment above it. Here SIM105 converts the two remaining try/except/pass blocks, which catch specific exceptions: country.py (TypeError, ValueError, OverflowError) and reform_impacts_service.py (CacheCoordinationError). No suppression changes.
• Idioms: 154 dict() calls become literals, plus comprehensions (C4, PERF), simplified conditions and combined with statements in the same order (SIM), ClassVar annotations, explicit Optional types, raw regex patterns and sorted __all__ (RUF), Path.open (PTH) and check=False on subprocess.run (PLW1510).
• Non-ASCII digits in tests (RUF001): the tests that check numeric identity use Arabic-Indic and full-width digits as inputs. They're now written as escape sequences: named escapes such as "\N{FULLWIDTH DIGIT ONE}" for single digits, and \u escapes, with a comment, for the two ten-digit translation tables.
• Blocking read in async code (ASYNC240): scripts/measure_cloud_run_runtime.py reads and parses the payload file in main() before asyncio.run(...), and passes the parsed payload to _run().
• Pytest style (PT): 37 pytest.raises gain match= with the real message; where a test only asserted that text separately, the match replaces that assertion. Parametrize names and values use tuples and lists, and composite assertions are split.
• Registry: api.quality.ruff-lint now lists the 13 families. The rules tool changed (comprehensions, check=False, a bound loop variable and an unused parser parameter removed); sim takes the same changes in Enable ruff argument, idiom and pytest-style rules (ARG, B, C4, FBT, PERF, PLW, PT, PTH, RUF, SIM and others) policyengine-sim-api#802.

Inline suppressions

This PR adds 8 inline suppressions; it adds no file-level exception for application code.

Location	Code	Reason	Why no code change or setting
policyengine_api/routes/household_routes.py, get_calculate and get_calculate_full	ARG001	Flask passes the <country_id> URL variable by keyword; validate_country checks it.	Renaming or removing the parameter breaks Flask's call. A file-level exception isn't allowed for application code.
policyengine_api/routes/user_profile_routes.py, get_user_profile and update_user_profile	ARG001	The same <country_id> URL variable, also checked by validate_country.	As above.
migrations/v2/env.py, _include_application_object(..., _reflected, ...)	FBT001	Alembic calls this include_object hook with positional arguments.	A keyword-only parameter breaks Alembic's call, and the file isn't one that file-level exceptions may cover.
policyengine_api/fastapi_routes/v2/metadata/parameter_routes.py, current: bool = False	FBT001, FBT002	A FastAPI query parameter.	#3933 replaces the parameter list with one ParameterValueListingQuery dependency, which removes this suppression.
policyengine_api/services/economy_comparison.py, two MicroSeries(...).values reads	PD011	MicroSeries overrides .values, and .to_numpy() emits a different warning.	#3936 deletes the module, which has no callers.

Suppression counts

Counted as lines containing # noqa in Python files (git grep -c '# noqa' -- '*.py', summed). The counts are one lower than before, because #3959 merged two BLE001 suppressions on master:

	Base (#3920)	This PR before 2026-10-20	This PR now
Lines with # noqa	96	125	98
Added by this PR		35 (and 6 E402 removed)	8 (and 6 E402 removed)

2026-10-20: rebased onto #3985

#3985 (v2 table privileges) added new application code. This PR's rules found three findings in it, and commit d8a153bef fixes them with code changes, adding no suppressions:

• PTH123: the privilege reconciliation appends its GitHub step summary through Path.open.
• PERF401: the annotation scan in privilege_requirements.py extends its list from one generator.
• C420: the manifest proof test builds its no-access map with dict.fromkeys.

Behaviour is unchanged, and #3985's 70 privilege tests pass. The only environment variable the changed code reads is GITHUB_STEP_SUMMARY, which the GitHub Actions runner sets for every step; how it is read is unchanged. The suppression counts are unchanged too.

2026-10-20 update: 27 fewer suppressions

Four commits on top of the branch remove 27 of the 35 inline suppressions this PR added. The earlier commits are unchanged.

1. 023b02420 Keep process state in objects instead of rebinding module globals (PLW0603): removes 11. See "Module-level state" above.
2. 14f29aeab Mark method overrides with typing_extensions.override (ARG002): removes 9, and adds the typing-extensions direct dependency.
3. e319ee6d6 Write the non-ASCII test digits as escape sequences (RUF001): removes 6. The parsed ASTs of all four test files are identical to the previous version, so every string constant and test parameter is unchanged.
4. f6d25ebb6 Read the load generator's payload before starting the event loop (ASYNC240): removes 1.

Testing

2026-10-20 update. At this tip (f6d25ebb6), on Python 3.12 with the uv.lock dependencies (uv sync --frozen --extra dev --python 3.12):

• ruff format --check . and ruff check . (ruff 0.15.12, with RUF100) are clean.
• python scripts/run_quality_guards.py and python -m scripts.rules guard --base-ref origin/ruff-structure-imports pass, and python -m scripts.rules render leaves no diff.
• mypy (the configured files): no issues in 167 source files. mypy on data/orm.py, data/v2/database.py, readiness.py, runtime_cache/fake.py and worker_spm_release.py reports nothing new.
• pytest tests/unit: 2,686 passed.
• Environment variables: the changes to data/orm.py, data/v2/database.py and readiness.py add, remove and rename none, and each is read in the same place and way as before.
  • orm.py reads POLICYENGINE_DB_INSTANCE_CONNECTION_NAME and POLICYENGINE_DB_PASSWORD (both required), and POLICYENGINE_DB_USER and POLICYENGINE_DB_NAME (both default to policyengine), when the engine is first built. It still calls load_dotenv() at import.
  • database.py and readiness.py read none directly. They call the same settings loaders under the same conditions.

2026-10-19 update. The stack was restacked onto #3915, which now converts the last best-effort blocks and removes the dashboard experiment, so this PR's contextlib.suppress commit was dropped and its SIM105 change shrank to the two blocks above. At that tip (7e92040), ruff check (with RUF100) and ruff format --check were clean and the quality guards passed. At the top of the stack (#3938, 7b23281), the make test set passed: 3,197 tests on Python 3.12 with the uv.lock dependencies. The earlier notes below describe the previous tips.

• The make test set (tests/unit, tests/contract, to_refactor and the dedupe integration test): 2,416 passed, 4 failed, the same as the base today.
  • The 4 failures are a date-dependent test on master. tests/unit/v2/test_stage12_comparison_models.py fixes retention_expires_at at 2026-10-14 but leaves created_at on the real clock, so its inserts fail the retention check since that date. It's unrelated to this PR and needs its own fix against master.
  • With the model clock frozen at 2026-09-20, every test passes on both base and branch.
• make typecheck-v2 is clean. mypy on the 128 changed files outside its file list shows no new errors.
• ruff check and ruff format --check (0.15.12) are clean repo-wide.
• Every Pydantic model schema and adapter, the FastAPI OpenAPI with every native router enabled, the /v2/openapi.json preview and the legacy spec are byte-identical to the base.
• The quality guards, the rules guard and the rules tool unittest (also on Python 3.11) pass.
• For the 2026-10-16 changes, at each tip from Enable ruff argument, idiom and pytest-style rules (ARG, B, C4, FBT, PERF, PLW, PT, PTH, RUF, SIM and others) #3924 to Register weighted-microdata rules, with AST guards and #767 proofs #3938:
  • ruff check (including RUF100) and ruff format --check are clean, and so are the guards and the rules tool unittests.
  • Rendered rules are fresh at all 104 commits.
  • Project Python differs from the previous version only in noqa comments, apart from:
    • the twelve files with contextlib.suppress rewrites;
    • one test lambda that ruff format re-wrapped once its comment was gone.
  • mypy is clean at Enable ruff argument, idiom and pytest-style rules (ARG, B, C4, FBT, PERF, PLW, PT, PTH, RUF, SIM and others) #3924.
  • The test modules that cover the rewritten code pass: 809 tests in 31 modules at Enable ruff argument, idiom and pytest-style rules (ARG, B, C4, FBT, PERF, PLW, PT, PTH, RUF, SIM and others) #3924, 980 at Register weighted-microdata rules, with AST guards and #767 proofs #3938, and 159 in the v1 route contract and deploy-script tests. The full suites weren't re-run for this change.
• CI/CD: no workflow changed. .github/find-api-model-versions.py changed only in idioms; it reads only GITHUB_ENV, which the Actions runner provides, and only when run without --shell, which its CI caller always passes.
• 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

[codecov]

Codecov Report

❌ Patch coverage is 73.05389% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.74%. Comparing base (f117791) to head (5ae76f9).
⚠️ Report is 28 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/services/economy_comparison.py	31.03%	20 Missing ⚠️
policyengine_api/country.py	41.66%	6 Missing and 1 partial ⚠️
policyengine_api/data/orm.py	76.19%	3 Missing and 2 partials ⚠️
policyengine_api/data/v2/database.py	93.54%	0 Missing and 2 partials ⚠️
policyengine_api/routes/policy_routes.py	33.33%	0 Missing and 2 partials ⚠️
policyengine_api/services/economy_service.py	0.00%	0 Missing and 2 partials ⚠️
.../payload_validators/validate_set_policy_payload.py	0.00%	1 Missing and 1 partial ⚠️
policyengine_api/constants.py	50.00%	1 Missing ⚠️
policyengine_api/data/congressional_districts.py	0.00%	0 Missing and 1 partial ⚠️
...licyengine_api/data/v2/privilege_reconciliation.py	50.00%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #3924       +/-   ##
===========================================
+ Coverage   49.20%   84.74%   +35.53%     
===========================================
  Files         242      258       +16     
  Lines       14307    15676     +1369     
  Branches     2357     2640      +283     
===========================================
+ Hits         7040    13284     +6244     
+ Misses       6637     1623     -5014     
- Partials      630      769      +139     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.