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.
- 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:
node (CSTNode) –
message (str | None) –
position (CodePosition | CodeRange | None) –
replacement (CSTNode | FlattenSentinel | RemovalSentinel | None) –
- Return type:
None
- AUTOFIX = False¶
Whether the lint rule contains an autofix.
Set to
True
automatically whenINVALID
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.
- VALID: ClassVar[List[str | ValidTestCase]]¶
Test cases that should produce no errors/reports
- class fixit.InvalidTestCase(code: str, range: libcst._position.CodeRange | NoneType = None, expected_message: str | NoneType = None, expected_replacement: str | NoneType = None)¶
- Parameters:
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 usingfixit_file()
, using a process pool when more than one file is being linted.Yields
Result
objects for each path, lint error, or exception found. Seefixit_bytes()
for semantics.Note
Currently does not support applying individual fixes when
parallel=True
, due to limitations in the multiprocessing method in use. Settingparallel=False
will enable interactive fixes. Settingautofix=True
will always apply fixes automatically during linting.
- 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. Seefixit_bytes()
for semantics.
- 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.
- class fixit.LintViolation(rule_name, range, message, node, replacement, diff='')¶
An individual lint error, with an optional replacement and expected diff.
- Parameters:
rule_name (str) –
range (CodeRange) –
message (str) –
node (CSTNode) –
replacement (CSTNode | FlattenSentinel | RemovalSentinel | None) –
diff (str) –
- replacement: CSTNode | FlattenSentinel | RemovalSentinel | None¶
Advanced API¶
- 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 finalFileContent
including any fixes applied.Use
capture()
to more easily capture return value after iterating through violations. Usegenerator.send(...)
with a boolean value to apply individual fixes for each violation.If
autofix
isTrue
, all violations with replacements will be applied automatically, even ifFalse
is sent back to the generator.
- 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]¶
- class fixit.QualifiedRule(module: str, name: str | NoneType = None, local: str | NoneType = None, root: pathlib.Path | NoneType = None)¶