mirror of
https://github.com/PyCQA/flake8.git
synced 2026-03-30 18:56:53 +00:00
650 lines
13 KiB
ReStructuredText
650 lines
13 KiB
ReStructuredText
.. _options-list:
|
|
|
|
================================================
|
|
Full Listing of Options and Their Descriptions
|
|
================================================
|
|
|
|
..
|
|
NOTE(sigmavirus24): When adding new options here, please follow the
|
|
following _rough_ template:
|
|
|
|
.. option:: --<opt-name>[=<descriptive-name-of-parameter>]
|
|
|
|
Active description of option's purpose (note that each description
|
|
starts with an active verb)
|
|
|
|
Command-line usage:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --<opt-name>[=<example-parameter(s)>] [positional params]
|
|
|
|
This **can[ not]** be specified in config files.
|
|
|
|
(If it can be, an example using .. code-block:: ini)
|
|
|
|
Thank you for your contribution to Flake8's documentation.
|
|
|
|
.. program:: flake8
|
|
|
|
.. option:: --version
|
|
|
|
Show :program:`Flake8`\ 's version as well as the versions of all plugins
|
|
installed.
|
|
|
|
Command-line usage:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --version
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: -h, --help
|
|
|
|
Show a description of how to use :program:`Flake8` and its options.
|
|
|
|
Command-line usage:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --help
|
|
flake8 -h
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: -v, --verbose
|
|
|
|
Increase the verbosity of Flake8's output. Each time you specify
|
|
it, it will print more and more information.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 -vv
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
verbose = 2
|
|
|
|
|
|
.. option:: -q, --quiet
|
|
|
|
Decrease the verbosity of Flake8's output. Each time you specify it,
|
|
it will print less and less information.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 -q
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
quiet = 1
|
|
|
|
|
|
.. option:: --count
|
|
|
|
Print the total number of errors.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --count dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
count = True
|
|
|
|
|
|
.. option:: --diff
|
|
|
|
Use the unified diff provided on standard in to only check the modified
|
|
files and report errors included in the diff.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
git diff -u | flake8 --diff
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: --exclude=<patterns>
|
|
|
|
Provide a comma-separated list of glob patterns to exclude from checks.
|
|
|
|
This defaults to: ``.svn,CVS,.bzr,.hg,.git,__pycache__,.tox``
|
|
|
|
Example patterns:
|
|
|
|
- ``*.pyc`` will match any file that ends with ``.pyc``
|
|
|
|
- ``__pycache__`` will match any path that has ``__pycache__`` in it
|
|
|
|
- ``lib/python`` will look expand that using :func:`os.path.abspath` and
|
|
look for matching paths
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --exclude=*.pyc dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
exclude =
|
|
.tox,
|
|
__pycache__
|
|
|
|
|
|
.. option:: --filename=<patterns>
|
|
|
|
Provide a comma-separate list of glob patterns to include for checks.
|
|
|
|
This defaults to: ``*.py``
|
|
|
|
Example patterns:
|
|
|
|
- ``*.py`` will match any file that ends with ``.py``
|
|
|
|
- ``__pycache__`` will match any path that has ``__pycache__`` in it
|
|
|
|
- ``lib/python`` will look expand that using :func:`os.path.abspath` and
|
|
look for matching paths
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --filename=*.py dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
filename =
|
|
example.py,
|
|
another-example*.py
|
|
|
|
|
|
.. option:: --format=<format>
|
|
|
|
Select the formatter used to display errors to the user.
|
|
|
|
This defaults to: ``default``
|
|
|
|
By default, there are two formatters available:
|
|
|
|
- default
|
|
|
|
- pylint
|
|
|
|
Other formatters can be installed. Refer to their documentation for the
|
|
name to use to select them.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --format=pylint dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
format=pylint
|
|
|
|
|
|
.. option:: --hang-closing
|
|
|
|
Toggle whether pycodestyle should enforce matching the indentation of the
|
|
opening bracket's line. When you specify this, it will prefer that you
|
|
hang the closing bracket rather than match the indentation.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --hang-closing dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
hang_closing = True
|
|
hang-closing = True
|
|
|
|
|
|
.. option:: --ignore=<errors>
|
|
|
|
Specify a list of codes to ignore. The list is expected to be
|
|
comma-separated, and does not need to specify an error code exactly.
|
|
Since Flake8 3.0, this **can** be combined with :option:`--select`. See
|
|
:option:`--select` for more information.
|
|
|
|
For example, if you wish to only ignore ``W234``, then you can specify
|
|
that. But if you want to ignore all codes that start with ``W23`` you
|
|
need only specify ``W23`` to ignore them. This also works for ``W2`` and
|
|
``W`` (for example).
|
|
|
|
This defaults to: ``E121,E123,E126,E226,E24,E704``
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --ignore=E121,E123 dir/
|
|
flake8 --ignore=E24,E704 dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
ignore =
|
|
E121,
|
|
E123
|
|
ignore = E121,E123
|
|
|
|
|
|
.. option:: --max-line-length=<n>
|
|
|
|
Set the maximum length that any line (with some exceptions) may be.
|
|
|
|
Exceptions include lines that are either strings or comments which are
|
|
entirely URLs. For example:
|
|
|
|
.. code-block:: python
|
|
|
|
# https://some-super-long-domain-name.com/with/some/very/long/path
|
|
|
|
url = (
|
|
'http://...'
|
|
)
|
|
|
|
This defaults to: 79
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --max-line-length 99 dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
max-line-length = 79
|
|
|
|
|
|
.. option:: --select=<errors>
|
|
|
|
Specify the list of error codes you wish Flake8 to report. Similarly to
|
|
:option:`--ignore`. You can specify a portion of an error code to get all
|
|
that start with that string. For example, you can use ``E``, ``E4``,
|
|
``E43``, and ``E431``.
|
|
|
|
This has no default value.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --select=E431,E5,W,F dir/
|
|
flake8 --select=E,W dir/
|
|
|
|
This can also be combined with :option:`--ignore`:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --select=E --ignore=E432 dir/
|
|
|
|
This will report all codes that start with ``E``, but ignore ``E432``
|
|
specifically. This is more flexibly than the Flake8 2.x and 1.x used
|
|
to be.
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
select =
|
|
E431,
|
|
W,
|
|
F
|
|
|
|
|
|
.. option:: --disable-noqa
|
|
|
|
Report all errors, even if it is on the same line as a ``# NOQA`` comment.
|
|
``# NOQA`` can be used to silence messages on specific lines. Sometimes,
|
|
users will want to see what errors are being silenced without editing the
|
|
file. This option allows you to see all the warnings, errors, etc.
|
|
reported.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --disable-noqa dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
disable_noqa = True
|
|
disable-noqa = True
|
|
|
|
|
|
.. option:: --show-source
|
|
|
|
Print the source code generating the error/warning in question.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --show-source dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
show_source = True
|
|
show-source = True
|
|
|
|
|
|
.. option:: --statistics
|
|
|
|
Count the number of occurrences of each error/warning code and
|
|
print a report.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --statistics
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
statistics = True
|
|
|
|
|
|
.. option:: --enable-extensions=<errors>
|
|
|
|
Enable off-by-default extensions.
|
|
|
|
Plugins to Flake8 have the option of registering themselves as
|
|
off-by-default. These plugins effectively add themselves to the
|
|
default ignore list.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --enable-extensions=H111 dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
enable-extensions =
|
|
H111,
|
|
G123
|
|
enable_extensions =
|
|
H111,
|
|
G123
|
|
|
|
|
|
.. option:: --exit-zero
|
|
|
|
Force Flake8 to use the exit status code 0 even if there are errors.
|
|
|
|
By default Flake8 will exit with a non-zero integer if there are errors.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --exit-zero dir/
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: --jobs=<n>
|
|
|
|
Specify the number of subprocesses that Flake8 will use to run checks in
|
|
parallel.
|
|
|
|
.. note::
|
|
|
|
This option is ignored on Windows because :mod:`multiprocessing` does
|
|
not support Windows across all supported versions of Python.
|
|
|
|
This defaults to: ``auto``
|
|
|
|
The default behaviour will use the number of CPUs on your machine as
|
|
reported by :func:`multiprocessing.cpu_count`.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --jobs=8 dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
jobs = 8
|
|
|
|
|
|
.. option:: --output-file=<path>
|
|
|
|
Redirect all output to the specified file.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --output-file=output.txt dir/
|
|
flake8 -vv --output-file=output.txt dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
output-file = output.txt
|
|
output_file = output.txt
|
|
|
|
|
|
.. option:: --append-config=<config>
|
|
|
|
Provide extra config files to parse in after and in addition to the files
|
|
that Flake8 found on its own. Since these files are the last ones read
|
|
into the Configuration Parser, so it has the highest precedence if it
|
|
provides an option specified in another config file.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --append-config=my-extra-config.ini dir/
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: --config=<config>
|
|
|
|
Provide a path to a config file that will be the only config file read and
|
|
used. This will cause Flake8 to ignore all other config files that exist.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --config=my-only-config.ini dir/
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: --isolated
|
|
|
|
Ignore any config files and use Flake8 as if there were no config files
|
|
found.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --isolated dir/
|
|
|
|
This **can not** be specified in config files.
|
|
|
|
|
|
.. option:: --builtins=<builtins>
|
|
|
|
Provide a custom list of builtin functions, objects, names, etc.
|
|
|
|
This allows you to let pyflakes know about builtins that it may
|
|
not immediately recognize so it does not report warnings for using
|
|
an undefined name.
|
|
|
|
This is registered by the default PyFlakes plugin.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --builtins=_,_LE,_LW dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
builtins =
|
|
_,
|
|
_LE,
|
|
_LW
|
|
|
|
|
|
.. option:: --doctests
|
|
|
|
Enable PyFlakes syntax checking of doctests in docstrings.
|
|
|
|
This is registered by the default PyFlakes plugin.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --doctests dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
doctests = True
|
|
|
|
|
|
.. option:: --include-in-doctest=<paths>
|
|
|
|
Specify which files are checked by PyFlakes for doctest syntax.
|
|
|
|
This is registered by the default PyFlakes plugin.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --include-in-doctest=dir/subdir/file.py,dir/other/file.py dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
include-in-doctest =
|
|
dir/subdir/file.py,
|
|
dir/other/file.py
|
|
include_in_doctest =
|
|
dir/subdir/file.py,
|
|
dir/other/file.py
|
|
|
|
|
|
.. option:: --exclude-from-doctest=<paths>
|
|
|
|
Specify which files are not to be checked by PyFlakes for doctest syntax.
|
|
|
|
This is registered by the default PyFlakes plugin.
|
|
|
|
Command-line example:
|
|
|
|
.. prompt:: bash
|
|
|
|
flake8 --exclude-in-doctest=dir/subdir/file.py,dir/other/file.py dir/
|
|
|
|
This **can** be specified in config files.
|
|
|
|
Example config file usage:
|
|
|
|
.. code-block:: ini
|
|
|
|
exclude-in-doctest =
|
|
dir/subdir/file.py,
|
|
dir/other/file.py
|
|
exclude_in_doctest =
|
|
dir/subdir/file.py,
|
|
dir/other/file.py
|