Allow type checkers to ignore specific error codes

conformance/tests/directives_type_ignore.py

@@ -10,8 +10,12 @@
 # The following type violation should be suppressed.
 y: int = ""  # type: ignore - additional stuff
 
+# The following type violations should not be suppressed.
+y: int = ""  # type: ignored  # E: Unexpected word "ignored"
+y: int = ""  # type: ignored, foo  # E: Unexpected comma
+
 # The following type violation should be suppressed.
-z: int = ""  # type: ignore[additional_stuff]
+z: int = ""  # type: ignore[assignment]
 
 # > In some cases, linting tools or other comments may be needed on the same
 # > line as a type comment. In these cases, the type comment should be before

docs/spec/directives.rst

@@ -73,6 +73,25 @@ other comments and linting markers:
 
   # type: ignore # <comment or other marker>
 
+Text following ``# type: ignore`` must be ignored, provided there is at
+least one whitespace character after it::
+
+    # Not valid because of the "d" after ignore; does not supress the type error
+    s: str = 1  # type: ignored
+    # Not valid because of the comma; does not supress the type error
+    s: str = 1  # type: ignore, because I feel like it
+    # This is valid because of the whitespace and must suppress the type error
+    s: str = 1  # type: ignore because why not
+
+The form of ``# type: ignore[...]`` may be used to filter errors depending on
+the type checker:
+
+- In ``# type: ignore[my_code1]``, a type checker may ignore the error code
+  ``my_code1`` and choose to treat this form as equivalent to ``# type: ignore``.
+- Alternatively in ``# type: ignore[my_code1]`` a type checker may suppress the
+  error only if the error cause matches the error code ``my_code1``.
+- ``# type: ignore`` must always suppress all errors.
+
 .. _`cast`:
 
 ``cast()``