Document error codes (#7451)

There's a general page about what error pages and for, and I document each error code that is supported, often with code examples.
python · Sep 18, 2019 · 0c2ec6a · 0c2ec6a
1 parent 85b04c1
commit 0c2ec6a
Show file tree

Hide file tree

Showing 8 changed files with 878 additions and 3 deletions.
diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
@@ -497,12 +497,20 @@ in error messages.
         main.py:3: error: Unsupported operand types for + ("int" and "str")
 
 ``--show-column-numbers``
-    This flag will add column offsets to error messages,
-    for example, the following indicates an error in line 12, column 9
+    This flag will add column offsets to error messages.
+    For example, the following indicates an error in line 12, column 9
     (note that column offsets are 0-based)::
 
         main.py:12:9: error: Unsupported operand types for / ("int" and "str")
 
+``--show-error-codes``
+    This flag will add an error code ``[<code>]`` to error messages. The error
+    code is shown after each error message::
+
+        prog.py:1: error: "str" has no attribute "trim"  [attr-defined]
+
+    See :ref:`error-codes` for more information.
+
 ``--no-color-output``
     This flag will disable color output in error messages, enabled by default.
 

diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
@@ -124,6 +124,14 @@ error:
 The second line is now fine, since the ignore comment causes the name
 ``frobnicate`` to get an implicit ``Any`` type.
 
+.. note::
+
+    You can use the form ``# type: ignore[<code>]`` to only ignore
+    specific errors on the line. This way you are less likely to
+    silence unexpected errors that are not safe to ignore, and this
+    will also document what the purpose of the comment is.  See
+    :ref:`error-codes` for more information.
+
 .. note::
 
     The ``# type: ignore`` comment will only assign the implicit ``Any``

diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
@@ -441,12 +441,16 @@ section of the command line docs.
 ``show_column_numbers`` (bool, default False)
     Shows column numbers in error messages.
 
+``show_error_codes`` (bool, default False)
+    Shows error codes in error messages. See :ref:`error-codes` for more information.
+
 ``color_output`` (bool, default True)
     Shows error messages with color enabled.
 
 ``error_summary`` (bool, default True)
     Shows a short summary line after error messages.
 
+
 Advanced options
 ----------------