loki.lint.linter

Linter operator class definition to drive rule checking for Sourcefile objects

Functions

`check_and_fix_file`(path, linter[, fix, ...])	Check the file at `path` with `linter` and, optionally, fix it
`lint_files`(rules, config[, handlers])	Construct a `Linter` according to `config` and check the rules in `rules`
`lint_files_glob`(linter, basedir, include[, ...])	Discover files relative to `basedir` using patterns in `include` and apply `linter` on each of them.
`lint_files_scheduler`(linter, basedir, config)	Discover files relative to `basedir` using `SchedulerConfig` from `config`, and apply `linter` on each of them.

Classes

`Linter`(reporter, rules[, config])	The operator class for Loki's linter functionality
`LinterTransformation`(linter[, key])	Apply `Linter` as a `Transformation` to `Sourcefile`

class Linter(reporter, rules, config=None)

Bases: object

The operator class for Loki’s linter functionality

It allows to check Sourcefile objects for compliance to rules specified as subclasses of GenericRule.

Parameters:

reporter (Reporter) – The reporter instance to be used for problem reporting.
rules (list of GenericRule or a Python module) – List of rules to check files against or a module that contains the rules.
config (dict, optional) – Configuration (e.g., from config file) to change behaviour of rules.

static lookup_rules(rules_module, rule_names=None)

Obtain all available rule classes in a module

Parameters:

rules_module (Python module) – The module in which rules are implemented.
rule_names (list of str, optional) – Only look for rules with a name that is in this list.

Returns:

A list of rule classes.

Return type:

list

static default_config(rules)

Return default configuration for a list of rules

Parameters:: rules (list) – List of rules for which to compile the default config.
Returns:: Mapping of rule names to the dict of default configuration values for each rule.
Return type:: dict

update_config(config): Update the stored configuration using the given config dict

check(sourcefile, overwrite_rules=None, overwrite_config=None, **kwargs)

Check the given sourcefile and compile a FileReport.

The file report is then stored in the Reporter given while creating the Linter. Additionally, the file report is returned, e.g., to use it wiht fix().

Parameters:

sourcefile (Sourcefile) – The source file to check.
overwrite_rules (list of rules, optional) – List of rules to check. This overwrites the stored list of rules.
overwrite_config (dict, optional) – Configuration that is used to update the stored configuration.

Returns:

The report for this file containing any discovered violations.

Return type:

FileReport

fix(sourcefile, file_report, backup_suffix=None, overwrite_config=None)

Fix all rule violations in file_report that were reported by fixable rules and write them into the original file

Parameters:

sourcefile (Sourcefile) – The source file to fix.
file_report (FileReport) – The report created by check() for that file.
backup_suffix (str, optional) – Create a copy of the original file using this file name suffix.
overwrite_config (dict, optional) – Configuration that is used to update the stored configuration.

class LinterTransformation(linter, key=None, **kwargs)

Bases: Transformation

Apply Linter as a Transformation to Sourcefile

The FileReport is stored in the ``trafo_data` in an Item object, if it is provided to transform_file(), e.g., during a Scheduler traversal.

Parameters:

linter (Linter) – The linter instance to use
key (str, optional) – Lookup key overwrite for stored reports in the trafo_data of Item

traverse_file_graph = True

item_filter: alias of Item

transform_file(sourcefile, **kwargs)

Defines the transformation to apply to Sourcefile items.

For transformations that modify Sourcefile objects, this method should be implemented. It gets called via the dispatch method apply().

Parameters:

sourcefile (Sourcefile) – The sourcefile to be transformed.
**kwargs (optional) – Keyword arguments for the transformation.

lint_files(rules, config, handlers=None)

Construct a Linter according to config and check the rules in rules

Depending on the given config values, this will use a Scheduler to discover files and drive the linting, or apply glob-based file discovery and apply linting to each of them.

Common config options include:

{
    'basedir': <some file path>,
    'max_workers': <n>, # Optional: use multiple workers
    'fix': <True|False>, # Optional: attempt automatic fixing of rule violations
    'backup_suffix': <suffix>, # Optional: Backup original file with given suffix
    'junitxml_file': <some file path>,  # Optional: write JunitXML-output of lint results
    'violations_file': <some file path>,  # Optional: write a YAML file containing violations
    'rules': ['SomeRule', 'AnotherRule', ...],  # Optional: select only these rules
    'SomeRule': <rule options>, # Optional: configuration values for individual rules
 }

The basedir option is given as the discovery path to the Scheduler. See SchedulerConfig for more details on the available config options.

See JunitXmlHandler and ViolationFileHandler for more details on the output file options.

The rules option in the config allows selecting only certain rules out of the provided rules argument.

In addition, config takes for scheduler the following options:

{
    'scheduler': <SchedulerConfig values>
}

If the scheduler key is found in config, the scheduler-based linting is automatically enabled.

For glob-based file discovery, the config takes the following options:

{
    'include': [<some pattern>, <another pattern>, ...]
    'exclude': [<some pattern>] # Optional
}

The include and exclude options are provided to find_paths to discover files that should be linted.

Parameters:

rules (list of GenericRule or a Python module) – List of rules to check files against or a module that contains the rules.
config (dict) – Configuration for file discovery/scheduler and linting rules
handlers (list, optional) – Additional instances of GenericHandler to use during linting

Returns:

The number of checked files

Return type:

int