pre-commit/flake8
1
0
Fork 0
mirror of https://github.com/PyCQA/flake8.git synced 2026-03-31 19:26:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add a first pass at documenting cli options

Browse source
This commit is contained in:
Ian Cordasco 2016-05-29 20:56:30 -05:00
parent 2fcb222ff9
commit 4c3d176f9a
1 changed files with 604 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

669
docs/source/user/options.rst
View file

@ -4,87 +4,626 @@
Full Listing of Options and Their Descriptions
================================================
..
-v, --verbose Print more information about what is happening in
flake8. This option is repeatable and will increase
verbosity each time it is repeated.
-q, --quiet Report only file names, or nothing. This option is
repeatable.
--count Print total number of errors and warnings to standard
error and set the exit code to 1 if total is not
empty.
--diff Report changes only within line number ranges in the
unified diff provided on standard in by the user.
--exclude=patterns Comma-separated list of files or directories to
exclude.(Default:
.svn,CVS,.bzr,.hg,.git,__pycache__,.tox)
--filename=patterns Only check for filenames matching the patterns in this
comma-separated list. (Default: *.py)
--format=format Format errors according to the chosen formatter.
--hang-closing Hang closing bracket instead of matching indentation
of opening bracket's line.
--ignore=errors Comma-separated list of errors and warnings to ignore
(or skip). For example, ``--ignore=E4,E51,W234``.
(Default: E121,E123,E126,E226,E24,E704)
--max-line-length=n Maximum allowed line length for the entirety of this
run. (Default: 79)
--select=errors Comma-separated list of errors and warnings to enable.
For example, ``--select=E4,E51,W234``. (Default: )
--disable-noqa Disable the effect of "# noqa". This will report
errors on lines with "# noqa" at the end.
--show-source Show the source generate each error or warning.
--statistics Count errors and warnings.
--enable-extensions=ENABLE_EXTENSIONS
Enable plugins and extensions that are otherwise
disabled by default
--exit-zero Exit with status code "0" even if there are errors.
-j JOBS, --jobs=JOBS Number of subprocesses to use to run checks in
parallel. This is ignored on Windows. The default,
"auto", will auto-detect the number of processors
available to use. (Default: auto)
--output-file=OUTPUT_FILE
Redirect report to a file.
--append-config=APPEND_CONFIG
Provide extra config files to parse in addition to the
files found by Flake8 by default. These files are the
last ones read and so they take the highest precedence
when multiple files provide the same option.
--config=CONFIG Path to the config file that will be the authoritative
config source. This will cause Flake8 to ignore all
other configuration files.
--isolated Ignore all found configuration files.
--builtins=BUILTINS define more built-ins, comma separated
--doctests check syntax of the doctests
--include-in-doctest=INCLUDE_IN_DOCTEST
Run doctests only on these files
--exclude-from-doctest=EXCLUDE_FROM_DOCTEST
Skip these files when running doctests
.. program:: flake8
.. option:: --version
When specified on the command-line, this will show :program:`Flake8`\ 's
version as well as the versions of all plugins installed.
Show :program:`Flake8`\ 's version as well as the versions of all plugins
installed.
**This cannot be specified in the config files.**
Command-line usage:
.. prompt:: bash
flake8 --version
This **can not** be specified in the config files.
.. option:: -h, --help
When specified on the command-line, this will show a description of how
to use :program:`Flake8` and it soptions.
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 the config files.
**This cannot be specified in the config files.**
.. option:: -v, --verbose
When specified on the command-line or in configuration, this will
increase the verbosity of Flake8's output. Each time you specify
Increase the verbosity of Flake8's output. Each time you specify
it, it will print more and more information.
**This can be specified in the config file.**
Command-line example:
Example config file specification:
.. prompt:: bash
flake8 -vv
This **can** be specified in the config file.
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 the config file.
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 the config file.
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 the config file.
.. 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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
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 the config file.
.. 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 the config file.
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 the config file.
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 the config file.
.. 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 the config file.
.. 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 the config file.
.. 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 the config file.
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 the config file.
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 the config file.
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 the config file.
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