Merge branch 'bug/333' into 'master'

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

See merge request !188

4 files changed, 436 insertions, 91 deletions

diff --git a/docs/source/user/ignoring-errors.rst b/docs/source/user/ignoring-errors.rst
deleted file mode 100644
index ff37c4a..0000000
--- a/docs/source/user/ignoring-errors.rst
+++ /dev/null
@@ -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.
diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst
index e0f9108..5a24b21 100644
--- a/docs/source/user/index.rst
+++ b/docs/source/user/index.rst
@@ -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
diff --git a/docs/source/user/options.rst b/docs/source/user/options.rst
index 6252c09..4922c1a 100644
--- a/docs/source/user/options.rst
+++ b/docs/source/user/options.rst
@@ -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
diff --git a/docs/source/user/violations.rst b/docs/source/user/violations.rst
new file mode 100644
index 0000000..ed44c94
--- /dev/null
+++ b/docs/source/user/violations.rst
@@ -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.