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

Package metadata is generated from pyproject.toml.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sarj_python_lint-0.58.0-py3-none-any.whl (361.2 kB view details)

Uploaded Aug 9, 2026 Python 3

File details

Details for the file sarj_python_lint-0.58.0-py3-none-any.whl.

File metadata

Download URL: sarj_python_lint-0.58.0-py3-none-any.whl
Upload date: Aug 9, 2026
Size: 361.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sarj_python_lint-0.58.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`3fd72a290dbe355ee088cde0d7cc9c47d5ce48f27bc611f214c4d75965b5567e`
MD5	`9715e3295a6f3ed4429c5f43ae1439db`
BLAKE2b-256	`27a0faef8d36d90aa480b971c938a320f6d08ee51cc73b765070fb5fdd123196`

See more details on using hashes here.

Provenance

The following attestation bundles were made for sarj_python_lint-0.58.0-py3-none-any.whl:

Publisher: release.yml on sarj-ai/standards

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: sarj_python_lint-0.58.0-py3-none-any.whl
- Subject digest: 3fd72a290dbe355ee088cde0d7cc9c47d5ce48f27bc611f214c4d75965b5567e
- Sigstore transparency entry: 2387646779
- Sigstore integration time: Aug 9, 2026
Source repository:
- Permalink: sarj-ai/standards@c9b56c912344573c0c5140b10d9fa9e9f30f0753
- Branch / Tag: refs/heads/main
- Owner: https://github.com/sarj-ai
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c9b56c912344573c0c5140b10d9fa9e9f30f0753
- Trigger Event: push