API Reference

Lint Rules

class rattle.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.

configure(raw_settings)
Parameters:

raw_settings (Mapping[str, object])

Return type:

None

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.

Return type:

Mapping[str, Callable[[CSTNode], None]]

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.

Parameters:

node (CSTNode)

Return type:

bool

node_comments(node)

Yield all comments associated with the given node.

Includes comments from both leading comments and trailing inline comments.

Parameters:

node (CSTNode)

Return type:

Generator[str, None, None]

classmethod qualified_name()
Return type:

str

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.

Parameters:
Return type:

None

should_lint_file(source, _path)
Parameters:
Return type:

bool

AUTOFIX = 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.

INVALID: ClassVar[Sequence[str | Invalid]]

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

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

Required LibCST metadata providers

NAME: ClassVar[str] = ''

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

PYTHON_VERSION: str = ''

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

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

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

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

Optional typed configuration settings for this lint rule.

SOURCE_PATTERNS: ClassVar[tuple[SourcePattern, ...]] = ()
TAGS: set[str] = {}

Arbitrary classification tags for use in configuration/selection

VALID: ClassVar[Sequence[str | Valid]]

Test cases that should produce no errors/reports

name: ClassVar[str] = ''

Canonical kebab-case name of this lint rule.

class rattle.RuleSetting(value_type: 'object', default: 'object' = <object object at 0x7b69c7f33d40>, validator: 'Callable[[object], object] | None' = None, description: 'str' = '')
Parameters:
validate(value, *, setting_name, rule_name)
Parameters:
Return type:

object

default: object = <object object>
description: str = ''
validator: Callable[[object], object] | None = None
value_type: object
class rattle.Valid(code: str, options: dict[str, str | int | float | bool | list[Any] | dict[str, Any]] | None = None)
Parameters:
code: str
options: dict[str, str | int | float | bool | list[Any] | dict[str, Any]] | None = None
class rattle.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[Any] | dict[str, Any]] | None = None)
Parameters:
code: str
expected_message: str | None = None
expected_replacement: str | None = None
options: dict[str, str | int | float | bool | list[Any] | dict[str, Any]] | None = None
range: CodeRange | None = None

Frontends

Simple API

rattle.rattle_paths(paths, *, autofix=False, include_diff=False, allow_cached_dirty_results=False, options=None, parallel=True, metrics_hook=None)

Lint multiple files or directories, recursively expanding each path.

Walks all paths given, obeying any .gitignore exclusions, finding Python source files. Lints each file found using rattle_file(), using a process pool when more than one file is being linted.

Yields Result objects for each path, lint error, or exception found. See rattle_bytes() for semantics.

If the first given path is STDIN (Path("-")), then content will be linted from STDIN using rattle_stdin(). The fixed content will be written to STDOUT. A second path argument may be given, which represents the original content’s true path name, and will be used: - to resolve the pyproject.toml configuration - when printing status messages, diffs, or errors. If no second path argument is given, it will default to “stdin” in the current working directory. Any further path names will result in a runtime error.

Note

Currently does not support applying individual fixes when parallel=True, due to limitations in the multiprocessing method in use. Setting parallel=False will enable interactive fixes. Setting autofix=True will always apply fixes automatically during linting.

Parameters:
Return type:

Generator[Result, bool, None]

rattle.rattle_file(path, *, autofix=False, include_diff=False, options=None, explicit_path=False, metrics_hook=None)

Lint a single file on disk, detecting and generating appropriate configuration.

Generates a merged Configuration based on all applicable config files. Reads file from disk as raw bytes, and uses rattle_bytes() to lint and apply any fixes to the content. Writes content back to disk if changes are detected.

Yields Result objects for each lint error or exception found, or a single empty result if the file is clean. See rattle_bytes() for semantics.

Parameters:
Return type:

Generator[Result, bool, None]

rattle.print_result(result, *, show_diff=False, stderr=False, output_format=OutputFormat.rattle, output_template='', brief=False)

Print linting results in a simple format designed for human eyes.

Setting show_diff=True will output autofixes or suggested changes in unified diff format, using ANSI colors when possible.

