API Reference

Lint Rules

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

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]]

report(node, message=None, *, position=None, replacement=None)

Report a lint rule violation.

If message is not provided, self.MESSAGE will be used as a violation message. If neither of them are available, this method raises ValueError.

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

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 replacment.

INVALID: ClassVar[List[str | InvalidTestCase]]

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

METADATA_DEPENDENCIES: ClassVar[Collection[ProviderT]] = (<class 'libcst.metadata.position_provider.PositionProvider'>,)

The set of metadata dependencies declared by this class.

TAGS: Set[str] = {}

Arbitrary classification tags for use in configuration/selection

VALID: ClassVar[List[str | ValidTestCase]]

Test cases that should produce no errors/reports

class fixit.ValidTestCase(code: str)
Parameters:

code (str) –

code: str
class fixit.InvalidTestCase(code: str, range: libcst._position.CodeRange | NoneType = None, expected_message: str | NoneType = None, expected_replacement: str | NoneType = None)
Parameters:

  • code (str) –

  • range (CodeRange | None) –

  • expected_message (str | None) –

  • expected_replacement (str | None) –

code: str
expected_message: str | None = None
expected_replacement: str | None = None
range: CodeRange | None = None

Frontends

Simple API

fixit.fixit_paths(paths, *, autofix=False, parallel=True)

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 fixit_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 fixit_bytes() for semantics.

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]

fixit.fixit_file(path, *, autofix=False)

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 fixit_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 fixit_bytes() for semantics.

Parameters:
Return type:

Generator[Result, bool, None]

fixit.print_result(result, show_diff=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:
Return type:

int

class fixit.LintViolation(rule_name, range, message, node, replacement, diff='')

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
range: CodeRange
replacement: CSTNode | FlattenSentinel | RemovalSentinel | None
rule_name: str
class fixit.Result(path, violation, error=None)

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

Parameters:
error: Tuple[Exception, str] | None = None
path: Path
violation: LintViolation | None

Advanced API

fixit.ftypes.FileContent

alias of bytes

fixit.fixit_bytes(path, content, *, config, autofix=False)

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. 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]

class fixit.util.capture(generator)

Wrap a generator, and capture it’s final return value in the result property.

Allows sending values back to the generator using the respond() method.

Example usage:

generator = capture( fixit_bytes(...) )
for result in generator:  # LintViolation
    ...
    generator.respond(...)  # optional

result = generator.result  # FileContent
respond(answer)

Send a value back to the generator in the next iteration.

Can be called while iterating on the wrapped generator object.

Parameters:

answer (Send) –

Return type:

None

property result: Return

Contains the final return value from the wrapped generator, if any.

class fixit.Config(path=<factory>, root=<factory>, enable=<factory>, disable=<factory>, options=<factory>)

Materialized configuration valid for processing a single file.

Parameters:
disable: List[QualifiedRule]
enable: List[QualifiedRule]
options: Dict[str, Dict[str, str | int | float]]
path: Path
root: Path
class fixit.QualifiedRule(module: str, name: str | NoneType = None, local: str | NoneType = None, root: pathlib.Path | NoneType = 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