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

Start writing new documentation around --select

Browse source 
In order to write this documentation, we need to also add documentation
for the --max-complexity option which was heretofore undocumented.
This commit is contained in:
Ian Cordasco 2017-05-29 20:07:13 -05:00
parent fec980a856
commit d411ced0f6
No known key found for this signature in database
GPG key ID: 656D3395E4A9791A
4 changed files with 293 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

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

@ -796,3 +796,24 @@
}
This **can not** be specified in config files.
.. option:: --max-complexity=<n>
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.