djavu-asus/emacs/elpy/rpc-venv/lib/python3.11/site-packages/flake8/main/options.py

   1 """Contains the logic for all of the default options for Flake8."""
   2 from __future__ import annotations
   3
   4 import argparse
   5
   6 from flake8 import defaults
   7 from flake8.options.manager import OptionManager
   8
   9
  10 def stage1_arg_parser() -> argparse.ArgumentParser:
  11     """Register the preliminary options on our OptionManager.
  12
  13     The preliminary options include:
  14
  15     - ``-v``/``--verbose``
  16     - ``--output-file``
  17     - ``--append-config``
  18     - ``--config``
  19     - ``--isolated``
  20     - ``--enable-extensions``
  21     """
  22     parser = argparse.ArgumentParser(add_help=False)
  23
  24     parser.add_argument(
  25         "-v",
  26         "--verbose",
  27         default=0,
  28         action="count",
  29         help="Print more information about what is happening in flake8. "
  30         "This option is repeatable and will increase verbosity each "
  31         "time it is repeated.",
  32     )
  33
  34     parser.add_argument(
  35         "--output-file", default=None, help="Redirect report to a file."
  36     )
  37
  38     # Config file options
  39
  40     parser.add_argument(
  41         "--append-config",
  42         action="append",
  43         default=[],
  44         help="Provide extra config files to parse in addition to the files "
  45         "found by Flake8 by default. These files are the last ones read "
  46         "and so they take the highest precedence when multiple files "
  47         "provide the same option.",
  48     )
  49
  50     parser.add_argument(
  51         "--config",
  52         default=None,
  53         help="Path to the config file that will be the authoritative config "
  54         "source. This will cause Flake8 to ignore all other "
  55         "configuration files.",
  56     )
  57
  58     parser.add_argument(
  59         "--isolated",
  60         default=False,
  61         action="store_true",
  62         help="Ignore all configuration files.",
  63     )
  64
  65     # Plugin enablement options
  66
  67     parser.add_argument(
  68         "--enable-extensions",
  69         help="Enable plugins and extensions that are otherwise disabled "
  70         "by default",
  71     )
  72
  73     parser.add_argument(
  74         "--require-plugins",
  75         help="Require specific plugins to be installed before running",
  76     )
  77
  78     return parser
  79
  80
  81 class JobsArgument:
  82     """Type callback for the --jobs argument."""
  83
  84     def __init__(self, arg: str) -> None:
  85         """Parse and validate the --jobs argument.
  86
  87         :param arg: The argument passed by argparse for validation
  88         """
  89         self.is_auto = False
  90         self.n_jobs = -1
  91         if arg == "auto":
  92             self.is_auto = True
  93         elif arg.isdigit():
  94             self.n_jobs = int(arg)
  95         else:
  96             raise argparse.ArgumentTypeError(
  97                 f"{arg!r} must be 'auto' or an integer.",
  98             )
  99
 100     def __repr__(self) -> str:
 101         """Representation for debugging."""
 102         return f"{type(self).__name__}({str(self)!r})"
 103
 104     def __str__(self) -> str:
 105         """Format our JobsArgument class."""
 106         return "auto" if self.is_auto else str(self.n_jobs)
 107
 108
 109 def register_default_options(option_manager: OptionManager) -> None:
 110     """Register the default options on our OptionManager.
 111
 112     The default options include:
 113
 114     - ``-q``/``--quiet``
 115     - ``--color``
 116     - ``--count``
 117     - ``--exclude``
 118     - ``--extend-exclude``
 119     - ``--filename``
 120     - ``--format``
 121     - ``--hang-closing``
 122     - ``--ignore``
 123     - ``--extend-ignore``
 124     - ``--per-file-ignores``
 125     - ``--max-line-length``
 126     - ``--max-doc-length``
 127     - ``--indent-size``
 128     - ``--select``
 129     - ``--extend-select``
 130     - ``--disable-noqa``
 131     - ``--show-source``
 132     - ``--statistics``
 133     - ``--exit-zero``
 134     - ``-j``/``--jobs``
 135     - ``--tee``
 136     - ``--benchmark``
 137     - ``--bug-report``
 138     """
 139     add_option = option_manager.add_option
 140
 141     add_option(
 142         "-q",
 143         "--quiet",
 144         default=0,
 145         action="count",
 146         parse_from_config=True,
 147         help="Report only file names, or nothing. This option is repeatable.",
 148     )
 149
 150     add_option(
 151         "--color",
 152         choices=("auto", "always", "never"),
 153         default="auto",
 154         help="Whether to use color in output.  Defaults to `%(default)s`.",
 155     )
 156
 157     add_option(
 158         "--count",
 159         action="store_true",
 160         parse_from_config=True,
 161         help="Print total number of errors to standard output after "
 162         "all other output.",
 163     )
 164
 165     add_option(
 166         "--exclude",
 167         metavar="patterns",
 168         default=",".join(defaults.EXCLUDE),
 169         comma_separated_list=True,
 170         parse_from_config=True,
 171         normalize_paths=True,
 172         help="Comma-separated list of files or directories to exclude. "
 173         "(Default: %(default)s)",
 174     )
 175
 176     add_option(
 177         "--extend-exclude",
 178         metavar="patterns",
 179         default="",
 180         parse_from_config=True,
 181         comma_separated_list=True,
 182         normalize_paths=True,
 183         help="Comma-separated list of files or directories to add to the list "
 184         "of excluded ones.",
 185     )
 186
 187     add_option(
 188         "--filename",
 189         metavar="patterns",
 190         default="*.py",
 191         parse_from_config=True,
 192         comma_separated_list=True,
 193         help="Only check for filenames matching the patterns in this comma-"
 194         "separated list. (Default: %(default)s)",
 195     )
 196
 197     add_option(
 198         "--stdin-display-name",
 199         default="stdin",
 200         help="The name used when reporting errors from code passed via stdin. "
 201         "This is useful for editors piping the file contents to flake8. "
 202         "(Default: %(default)s)",
 203     )
 204
 205     # TODO(sigmavirus24): Figure out --first/--repeat
 206
 207     # NOTE(sigmavirus24): We can't use choices for this option since users can
 208     # freely provide a format string and that will break if we restrict their
 209     # choices.
 210     add_option(
 211         "--format",
 212         metavar="format",
 213         default="default",
 214         parse_from_config=True,
 215         help=(
 216             f"Format errors according to the chosen formatter "
 217             f"({', '.join(sorted(option_manager.formatter_names))}) "
 218             f"or a format string containing %%-style "
 219             f"mapping keys (code, col, path, row, text). "
 220             f"For example, "
 221             f"``--format=pylint`` or ``--format='%%(path)s %%(code)s'``. "
 222             f"(Default: %(default)s)"
 223         ),
 224     )
 225
 226     add_option(
 227         "--hang-closing",
 228         action="store_true",
 229         parse_from_config=True,
 230         help="Hang closing bracket instead of matching indentation of opening "
 231         "bracket's line.",
 232     )
 233
 234     add_option(
 235         "--ignore",
 236         metavar="errors",
 237         parse_from_config=True,
 238         comma_separated_list=True,
 239         help=(
 240             f"Comma-separated list of error codes to ignore (or skip). "
 241             f"For example, ``--ignore=E4,E51,W234``. "
 242             f"(Default: {','.join(defaults.IGNORE)})"
 243         ),
 244     )
 245
 246     add_option(
 247         "--extend-ignore",
 248         metavar="errors",
 249         parse_from_config=True,
 250         comma_separated_list=True,
 251         help="Comma-separated list of error codes to add to the list of "
 252         "ignored ones. For example, ``--extend-ignore=E4,E51,W234``.",
 253     )
 254
 255     add_option(
 256         "--per-file-ignores",
 257         default="",
 258         parse_from_config=True,
 259         help="A pairing of filenames and violation codes that defines which "
 260         "violations to ignore in a particular file. The filenames can be "
 261         "specified in a manner similar to the ``--exclude`` option and the "
 262         "violations work similarly to the ``--ignore`` and ``--select`` "
 263         "options.",
 264     )
 265
 266     add_option(
 267         "--max-line-length",
 268         type=int,
 269         metavar="n",
 270         default=defaults.MAX_LINE_LENGTH,
 271         parse_from_config=True,
 272         help="Maximum allowed line length for the entirety of this run. "
 273         "(Default: %(default)s)",
 274     )
 275
 276     add_option(
 277         "--max-doc-length",
 278         type=int,
 279         metavar="n",
 280         default=None,
 281         parse_from_config=True,
 282         help="Maximum allowed doc line length for the entirety of this run. "
 283         "(Default: %(default)s)",
 284     )
 285     add_option(
 286         "--indent-size",
 287         type=int,
 288         metavar="n",
 289         default=defaults.INDENT_SIZE,
 290         parse_from_config=True,
 291         help="Number of spaces used for indentation (Default: %(default)s)",
 292     )
 293
 294     add_option(
 295         "--select",
 296         metavar="errors",
 297         parse_from_config=True,
 298         comma_separated_list=True,
 299         help=(
 300             "Limit the reported error codes to codes prefix-matched by this "
 301             "list.  "
 302             "You usually do not need to specify this option as the default "
 303             "includes all installed plugin codes.  "
 304             "For example, ``--select=E4,E51,W234``."
 305         ),
 306     )
 307
 308     add_option(
 309         "--extend-select",
 310         metavar="errors",
 311         parse_from_config=True,
 312         comma_separated_list=True,
 313         help=(
 314             "Add additional error codes to the default ``--select``.  "
 315             "You usually do not need to specify this option as the default "
 316             "includes all installed plugin codes.  "
 317             "For example, ``--extend-select=E4,E51,W234``."
 318         ),
 319     )
 320
 321     add_option(
 322         "--disable-noqa",
 323         default=False,
 324         parse_from_config=True,
 325         action="store_true",
 326         help='Disable the effect of "# noqa". This will report errors on '
 327         'lines with "# noqa" at the end.',
 328     )
 329
 330     # TODO(sigmavirus24): Decide what to do about --show-pep8
 331
 332     add_option(
 333         "--show-source",
 334         action="store_true",
 335         parse_from_config=True,
 336         help="Show the source generate each error or warning.",
 337     )
 338     add_option(
 339         "--no-show-source",
 340         action="store_false",
 341         dest="show_source",
 342         parse_from_config=False,
 343         help="Negate --show-source",
 344     )
 345
 346     add_option(
 347         "--statistics",
 348         action="store_true",
 349         parse_from_config=True,
 350         help="Count errors.",
 351     )
 352
 353     # Flake8 options
 354
 355     add_option(
 356         "--exit-zero",
 357         action="store_true",
 358         help='Exit with status code "0" even if there are errors.',
 359     )
 360
 361     add_option(
 362         "-j",
 363         "--jobs",
 364         default="auto",
 365         parse_from_config=True,
 366         type=JobsArgument,
 367         help="Number of subprocesses to use to run checks in parallel. "
 368         'This is ignored on Windows. The default, "auto", will '
 369         "auto-detect the number of processors available to use. "
 370         "(Default: %(default)s)",
 371     )
 372
 373     add_option(
 374         "--tee",
 375         default=False,
 376         parse_from_config=True,
 377         action="store_true",
 378         help="Write to stdout and output-file.",
 379     )
 380
 381     # Benchmarking
 382
 383     add_option(
 384         "--benchmark",
 385         default=False,
 386         action="store_true",
 387         help="Print benchmark information about this run of Flake8",
 388     )
 389
 390     # Debugging
 391
 392     add_option(
 393         "--bug-report",
 394         action="store_true",
 395         help="Print information necessary when preparing a bug report",
 396     )