Frontends

Simple API

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.

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.

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.

Advanced API

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.

capture

alias of Capture