comments and documentation

Author: wyattscarpenter

CHANGELOG.md

@@ -56,6 +56,14 @@ may necessitate changing the location of a `# type: ignore` comment.
 Contributed by Shantanu Jain (PR [18392](https://github.com/python/mypy/pull/18392),
 PR [18397](https://github.com/python/mypy/pull/18397)).
 
+### `mypy: ignore`
+
+`mypy: ignore` comments are now honored by mypy exactly as though they said `type: ignore`.
+This allows one to suppress type errors from mypy in particular, without suppressing other type checkers,
+which can be desirable if mypy has a bug and other type checkers one runs on the same code do not.
+
+Contributed by Wyatt S Carpenter (PR [17875](https://github.com/python/mypy/pull/17875)).
+
 ## Mypy 1.14
 
 We’ve just uploaded mypy 1.14 to the Python Package Index ([PyPI](https://pypi.org/project/mypy/)).

docs/source/common_issues.rst

@@ -148,21 +148,31 @@ 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``
     type if mypy cannot find information about that particular module. So,
     if we did have a stub available for ``frobnicate`` then mypy would
     ignore the ``# type: ignore`` comment and typecheck the stub as usual.
 
+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.
+
+Instead of ``# type: ignore``, you may also use the mypy-specific
+``# mypy: ignore``, to tell only mypy — and not other type checkers — to
+ignore that line. This is mostly useful if mypy has a bug that produces
+known-spurious error messages. You may also use the ``# mypy: ignore[<code>]``
+form to only ignore specific errors. Indeed, it is often wisest to use
+``# mypy: ignore[<code>]``, as this minimizes your chances of accidentally
+suppressing other errors that you don't really want to ignore!
+
+(``# mypy: ignore`` comments are per-line and should not be confused with
+:ref:`inline-configuration` comments, which are per-file configuration directives
+that just happen to be formatted a similar way.)
+
 Another option is to explicitly annotate values with type ``Any`` --
 mypy will let you perform arbitrary operations on ``Any``
 values. Sometimes there is no more precise type you can use for a

mypy/fastparse.py

@@ -140,16 +140,18 @@ def ast3_parse(
     source: str | bytes, filename: str, mode: str, feature_version: int = PY_MINOR_VERSION
 ) -> AST:
     """This function is just a convenience wrapper around ast.parse, with default flags useful to Mypy.
-    It also incorporates a hack to accomodate `# mypy: ignore` comments, which are treated by mypy as `# type: ignore` comments.
+    It also handles `# mypy: ignore` comments, by turning them into `# type: ignore` comments.
     """
     # Hack to support "mypy: ignore" comments until the builtin compile function changes to allow us to detect it otherwise:
-    # (Note: completely distinct from https://mypy.readthedocs.io/en/stable/inline_config.html ; see also, util.get_mypy_comments in this codebase)
+    # (Note: completely distinct from https://mypy.readthedocs.io/en/stable/inline_config.html ; see also, util.get_mypy_comments in this codebase.)
 
     # We make the substitution in comments, and to find those comments we use Python's `tokenize`.
     # https://docs.python.org/3/library/tokenize.html has a big red **Warning:**
-    #     Note that the functions in this module are only designed to parse syntactically valid Python code (code that does not raise when parsed using ast.parse()). The behavior of the functions in this module is **undefined** when providing invalid Python code and it can change at any point.
+    #     Note that the functions in this module are only designed to parse syntactically valid Python
+    #     code (code that does not raise when parsed using ast.parse()). The behavior of the functions
+    #     in this module is **undefined** when providing invalid Python code and it can change at any point.
     # So, we cannot rely on roundtrip behavior in tokenize iff ast.parse would throw when given `source`.
-    # The simplest way to deal with that is just to call ast.parse twice, once before and once after. So, we do that.
+    # The simplest way to deal with that is just to call ast.parse twice, once before and once after!
     def p() -> AST:
         return ast3.parse(
             source, filename, mode, type_comments=True, feature_version=feature_version
@@ -160,11 +162,12 @@ def p() -> AST:
         tokens = tokenize.generate_tokens(io.StringIO(source).readline)
     else:
         tokens = tokenize.tokenize(io.BytesIO(source).readline)
-    # We do a workaround for a roundtripping error https://github.com/python/cpython/issues/125008
-    # An error that was introduced in 3.12.3 (https://github.com/python/cpython/blob/v3.12.3/Lib/tokenize.py#L205) and fixed in 3.12.8 (not out yet at time of writing but it's probably https://github.com/python/cpython/blob/v3.12.8/Lib/tokenize.py#L203 or thereabouts).
+    # We do a workaround for a roundtripping error (https://github.com/python/cpython/issues/125008)
+    # that was introduced in 3.12.3 (https://github.com/python/cpython/blob/v3.12.3/Lib/tokenize.py#L205)
+    # and fixed in 3.12.8 (https://github.com/python/cpython/blob/v3.12.8/Lib/tokenize.py#L205).
     # Luckily, it was caught before the first official (non-rc) release of python 3.13.
     is_defective_version = (3, 12, 3) <= sys.version_info[:3] <= (3, 12, 7)
-    # Could the workaround ever come back to bite us? I confess I don't know enough about FSTRING_MIDDLE to say no for certain, even though I have tried to examine all relevant cases.
+    # This is a gnarly list comprehension, but that's basically just how untokenize is supposed to work.
     source = tokenize.untokenize(
         (
             t,
@@ -182,11 +185,11 @@ def p() -> AST:
                     else s
                 )
             ),
-            *_,  # this improves whitespace roundtripping (possibly always making it perfect, for this usecase?)
+            *_,  # Including this bit improves whitespace roundtripping (possibly always making it perfect).
         )
         for t, s, *_ in tokens
     )
-    return p()
+    return p() # `source` has changed, so this result is different than the first call.
 
 
 NamedExpr = ast3.NamedExpr