Skip to content

Enable ruff docstring rules (D) - #779

Merged
anth-volk merged 22 commits into
mainfrom
ruff-docstrings
Oct 16, 2026
Merged

Enable ruff docstring rules (D)#779
anth-volk merged 22 commits into
mainfrom
ruff-docstrings

Conversation

@anth-volk

@anth-volk anth-volk commented Oct 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Fixes #778

Same-Repository Draft PR Check

  • This PR is a draft.
  • This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

Phase 1 step 1.8, group 4: docstrings. Stacked on #777.

  • Docstrings: ruff.toml gains D and ignores D203 and D213, keeping D211 (no blank line before a class docstring) and D212 (summary on the first line). Every module, class and function outside tests is documented, one commit per project. The 1,043 findings at the base were: executor 427, contract 179, gateway 139, fastapi 118, entry 60, persistence 25, observability 22, integration tests 17, and 56 in repo scripts, proof fixtures and package markers.
  • Code is unchanged apart from docstrings. An AST comparison with the base, ignoring docstrings, finds two files with other changes, both equivalent:
    • observability/emitters.py: documented no-op methods drop their redundant return None instead of suppressing RET501.
    • opentelemetry/gcp.py: two misplaced string literals (a class description after __init__, and a function description after its imports) are replaced by docstrings in the right place.
  • Suppressions: none for D. An earlier commit suppressed D101 on 61 published contract, ping and health models; the commit "Document published contract models and routes" replaces every one with a docstring.
  • Published schema text changes (agreed): Pydantic copies a class docstring into the model's JSON-schema description, and FastAPI copies a route docstring into the operation description. So the entry, gateway and executor OpenAPI documents gain descriptions, written for API consumers. The gateway golden spec (tests/golden/openapi.json) is regenerated with generate_openapi. Compared with the base, ignoring description keys, it's structurally identical: 25 descriptions added, none changed or removed.
  • Shared rules tool: both repos documented scripts/rules independently, so the copies drifted. This PR takes the Public API's wording, so the tool is byte-identical again (tool sha256 db83d5ad2aa4 in both rendered rules pages). Only docstrings differ from the previous copy.
  • Registry: sim.quality.ruff-lint now lists D.
  • After rebasing onto main: Count households once: sum the weight column unweighted #767 added two docstrings whose summary lines aren't in the imperative mood, which D401 requires. The commit "Put the docstrings Count households once: sum the weight column unweighted #767 added in the imperative mood" rewords those two lines.

Testing

  • All seven projects' test suites pass:

    Project Passed
    fastapi 14
    contract 145
    observability 30
    stage12 12
    entry 224
    gateway 214
    executor 733

  • ruff check (0.15.22) is clean repo-wide, and ruff format --check is unchanged.

  • The rules guard, the ci-scripts guard and the rules tool unittest pass.

🤖 Generated with Claude Code

