Skip to content

agents(rules): update python rules with typing and runfiles conventions #4035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rickeylev merged 1 commit into from
Aug 11, 2026
+12 −0
Merged

agents(rules): update python rules with typing and runfiles conventions #4035

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .agents/rules/python.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,22 @@
(e.g. `[missing-import]`) over `tags = ["no-pyrefly"]`.
* **No blanket ignores**: NEVER use bare `# type: ignore` or literal
`# type: ignore[...]`. Use error-specific ignores instead.
* **Ignore comments**: When adding `# pyrefly: ignore[...]` or type
suppressions, add an explanatory comment indicating why it is suppressed.
* **Type assertions**: When adding assertions for type narrowing, add an
end-of-line comment: `assert foo is not None # type assert`.
* **Consent for `Any`**: Require user consent before changing type annotations
to `Any`.
* **Union syntax (`X | None`)**: Use `X | None` instead of `typing.Optional[X]`.
Add `from __future__ import annotations` if necessary.
* **Collections generics**: Use `collections.abc` (e.g., `Sequence`, `Iterable`,
`Iterator`, `Callable`, `Mapping`) and builtin generics (`list`, `dict`,
`tuple`, `set`) instead of `typing.XXX` collection types.

## Runfiles
* **Fail-fast creation**: Prefer `runfiles.CreateOrRaise()` over
`runfiles.Create()` followed by manual `assert` when initializing runfiles in
tests and runtime scripts.

## Delegating Functions
* Module-level functions delegating to class methods should have a docstring
Expand Down