Returns True if the result is “dirty” - either a lint error or exception.

Parameters:

  • result (Result)

  • show_diff (bool)

  • stderr (bool)

  • output_format (OutputFormat)

  • output_template (str)

  • brief (bool)

Return type:

int

class rattle.LintViolation(rule_name, range, message, node, replacement, diff='', position_node=None)

An individual lint error, with an optional replacement and expected diff.

Parameters:
property autofixable: bool

Whether the violation includes a suggested replacement.

diff: str
message: str
node: CSTNode
position_node: CSTNode | None
range: CodeRange | None
replacement: CSTNode | FlattenSentinel[CSTNode] | RemovalSentinel | None
rule_name: str
class rattle.Result(path, violation, error=None, source=None, config=None)

A single lint result for a given file and lint rule.

Parameters:
classmethod from_exception(path, error, *, source=None, config=None)
Parameters:
Return type:

Result

config: Config | None = None
error: tuple[Exception, str] | None = None
path: Path
source: bytes | None = None
violation: LintViolation | None

Advanced API

rattle.FileContent

alias of bytes

rattle.rattle_bytes(path, content, *, config, autofix=False, include_diff=False, rules=None, metrics_hook=None)

Lint raw bytes content representing a single path, using the given configuration.

Yields Result objects for each lint error or exception found, or a single empty result if the file is clean. A file is considered clean if no lint errors or no rules are enabled for the given path. Returns the final FileContent including any fixes applied.

Use capture() to more easily capture return value after iterating through violations. Use generator.send(...) with a boolean value to apply individual fixes for each violation.

If autofix is True, all violations with replacements will be applied automatically, even if False is sent back to the generator.

Parameters:
Return type:

Generator[Result, bool, bytes | None]

rattle.util.capture

alias of Capture

class rattle.Config(path=<factory>, root=<factory>, excluded=False, enable_root_import=False, enable=<factory>, disable=<factory>, rule_imports=<factory>, options=<factory>, python_version=<factory>, tags=<factory>, formatter='auto', output_format=OutputFormat.rattle, output_template='')

Materialized configuration valid for processing a single file.

Parameters:
disable: list[QualifiedRule | RuleNameSelector]
enable: list[QualifiedRule | RuleNameSelector]
enable_root_import: bool | Path = False
excluded: bool = False
formatter: str | None = 'auto'
options: dict[str, dict[str, str | int | float | bool | list[Any] | dict[str, Any]]]
output_format: OutputFormat = 'rattle'
output_template: str = ''
path: Path
python_version: Version | None
root: Path
rule_imports: list[QualifiedRule | RuleNameSelector]
tags: Tags
class rattle.Options(debug=None, config_file=None, exclude=(), extend_exclude=(), jobs=None, tags=None, rules=(), output_format=None, output_template=None, print_metrics=False, no_format=False)

Command-line options to affect runtime behavior.

Parameters:
config_file: Path | None = None
debug: bool | None = None
exclude: Sequence[str] = ()
extend_exclude: Sequence[str] = ()
jobs: int | None = None
no_format: bool = False
output_format: OutputFormat | None = None
output_template: str | None = None
print_metrics: bool = False
rules: Sequence[QualifiedRule | RuleNameSelector] = ()
tags: Tags | None = None
class rattle.QualifiedRule(module: str, name: str | None = None, local: str | None = None, root: pathlib.Path | None = None)
Parameters:

  • module (str)

  • name (str | None)

  • local (str | None)

  • root (Path | None)

local: str | None = None
module: str
name: str | None = None
root: Path | None = None
class rattle.Tags(include: tuple[str, ...] = (), exclude: tuple[str, ...] = ())
Parameters:
static parse(value)
Parameters:

value (str | None)

Return type:

Tags

exclude: tuple[str, ...] = ()
include: tuple[str, ...] = ()

Formatters

class rattle.Formatter

Rattle post-transform code style and formatting interface.

format(module, _path)

Format the given Module and return it as UTF-8 encoded bytes.

Parameters:
Return type:

bytes

STYLE: str

Short name to identify this formatting style in user configuration. For example: "black".