ENGINE / PYTHON

Python rules

79 deterministic checks, ordered by canonical rule ID.

Find a rule / Clear

79 rules

Rule	Engine	Category	Default
conditional-assertion-in-test Tests should guarantee that at least one assertion runs on every execution path.	Python	testing	error
defect-xfail-requires-strict Bug-pinning `xfail` without `strict=True` — an XPASS reports as a pass and the pin rots.	Python	testing	error
docstring-args-restate-signature Argument documentation must add facts beyond the function signature.	Python	maintainability	error
docstring-returns-restate-signature Return documentation must add facts beyond the function name and annotation.	Python	maintainability	error
duplicate-test-body Similar test bodies should be represented as one named parameterized case table.	Python	testing	error
duplicated-override-docstring Remove an override docstring copied verbatim from its local base method.	Python	maintainability	error
fastapi-openapi-contract FastAPI operations must publish explicit request, response, and OpenAPI contracts.	Python	correctness	error
fixture-returns-bare-tuple Fixture returns a bare multi-field tuple — return a NamedTuple so consumers destructure by name.	Python	testing	error
interaction-only-test Tests should verify outcomes, not only mock interaction bookkeeping.	Python	testing	error
invalid-pydantic-field-default Require literal Pydantic `Field` defaults to satisfy their declared contract.	Python	correctness	error
kwarg-heavy-construction-in-test Object built with many keywords inline in a test — extract a helper with defaults.	Python	testing	error
mock-without-spec Mock built without `spec=`/`autospec=` — it accepts any attribute and cannot rot loudly.	Python	testing	error
no-aggregation-in-store-query Postgres store queries should not perform analytical aggregation.	Python	architecture	error
no-comment-cruft Comment repeats code, preserves dead code, or adds a decorative section marker.	Python	maintainability	error
no-cors-wildcard-with-credentials Credentialed CORS must not allow a wildcard origin.	Python	security	error
no-duplicate-dunder-all-entry static package `__all__` declarations should list each exported name once	Python	correctness	error
no-fat-try-blocks Keep a `try` body narrow enough to identify which operation a handler covers.	Python	correctness	error
no-file-level-escape-hatch-noqa File-level Ruff noqa suppresses an escape-hatch rule across the entire file.	Python	maintainability	error
no-file-level-suppression Unscoped file-level suppressions disable a checker for the entire file, including diagnostics added later.	Python	maintainability	error
no-first-party-private-import Code imports a private name or module from another first-party package.	Python	architecture	error
no-frozen-after-validator-field-write Do not assign declared fields in after-validators on frozen Pydantic models.	Python	correctness	error
no-gen-random-uuid-in-sql Embedded SQL calls gen_random_uuid() instead of uuidv7().	Python	performance	error
no-generic-single-export-module A generic module with one public definition should be named after that definition.	Python	architecture	error
no-hidden-constructor-fallback Constructor option silently falls back to application settings when omitted.	Python	architecture	error
no-isinstance-union-chain Use exhaustive pattern matching for dispatch over a local closed class union.	Python	correctness	error
no-long-comment Long docstrings must use deliberate documentation structure or technical anchors.	Python	maintainability	error
no-offset-pagination Store queries should use keyset cursors instead of `OFFSET` pagination.	Python	performance	error
no-optional-tenant-predicate Tenant predicate is added only conditionally, allowing an unscoped query.	Python	security	error
no-query-with-many-joins Store queries should use at most two explicit or implicit joins.	Python	architecture	error
no-raw-sql-in-tests Tests should seed records through store or service methods instead of raw SQL inserts.	Python	testing	error
no-repeated-string-literal Structured string literals repeated across functions should use a module constant.	Python	maintainability	error
no-restated-comment Comment restates the statement immediately below it.	Python	maintainability	error
no-secret-in-log Secret-like value is passed to a logging call under a secret-like keyword.	Python	security	error
no-select-star Store queries should select explicit columns instead of `*`.	Python	maintainability	error
no-sentinel-return-on-except Exception handler silently converts a failure into a sentinel return value.	Python	correctness	error
no-sleep-in-test-body Tests should synchronize on observable state instead of waiting a fixed duration.	Python	testing	error
no-stdlib-logging Application code imports standard-library logging instead of the configured house logger.	Python	architecture	error
no-string-concat-in-loop Do not grow one string with repeated concatenation inside a loop.	Python	performance	error
no-tautological-expect Assertion outcome is fixed entirely by literal values.	Python	testing	error
no-typed-doc-sections Docstring sections must not repeat types already present in a fully typed signature.	Python	maintainability	error
opaque-parametrize-case-needs-id Opaque `parametrize` case with no `ids=`/`id=` — the failing case reports as `case0`.	Python	testing	error
over-mocked-test Tests should not replace more than five distinct collaborators.	Python	testing	error
prefer-class-row Use a validated model row instead of Psycopg `dict_row`.	Python	correctness	error
prefer-constant-time-secret-compare Secret-like values are compared with timing-sensitive equality operators.	Python	security	error
prefer-fstring-over-concat Build short strings with f-strings instead of concatenating literals and known strings.	Python	style	error
prefer-immutable-module-constant module-level constant collections expose mutable shared state; use tuple, frozenset, or an immutable mapping	Python	maintainability	error
prefer-library-fake Tests should use maintained service fakes or emulators instead of hand-rolled third-party doubles.	Python	testing	error
prefer-match-assert-never Closed-set dispatch should fail explicitly when a variant is unhandled.	Python	correctness	error
prefer-match-type-dispatch Use `match` for explicit runtime type dispatch instead of branching parser machinery.	Python	maintainability	error
prefer-module-level-constant Literal-only collections and compiled regular expressions built inside a function should be module-level constants.	Python	performance	error
prefer-namedtuple-over-tuple-return Public functions should return named records instead of fixed positional tuples.	Python	maintainability	error
prefer-nominal-id-types Production boundaries with multiple ID roles must distinguish them with nominal types.	Python	correctness	error
prefer-non-nullable-collection Avoid nullable list parameters when local use proves `None` and an empty list are equivalent.	Python	correctness	error
prefer-or-pattern Merge adjacent `case` arms with identical bodies into one or-pattern.	Python	maintainability	error
prefer-real-store-in-tests Tests should exercise the real persistence implementation instead of an in-memory reimplementation.	Python	testing	error
prefer-self-documenting-constant Encode a constant's units or HTTP status meaning in its name, type, or value.	Python	maintainability	error
prefer-self-type-annotation Annotate fluent methods and alternate constructors with `Self`.	Python	correctness	error
prefer-str-enum Represent corroborated closed string domains with `StrEnum` or a named `Literal` alias.	Python	correctness	error
prefer-struct-over-namedtuple `collections.namedtuple` creates an untyped, positionally constructed record.	Python	maintainability	error
prefer-timedelta-for-durations Duration-bearing name is typed as a raw integer or float.	Python	correctness	error
prefer-walrus-comprehension-filter Evaluate a repeated comprehension call once with a named expression.	Python	performance	error
prefer-walrus-regex-match Bind a regex result in the `if` condition that immediately tests it.	Python	style	error
prefer-walrus-stream-loop Bind each stream value in the `while` condition instead of using an explicit break.	Python	maintainability	error
pydantic-at-boundaries Public function or route returns a fixed-shape untyped dictionary.	Python	architecture	error
redundant-class-docstring Class docstrings must add information beyond the class name and bases.	Python	maintainability	error
redundant-docstring Docstring only restates the signature — delete the whole docstring or document behavior callers cannot infer.	Python	maintainability	error
redundant-module-docstring Module docstrings must add information beyond the file path.	Python	maintainability	error
require-keyword-only-swap-prone-params Swap-prone parameters with the same primitive type should be keyword-only.	Python	correctness	error
require-port-for-service Consider a consumer-owned port for a service with a behaviorally used collaborator.	Python	architecture	error
restated-test-docstring Test docstrings must add information beyond the test name and body.	Python	testing	error
sleep-with-computed-arg-in-test Computed `sleep()` in a test body — synchronize on the signal, don't guess a delay.	Python	testing	error
stepdown A private helper used by one caller should be defined below that caller.	Python	maintainability	error
store-insert-requires-on-conflict Embedded SQL inserts in store code must handle conflicts explicitly.	Python	correctness	error
test-loops-over-literal-cases Test loops over a literal case table — use `@pytest.mark.parametrize` so cases report separately.	Python	testing	error
test-phase-label-comment Tests must not use bare Arrange, Act, Assert, Given, When, or Then phase comments.	Python	testing	error
trailing-value-narration Trailing comment restates a literal value and its unit.	Python	maintainability	error
trivially-true-assertion Assertions should depend on behavior rather than echoing values supplied by the test.	Python	testing	error
unused-mock-setup Tests should remove mock configuration that cannot affect execution.	Python	testing	error
zero-assertion-test Test contains no assertion of any kind — it passes as long as nothing raises.	Python	testing	error