djavu-asus/elpy/rpc-venv/lib/python3.11/site-packages/flake8/api/legacy.py

   1 """Module containing shims around Flake8 2.x behaviour.
   2
   3 Previously, users would import :func:`get_style_guide` from ``flake8.engine``.
   4 In 3.0 we no longer have an "engine" module but we maintain the API from it.
   5 """
   6 from __future__ import annotations
   7
   8 import argparse
   9 import logging
  10 import os.path
  11 from typing import Any
  12
  13 from flake8.discover_files import expand_paths
  14 from flake8.formatting import base as formatter
  15 from flake8.main import application as app
  16 from flake8.options.parse_args import parse_args
  17
  18 LOG = logging.getLogger(__name__)
  19
  20
  21 __all__ = ("get_style_guide",)
  22
  23
  24 class Report:
  25     """Public facing object that mimic's Flake8 2.0's API.
  26
  27     .. note::
  28
  29         There are important changes in how this object behaves compared to
  30         the object provided in Flake8 2.x.
  31
  32     .. warning::
  33
  34         This should not be instantiated by users.
  35
  36     .. versionchanged:: 3.0.0
  37     """
  38
  39     def __init__(self, application: app.Application) -> None:
  40         """Initialize the Report for the user.
  41
  42         .. warning:: This should not be instantiated by users.
  43         """
  44         assert application.guide is not None
  45         self._application = application
  46         self._style_guide = application.guide
  47         self._stats = self._style_guide.stats
  48
  49     @property
  50     def total_errors(self) -> int:
  51         """Return the total number of errors."""
  52         return self._application.result_count
  53
  54     def get_statistics(self, violation: str) -> list[str]:
  55         """Get the list of occurrences of a violation.
  56
  57         :returns:
  58             List of occurrences of a violation formatted as:
  59             {Count} {Error Code} {Message}, e.g.,
  60             ``8 E531 Some error message about the error``
  61         """
  62         return [
  63             f"{s.count} {s.error_code} {s.message}"
  64             for s in self._stats.statistics_for(violation)
  65         ]
  66
  67
  68 class StyleGuide:
  69     """Public facing object that mimic's Flake8 2.0's StyleGuide.
  70
  71     .. note::
  72
  73         There are important changes in how this object behaves compared to
  74         the StyleGuide object provided in Flake8 2.x.
  75
  76     .. warning::
  77
  78         This object should not be instantiated directly by users.
  79
  80     .. versionchanged:: 3.0.0
  81     """
  82
  83     def __init__(self, application: app.Application) -> None:
  84         """Initialize our StyleGuide."""
  85         self._application = application
  86         self._file_checker_manager = application.file_checker_manager
  87
  88     @property
  89     def options(self) -> argparse.Namespace:
  90         """Return application's options.
  91
  92         An instance of :class:`argparse.Namespace` containing parsed options.
  93         """
  94         assert self._application.options is not None
  95         return self._application.options
  96
  97     @property
  98     def paths(self) -> list[str]:
  99         """Return the extra arguments passed as paths."""
 100         assert self._application.options is not None
 101         return self._application.options.filenames
 102
 103     def check_files(self, paths: list[str] | None = None) -> Report:
 104         """Run collected checks on the files provided.
 105
 106         This will check the files passed in and return a :class:`Report`
 107         instance.
 108
 109         :param paths:
 110             List of filenames (or paths) to check.
 111         :returns:
 112             Object that mimic's Flake8 2.0's Reporter class.
 113         """
 114         assert self._application.options is not None
 115         self._application.options.filenames = paths
 116         self._application.run_checks()
 117         self._application.report_errors()
 118         return Report(self._application)
 119
 120     def excluded(self, filename: str, parent: str | None = None) -> bool:
 121         """Determine if a file is excluded.
 122
 123         :param filename:
 124             Path to the file to check if it is excluded.
 125         :param parent:
 126             Name of the parent directory containing the file.
 127         :returns:
 128             True if the filename is excluded, False otherwise.
 129         """
 130
 131         def excluded(path: str) -> bool:
 132             paths = tuple(
 133                 expand_paths(
 134                     paths=[path],
 135                     stdin_display_name=self.options.stdin_display_name,
 136                     filename_patterns=self.options.filename,
 137                     exclude=self.options.exclude,
 138                 )
 139             )
 140             return not paths
 141
 142         return excluded(filename) or (
 143             parent is not None and excluded(os.path.join(parent, filename))
 144         )
 145
 146     def init_report(
 147         self,
 148         reporter: type[formatter.BaseFormatter] | None = None,
 149     ) -> None:
 150         """Set up a formatter for this run of Flake8."""
 151         if reporter is None:
 152             return
 153         if not issubclass(reporter, formatter.BaseFormatter):
 154             raise ValueError(
 155                 "Report should be subclass of "
 156                 "flake8.formatter.BaseFormatter."
 157             )
 158         self._application.formatter = reporter(self.options)
 159         self._application.guide = None
 160         # NOTE(sigmavirus24): This isn't the intended use of
 161         # Application#make_guide but it works pretty well.
 162         # Stop cringing... I know it's gross.
 163         self._application.make_guide()
 164         self._application.file_checker_manager = None
 165         self._application.make_file_checker_manager([])
 166
 167     def input_file(
 168         self,
 169         filename: str,
 170         lines: Any | None = None,
 171         expected: Any | None = None,
 172         line_offset: Any | None = 0,
 173     ) -> Report:
 174         """Run collected checks on a single file.
 175
 176         This will check the file passed in and return a :class:`Report`
 177         instance.
 178
 179         :param filename:
 180             The path to the file to check.
 181         :param lines:
 182             Ignored since Flake8 3.0.
 183         :param expected:
 184             Ignored since Flake8 3.0.
 185         :param line_offset:
 186             Ignored since Flake8 3.0.
 187         :returns:
 188             Object that mimic's Flake8 2.0's Reporter class.
 189         """
 190         return self.check_files([filename])
 191
 192
 193 def get_style_guide(**kwargs: Any) -> StyleGuide:
 194     r"""Provision a StyleGuide for use.
 195
 196     :param \*\*kwargs:
 197         Keyword arguments that provide some options for the StyleGuide.
 198     :returns:
 199         An initialized StyleGuide
 200     """
 201     application = app.Application()
 202     application.plugins, application.options = parse_args([])
 203     # We basically want application.initialize to be called but with these
 204     # options set instead before we make our formatter, notifier, internal
 205     # style guide and file checker manager.
 206     options = application.options
 207     for key, value in kwargs.items():
 208         try:
 209             getattr(options, key)
 210             setattr(options, key, value)
 211         except AttributeError:
 212             LOG.error('Could not update option "%s"', key)
 213     application.make_formatter()
 214     application.make_guide()
 215     application.make_file_checker_manager([])
 216     return StyleGuide(application)