Metadata-Version: 2.4
Name: sarj-python-lint
Version: 0.58.0
Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
Project-URL: Repository, https://github.com/sarj-ai/standards
Project-URL: Issues, https://github.com/sarj-ai/standards/issues
Author: sarj-ai
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.14
Description-Content-Type: text/markdown

<!-- Generated by `sarj-standards maintain docs sync`; do not edit. -->

# sarj-python-lint

Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults

## Package metadata

| Field | Value |
| --- | --- |
| Version | `0.58.0` |
| Registry | PyPI |
| License | MIT |
| Runtime | `Python >=3.14` |

## Command-line reference

| Command | Entrypoint | Help |
| --- | --- | --- |
| `sarj-python-lint` | `sarj_python_lint.__main__:main` | `sarj-python-lint --help` |
| `sarj-ratchet` | `sarj_python_lint._ratchet_cli:main` | `sarj-ratchet --help` |

## Rule catalog

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

## Project links

- [Homepage](https://code-standards.sarj.ai/rules/python/)
- [Issues](https://github.com/sarj-ai/standards/issues)
- [Repository](https://github.com/sarj-ai/standards)

Package metadata is generated from [`pyproject.toml`](pyproject.toml).
