pre-commit/flake8
1
0
Fork 0
mirror of https://github.com/PyCQA/flake8.git synced 2026-04-08 14:04:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'bug/333' into 'master'

Browse source 
Add documentation for using --select and --ignore seperately and together

See merge request !188
This commit is contained in:
Ian Cordasco 2017-05-30 01:28:01 +00:00
commit 68c6577564
4 changed files with 436 additions and 91 deletions
Download patch file Download diff file Expand all files Collapse all files

90
docs/source/user/ignoring-errors.rst
View file

@ -1,90 +0,0 @@
=============================
Ignoring Errors with Flake8
=============================
By default, |Flake8| has a list of error codes that it ignores. The list used
by a version of |Flake8| may be different than the list used by a different
version. To see the default list, :option:`flake8 --help` will
show the output with the current default list.
Changing the Ignore List
========================
If we want to change the list of ignored codes for a single run, we can use
:option:`flake8 --ignore` to specify a comma-separated list of codes for a
specific run on the command-line, e.g.,
.. prompt:: bash
flake8 --ignore=E1,E23,W503 path/to/files/ path/to/more/files/
This tells |Flake8| to ignore any error codes starting with ``E1``, ``E23``,
or ``W503`` while it is running.
.. note::
The documentation for :option:`flake8 --ignore` shows examples for how
to change the ignore list in the configuration file. See also
:ref:`configuration` as well for details about how to use configuration
files.
In-line Ignoring Errors
=======================
In some cases, we might not want to ignore an error code (or class of error
codes) for the entirety of our project. Instead, we might want to ignore the
specific error code on a specific line. Let's take for example a line like
.. code-block:: python
example = lambda: 'example'
Sometimes we genuinely need something this simple. We could instead define
a function like we normally would. Note, in some contexts this distracts from
what is actually happening. In those cases, we can also do:
.. code-block:: python
example = lambda: 'example' # noqa: E731
This will only ignore the error from pycodestyle that checks for lambda
assignments and generates an ``E731``. If there are other errors on the line
then those will be reported.
.. note::
If we ever want to disable |Flake8| respecting ``# noqa`` comments, we can
can refer to :option:`flake8 --disable-noqa`.
If we instead had more than one error that we wished to ignore, we could
list all of the errors with commas separating them:
.. code-block:: python
# noqa: E731,E123
Finally, if we have a particularly bad line of code, we can ignore every error
using simply ``# noqa`` with nothing after it.
Ignoring Entire Files
=====================
Imagine a situation where we are adding |Flake8| to a codebase. Let's further
imagine that with the exception of a few particularly bad files, we can add
|Flake8| easily and move on with our lives. There are two ways to ignore the
file:
#. By explicitly adding it to our list of excluded paths (see: :option:`flake8
--exclude`)
#. By adding ``# flake8: noqa`` to the file
The former is the **recommended** way of ignoring entire files. By using our
exclude list, we can include it in our configuration file and have one central
place to find what files aren't included in |Flake8| checks. The latter has the
benefit that when we run |Flake8| with :option:`flake8 --disable-noqa` all of
the errors in that file will show up without having to modify our
configuration. Both exist so we can choose which is better for us.

2
docs/source/user/index.rst
View file

@ -24,7 +24,7 @@ This guide will cover all of these and the nuances for using |Flake8|.
configuration
options
error-codes
ignoring-errors
violations
using-plugins
using-hooks
python-api

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

@ -10,6 +10,8 @@
.. option:: --<opt-name>[=<descriptive-name-of-parameter>]
:ref:`Go back to index <top>`
Active description of option's purpose (note that each description
starts with an active verb)
@ -25,10 +27,87 @@
Thank you for your contribution to Flake8's documentation.
.. _top:
Index of Options
================
- :option:`flake8 --version`
- :option:`flake8 --help`
- :option:`flake8 --verbose`
- :option:`flake8 --quiet`
- :option:`flake8 --count`
- :option:`flake8 --diff`
- :option:`flake8 --exclude`
- :option:`flake8 --filename`
- :option:`flake8 --stdin-display-name`
- :option:`flake8 --format`
- :option:`flake8 --hang-closing`
- :option:`flake8 --ignore`
- :option:`flake8 --max-line-length`
- :option:`flake8 --select`
- :option:`flake8 --disable-noqa`
- :option:`flake8 --show-source`
- :option:`flake8 --statistics`
- :option:`flake8 --enable-extensions`
- :option:`flake8 --exit-zero`
- :option:`flake8 --install-hook`
- :option:`flake8 --jobs`
- :option:`flake8 --output-file`
- :option:`flake8 --tee`
- :option:`flake8 --append-config`
- :option:`flake8 --config`
- :option:`flake8 --isolated`
- :option:`flake8 --builtins`
- :option:`flake8 --doctests`
- :option:`flake8 --include-in-doctest`
- :option:`flake8 --exclude-from-doctest`
- :option:`flake8 --benchmark`
- :option:`flake8 --bug-report`
- :option:`flake8 --max-complexity`
Options and their Descriptions
==============================
.. program:: flake8
.. option:: --version
:ref:`Go back to index <top>`
Show |Flake8|'s version as well as the versions of all plugins
installed.
@ -43,6 +122,8 @@
.. option:: -h, --help
:ref:`Go back to index <top>`
Show a description of how to use |Flake8| and its options.
Command-line usage:
@ -57,6 +138,8 @@
.. option:: -v, --verbose
:ref:`Go back to index <top>`
Increase the verbosity of |Flake8|'s output. Each time you specify
it, it will print more and more information.
@ -77,6 +160,8 @@
.. option:: -q, --quiet
:ref:`Go back to index <top>`
Decrease the verbosity of |Flake8|'s output. Each time you specify it,
it will print less and less information.
@ -97,6 +182,8 @@
.. option:: --count
:ref:`Go back to index <top>`
Print the total number of errors.
Command-line example:
@ -116,6 +203,8 @@
.. option:: --diff
:ref:`Go back to index <top>`
Use the unified diff provided on standard in to only check the modified
files and report errors included in the diff.
@ -130,6 +219,8 @@
.. option:: --exclude=<patterns>
:ref:`Go back to index <top>`
Provide a comma-separated list of glob patterns to exclude from checks.
This defaults to: ``.svn,CVS,.bzr,.hg,.git,__pycache__,.tox``
@ -162,6 +253,8 @@
.. option:: --filename=<patterns>
:ref:`Go back to index <top>`
Provide a comma-separate list of glob patterns to include for checks.
This defaults to: ``*.py``
@ -194,6 +287,8 @@
.. option:: --stdin-display-name=<display_name>
:ref:`Go back to index <top>`
Provide the name to use to report warnings and errors from code on stdin.
Instead of reporting an error as something like:
@ -218,6 +313,8 @@
.. option:: --format=<format>
:ref:`Go back to index <top>`
Select the formatter used to display errors to the user.
This defaults to: ``default``
@ -262,6 +359,8 @@
.. option:: --hang-closing
:ref:`Go back to index <top>`
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.
@ -284,6 +383,8 @@
.. option:: --ignore=<errors>
:ref:`Go back to index <top>`
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
@ -317,6 +418,8 @@
.. option:: --max-line-length=<n>
:ref:`Go back to index <top>`
Set the maximum length that any line (with some exceptions) may be.
Exceptions include lines that are either strings or comments which are
@ -349,6 +452,8 @@
.. option:: --select=<errors>
:ref:`Go back to index <top>`
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``,
@ -387,6 +492,8 @@
.. option:: --disable-noqa
:ref:`Go back to index <top>`
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
@ -411,6 +518,8 @@
.. option:: --show-source
:ref:`Go back to index <top>`
Print the source code generating the error/warning in question.
Command-line example:
@ -431,6 +540,8 @@
.. option:: --statistics
:ref:`Go back to index <top>`
Count the number of occurrences of each error/warning code and
print a report.
@ -451,6 +562,8 @@
.. option:: --enable-extensions=<errors>
:ref:`Go back to index <top>`
Enable off-by-default extensions.
Plugins to |Flake8| have the option of registering themselves as
@ -479,6 +592,8 @@
.. option:: --exit-zero
:ref:`Go back to index <top>`
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.
@ -494,6 +609,8 @@
.. option:: --install-hook=VERSION_CONTROL_SYSTEM
:ref:`Go back to index <top>`
Install a hook for your version control system that is executed before
or during commit.
@ -514,6 +631,8 @@
.. option:: --jobs=<n>
:ref:`Go back to index <top>`
Specify the number of subprocesses that |Flake8| will use to run checks in
parallel.
@ -544,6 +663,8 @@
.. option:: --output-file=<path>
:ref:`Go back to index <top>`
Redirect all output to the specified file.
Command-line example:
@ -565,6 +686,8 @@
.. option:: --tee
:ref:`Go back to index <top>`
Also print output to stdout if output-file has been configured.
Command-line example:
@ -585,6 +708,8 @@
.. option:: --append-config=<config>
:ref:`Go back to index <top>`
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
@ -601,6 +726,8 @@
.. option:: --config=<config>
:ref:`Go back to index <top>`
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.
@ -616,6 +743,8 @@
.. option:: --isolated
:ref:`Go back to index <top>`
Ignore any config files and use |Flake8| as if there were no config files
found.
@ -630,6 +759,8 @@
.. option:: --builtins=<builtins>
:ref:`Go back to index <top>`
Provide a custom list of builtin functions, objects, names, etc.
This allows you to let pyflakes know about builtins that it may
@ -658,6 +789,8 @@
.. option:: --doctests
:ref:`Go back to index <top>`
Enable PyFlakes syntax checking of doctests in docstrings.
This is registered by the default PyFlakes plugin.
@ -679,6 +812,8 @@
.. option:: --include-in-doctest=<paths>
:ref:`Go back to index <top>`
Specify which files are checked by PyFlakes for doctest syntax.
This is registered by the default PyFlakes plugin.
@ -705,6 +840,8 @@
.. option:: --exclude-from-doctest=<paths>
:ref:`Go back to index <top>`
Specify which files are not to be checked by PyFlakes for doctest syntax.
This is registered by the default PyFlakes plugin.
@ -731,6 +868,8 @@
.. option:: --benchmark
:ref:`Go back to index <top>`
Collect and print benchmarks for this run of |Flake8|. This aggregates the
total number of:
@ -752,6 +891,8 @@
.. option:: --bug-report
:ref:`Go back to index <top>`
Generate information necessary to file a complete bug report for Flake8.
This will pretty-print a JSON blob that should be copied and pasted into a
bug report for Flake8.
@ -796,3 +937,26 @@
}
This **can not** be specified in config files.
.. option:: --max-complexity=<n>
:ref:`Go back to index <top>`
Set the maximum allowed McCabe complexity value for a block of code.
This option is provided by the ``mccabe`` dependency's |Flake8| plugin.
Command-line usage:
.. prompt:: bash
flake8 --max-complexity 15 dir/
This **can** be specified in config files.
Example config file usage:
.. code-block:: ini
max-complexity = 15

271
docs/source/user/violations.rst Normal file
View file

@ -0,0 +1,271 @@
===================================
Selecting and Ignoring Violations
===================================
It is possible to select and ignore certain violations reported by |Flake8|
and the plugins we've installed. It's also possible as of |Flake8| 3.0 to
combine usage of :option:`flake8 --select` and :option:`flake8 --ignore`. This
chapter of the User Guide aims to educate about how Flake8 will report errors
based on different inputs.
Ignoring Violations with Flake8
===============================
By default, |Flake8| has a list of error codes that it ignores. The list used
by a version of |Flake8| may be different than the list used by a different
version. To see the default list, :option:`flake8 --help` will
show the output with the current default list.
Changing the Ignore List
------------------------
If we want to change the list of ignored codes for a single run, we can use
:option:`flake8 --ignore` to specify a comma-separated list of codes for a
specific run on the command-line, e.g.,
.. prompt:: bash
flake8 --ignore=E1,E23,W503 path/to/files/ path/to/more/files/
This tells |Flake8| to ignore any error codes starting with ``E1``, ``E23``,
or ``W503`` while it is running.
.. note::
The documentation for :option:`flake8 --ignore` shows examples for how
to change the ignore list in the configuration file. See also
:ref:`configuration` as well for details about how to use configuration
files.
In-line Ignoring Errors
-----------------------
In some cases, we might not want to ignore an error code (or class of error
codes) for the entirety of our project. Instead, we might want to ignore the
specific error code on a specific line. Let's take for example a line like
.. code-block:: python
example = lambda: 'example'
Sometimes we genuinely need something this simple. We could instead define
a function like we normally would. Note, in some contexts this distracts from
what is actually happening. In those cases, we can also do:
.. code-block:: python
example = lambda: 'example' # noqa: E731
This will only ignore the error from pycodestyle that checks for lambda
assignments and generates an ``E731``. If there are other errors on the line
then those will be reported.
.. note::
If we ever want to disable |Flake8| respecting ``# noqa`` comments, we can
can refer to :option:`flake8 --disable-noqa`.
If we instead had more than one error that we wished to ignore, we could
list all of the errors with commas separating them:
.. code-block:: python
# noqa: E731,E123
Finally, if we have a particularly bad line of code, we can ignore every error
using simply ``# noqa`` with nothing after it.
Ignoring Entire Files
---------------------
Imagine a situation where we are adding |Flake8| to a codebase. Let's further
imagine that with the exception of a few particularly bad files, we can add
|Flake8| easily and move on with our lives. There are two ways to ignore the
file:
#. By explicitly adding it to our list of excluded paths (see: :option:`flake8
--exclude`)
#. By adding ``# flake8: noqa`` to the file
The former is the **recommended** way of ignoring entire files. By using our
exclude list, we can include it in our configuration file and have one central
place to find what files aren't included in |Flake8| checks. The latter has the
benefit that when we run |Flake8| with :option:`flake8 --disable-noqa` all of
the errors in that file will show up without having to modify our
configuration. Both exist so we can choose which is better for us.
Selecting Violations with Flake8
================================
|Flake8| has a default list of violation classes that we use. This list is:
- ``C90``
All ``C90`` class violations are reported when the user specifies
:option:`flake8 --max-complexity`
- ``E``
All ``E`` class violations are "errors" reported by pycodestyle
- ``F``
All ``F`` class violations are reported by pyflakes
- ``W``
All ``W`` class violations are "warnings" reported by pycodestyle
This list can be overridden by specifying :option:`flake8 --select`. Just as
specifying :option:`flake8 --ignore` will change the behaviour of |Flake8|, so
will :option:`flake8 --select`.
Let's look through some examples using this sample code:
.. code-block:: python
# example.py
def foo():
print(
"Hello"
"World"
)
By default, if we run ``flake8`` on this file we'll get:
.. prompt:: bash
flake8 example.py
.. code:: text
example.py:4:9: E131 continuation line unaligned for hanging indent
Now let's select all ``E`` class violations:
.. prompt:: bash
flake8 --select E example.py
.. code:: text
example.py:3:17: E126 continuation line over-indented for hanging indent
example.py:4:9: E131 continuation line unaligned for hanging indent
example.py:5:9: E121 continuation line under-indented for hanging indent
Suddenly we now have far more erors that are reported to us. Using
``--select`` alone will override the default ``--ignore`` list. In these cases,
the user is telling us that they want all ``E`` violations and so we ignore
our list of violations that we ignore by default.
We can also be highly specific. For example, we can do
.. prompt:: bash
flake8 --select E121 example.py
.. code:: text
example.py:5:9: E121 continuation line under-indented for hanging indent
We can also specify lists of items to select both on the command-line and in
our configuration files.
.. prompt:: bash
flake8 --select E121,E131 example.py
.. code:: text
example.py:4:9: E131 continuation line unaligned for hanging indent
example.py:5:9: E121 continuation line under-indented for hanging indent
Selecting and Ignoring Simultaneously For Fun and Profit
========================================================
Prior to |Flake8| 3.0, all handling of :option:`flake8 --select` and
:option:`flake8 --ignore` was delegated to pycodestyle. It's handling of the
options significantly differs from how |Flake8| 3.0 has been designed.
pycodestyle has always preferred ``--ignore`` over ``--select`` and will
ignore ``--select`` if the user provides both. |Flake8| 3.0 will now do its
best to intuitively combine both options provided by the user. Let's look at
some examples using:
.. code-block:: python
# example.py
import os
def foo():
var = 1
print(
"Hello"
"World"
)
If we run |Flake8| with its default settings we get:
.. prompt:: bash
flake8 example.py
.. code:: text
example.py:1:1: F401 'os' imported but unused
example.py:5:5: F841 local variable 'var' is assigned to but never used
example.py:8:9: E131 continuation line unaligned for hanging indent
Now let's select all ``E`` and ``F`` violations including those in the default
ignore list.
.. prompt:: bash
flake8 --select E,F example.py
.. code:: text
example.py:1:1: F401 'os' imported but unused
example.py:5:5: F841 local variable 'var' is assigned to but never used
example.py:7:17: E126 continuation line over-indented for hanging indent
example.py:8:9: E131 continuation line unaligned for hanging indent
example.py:9:9: E121 continuation line under-indented for hanging indent
Now let's selectively ignore some of these while selecting the rest:
.. prompt:: bash
flake8 --select E,F --ignore F401,E121 example.py
.. code:: text
example.py:5:5: F841 local variable 'var' is assigned to but never used
example.py:7:17: E126 continuation line over-indented for hanging indent
example.py:8:9: E131 continuation line unaligned for hanging indent
Via this example, we can see that the *most specific* **user-specified** rule
will win. So in the above, we had very vague select rules and two very
specific ignore rules. Let's look at a different example:
.. prompt:: bash
flake8 --select F401,E131 --ignore E,F example.py
.. code:: text
example.py:1:1: F401 'os' imported but unused
example.py:8:9: E131 continuation line unaligned for hanging indent
In this case, we see that since our selected violation codes were more
specific those were reported.