@anth-volk
anth-volk added this pull request to stack #755 October 13, 2026 13:28
@anth-volk anth-volk mentioned this pull request Oct 13, 2026
Draft
@anth-volk anth-volk mentioned this pull request Oct 13, 2026
Merged
2 tasks done
@anth-volk
anth-volk force-pushed the ruff-docstrings branch 3 times, most recently from 4e5cc2f to d6f1b11 Compare October 14, 2026 14:47
@anth-volk
anth-volk force-pushed the ruff-docstrings branch 4 times, most recently from b7ba1be to a0166f6 Compare October 14, 2026 21:06
@anth-volk
anth-volk force-pushed the ruff-docstrings branch 2 times, most recently from 740614d to 05d4fb2 Compare October 14, 2026 21:52
@anth-volk
anth-volk force-pushed the ruff-docstrings branch 2 times, most recently from a6e5037 to fc82737 Compare October 15, 2026 15:09
@anth-volk
anth-volk force-pushed the ruff-docstrings branch 2 times, most recently from 53d65e1 to cecbd05 Compare October 16, 2026 04:41
Base automatically changed from ruff-annotations to main October 16, 2026 04:54
anth-volk and others added 2 commits October 16, 2026 08:54
@anth-volk @claude
Document the simulation contract library for ruff D
c1f6ece 
Validators, state helpers and URI functions get docstrings. Every Pydantic
model and enum whose class docstring would become a JSON-schema description
carries a D101 noqa instead, so the published contract schemas and the
OpenAPI documents built from them stay byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the FastAPI support library for ruff D
bd91f22 
The ping and health models and the /ping/alive route are mounted in the
executor app, so they keep their existing (OpenAPI-visible) docstrings under
noqa. The no-op observability methods keep their explicit return None under
RET501 noqa, and two stray string statements in the GCP module become the
docstrings they were meant to be.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
anth-volk and others added 20 commits October 16, 2026 08:54
@anth-volk @claude
Document the simulation observability library for ruff D
a85a981 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the Stage 12 persistence library for ruff D
d7d6d02 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the simulation entrypoint for ruff D
fc588ed 
The entry routes are nested in create_app, so their docstrings (the OpenAPI
descriptions) are untouched and the generated spec is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the simulation gateway for ruff D
aa4dacf 
The /ping router endpoint keeps its OpenAPI description under a D205 noqa;
the golden OpenAPI test still passes. Two placeholder pass statements in the
test fixtures' mock exception classes go now that the classes have
docstrings (PIE790).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the simulation executor for ruff D
9d7dd87 
Covers the executor package, the Modal apps, fixtures, scripts and test
docstrings. Docstrings are added to several Modal functions; images copy
src/modal into a layer, so this changes those layers like any source edit.
Protocol stubs keep their ... bodies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the integration tests, repo scripts and package markers for …
542de3f 
…ruff D

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the Stage 12 schema-DDL proof fixtures for ruff D
14dba21 
The schema-authority proof reads the fixtures as text; the new docstrings
avoid DDL phrases, so the bad fixture is still rejected and the good one
accepted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Enable ruff group 4 (docstrings)
176fcbc 
Select pydocstyle (D) and ignore D203 and D213, the incompatible halves of
the D203/D211 and D212/D213 pairs. Tests stay exempt from D1 only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Drop redundant return None from documented no-op methods
8fa432b 
With a docstring as the body, the bare return None lines are redundant;
remove them instead of suppressing RET501.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document published contract models and routes
4b70ddb 
Replace the 61 D101 suppressions on contract, ping and health models with
class docstrings written for API consumers, and fix the /ping/alive and
gateway /ping route docstrings instead of suppressing D205. Pydantic and
FastAPI copy these into schema and operation descriptions, so the entry,
gateway and executor OpenAPI documents gain descriptions; paths, operations,
properties, types and required lists are unchanged. The gateway golden spec
is regenerated with generate_openapi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Use the Public API's docstrings in the shared rules tool
5682d6c 
Both repos documented scripts/rules independently for ruff D, so the
copies drifted apart. Take the Public API's wording so the tool stays
byte-identical in both repos; only docstrings differ.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Register D in the ruff-lint rule
4d78fc2 
sim.quality.ruff-lint now lists D, and the rendered rules page and
AGENTS.md Rules block are regenerated for the new tool hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #767 added in the imperative mood
a529896 
#767 landed on main after this stack branched. D401, which this PR
enables, wants each docstring's summary line in the imperative mood.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #743 and #744 added in the D style
18b6d0a 
#743 and #744 landed on main after this stack branched. D, which this PR
enables, flags their new code: blank lines after docstrings (D202), a
two-line summary (D205, D209), summaries that are not in the imperative
mood (D401), an escaped backslash in the sentinel's module docstring
(D301), and three public functions without docstrings (D103).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #789 added in the D style
c6be88f 
#789 landed on main after this stack branched. D, which this PR enables,
flags blank lines after its new docstrings (D202) and the undocumented
__call__ of its ConnectionOpener protocol (D102).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Document the shared object store fake #787 added
b66838c 
#787 landed on main after this stack branched. D, which this PR enables,
flags the undocumented __init__ (D107), upload_bytes and read_bytes (D102)
of the in-memory object store it moved into the executor's fixtures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #795 added in the D style
00a8a57 
D, which this PR enables, flags the undocumented group_label property
(D102), the budget check's run-on summary (D205, D209) and two test
helpers' summaries that are not in the imperative mood (D401).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #791 added in the D style
d385e30 
#791 landed on main after this stack branched. D, which this PR enables,
flags blank lines after five of its new docstrings (D202) and the
undocumented __init__ (D107) and stage method (D102) of its StageProgress
tracker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #758 added in the D style
b3b24f9 
#758 landed on main after this stack branched. D, which this PR enables,
flags its permission checks and deployed permission test:

- CallerAuthorizer's initializer and authorize now say what enforcement
  does with a caller that lacks a permission, and that the missing
  permission is always recorded;
- the permission_enforcement fixture says when it skips and when it
  raises, and the enforced-permission deployment test says what it
  checks;
- the blank lines after the docstrings of is_client_credentials,
  granted_permissions, the gty validator and the Cloud Run
  deployment-environment test helper go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk @claude
Put the docstrings #781 added in the D style
ea919cb 
#781 landed on main after this stack branched. D, which this PR enables,
flags its job progress code:

- the JobProgressReporter protocol and each of its methods say which
  stage boundary the runtime reports; the null reporter's methods say
  what they discard, with the docstring as the body;
- StoredJobProgressReporter's initializer, record, start, set_execution,
  enter, start_segments, segment_completed and attempts say how the
  record changes, including when a call changes nothing;
- the contract's job progress store functions say what they read and
  write, and StageReportingSimulation and its ensure say when the
  callback runs;
- the floor and maximum helpers, the Modal reporter factory, the
  published-record helper and the gateway's stage-field helper are in
  the imperative mood, and blank lines after docstrings go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@anth-volk
anth-volk marked this pull request as ready for review October 16, 2026 05:01
@anth-volk
anth-volk requested a review from a team as a code owner October 16, 2026 05:01
@anth-volk
anth-volk merged commit 698dd27 into main Oct 16, 2026
14 checks passed
@anth-volk
anth-volk deleted the ruff-docstrings branch October 16, 2026 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Enable ruff docstring rules (D)

1 participant

@anth-volk