# 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