Rules

Rule Base Classes

class LintRule

Lint rule implemented using LibCST.

To build a new lint rule, subclass this and Implement a CST visitor. When a lint rule violation should be reported, use the report() method.

MESSAGE: str = ''

Human-readable diagnostic message or formatting template.

METADATA_DEPENDENCIES: ClassVar[Collection[ProviderT]] = ()

Required LibCST metadata providers

TAGS: ClassVar[set[str]] = {}

Arbitrary classification tags for use in configuration/selection

NAME: ClassVar[str] = ''

Explicit public rule name. Defaults to kebab-case generated from the class name.

PYTHON_VERSION: ClassVar[str] = ''

Compatible target Python versions, in PEP 440 version specifier format.

VALID: ClassVar[Sequence[str | Valid]] = ()

Test cases that should produce no errors/reports

INVALID: ClassVar[Sequence[str | Invalid]] = ()

Test cases that are expected to produce errors, with optional replacements

SETTINGS: ClassVar[dict[str, RuleSetting]] = {}

Optional typed configuration settings for this lint rule.

REFERENCES: ClassVar[Sequence[RuleReference]] = ()

External references for documentation, as URLs or (label, URL) pairs.

SOURCE_PATTERNS: ClassVar[tuple[SourcePattern, ...]] = ()

AUTOFIX: ClassVar[bool] = False

Whether the lint rule contains an autofix.

Set to True automatically when INVALID contains at least one test case that provides an expected replacement.

name: ClassVar[str] = ''

Canonical kebab-case name of this lint rule.

classmethod qualified_name()

should_lint_file(source, _path)

setting(name, value_type)

Return a configured setting after retaining its runtime-validated type.

configure(raw_settings)

node_comments(node)

Yield all comments associated with the given node.

Includes comments from both leading comments and trailing inline comments.

ignore_lint(node)

Whether to ignore a violation for a given node.

Returns true if any # rattle: ignore[...] directive matches the current rule by name, or if the directive has no rule names listed.

report(

node,

message,

*,

position=None,

position_node=None,

replacement=None,

)

Report a lint rule violation.

The optional position parameter can override the location where the violation is reported. By default, the entire span of node is used. If position is a CodePosition, only a single character is marked.

The optional replacement parameter can be used to provide an auto-fix for this lint violation. Replacing node with replacement should make the lint violation go away.

get_visitors()

Returns a mapping of all the visit_<Type[CSTNode]>, visit_<Type[CSTNode]>_<attribute>, leave_<Type[CSTNode]> and leave_<Type[CSTNode]>_<attribute>` methods defined by this visitor, excluding all empty stubs.

class RuleSetting

RuleSetting(value_type: ‘type[T]’, default: ‘T | object’ = <object object at 0x76e9273e7a80>, validator: ‘Callable[[T], object] | None’ = None, description: ‘str’ = ‘’)

value_type: type[T]

default: T | object = <object object>

validator: Callable[[T], object] | None = None

description: str = ''

validate(value, *, setting_name, rule_name)

Rule Test Cases

class Valid

Valid(code: str, options: dict[str, str | int | float | bool | list[‘RuleOptionValue’] | dict[str, ‘RuleOptionValue’]] | None = None)

code: str

options: dict[str, str | int | float | bool | list[RuleOptionValue] | dict[str, RuleOptionValue]] | None = None

class Invalid

Invalid(code: str, range: libcst._position.CodeRange | None = None, expected_message: str | None = None, expected_replacement: str | None = None, options: dict[str, str | int | float | bool | list[‘RuleOptionValue’] | dict[str, ‘RuleOptionValue’]] | None = None)

code: str

range: CodeRange | None = None

expected_message: str | None = None

expected_replacement: str | None = None

options: dict[str, str | int | float | bool | list[RuleOptionValue] | dict[str, RuleOptionValue]] | None = None

Rule Metadata

RuleReference = str | tuple[str, str]

Represent a PEP 604 union type

E.g. for int | str

Optional AST Analysis

class AstProvider

Provide a cached CPython AST for the current LibCST module.

visit_Module(node)

class AstContext

A parsed Python AST and source-aware conversion to Rattle code ranges.

tree: Module

code_range(node)

Return the Rattle source range for a positioned AST node.

class AstParseError

Raised when the running Python interpreter cannot build a requested AST.