Skip to content

Allow type checkers to ignore specific error codes #2153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davidhalter merged 10 commits into from
Apr 24, 2026
Merged

Allow type checkers to ignore specific error codes #2153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f4a919a
Allow type: ignore error codes filtering
davidhalter Feb 25, 2026
6ce8087
Try to improve the wording for the spec
davidhalter Mar 2, 2026
5cbcac4
Rephrase a bit of the spec
davidhalter Mar 2, 2026
6856262
Merge remote-tracking branch 'origin/main' into zuban-ignore
davidhalter Apr 14, 2026
ffc8e7c
Avoid specifying how whitespace after # type: ignore works
davidhalter Apr 14, 2026
a0bc8ad
Update conformance/tests/directives_type_ignore.py
davidhalter Apr 15, 2026
614bf60
Update docs/spec/directives.rst
davidhalter Apr 15, 2026
ca781d2
Rerun the tests
davidhalter Apr 16, 2026
d37d815
Change the error code to a random error code and allow the error to h…
davidhalter Apr 16, 2026
a6b55e4
Update conformance/tests/directives_type_ignore.py
davidhalter Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions conformance/results/mypy/directives_type_ignore.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,10 @@ Does not honor "# type: ignore" comment if comment includes additional text.
output = """
directives_type_ignore.py:11: error: Invalid "type: ignore" comment [syntax]
directives_type_ignore.py:11: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]
directives_type_ignore.py:14: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]
directives_type_ignore.py:14: note: Error code "assignment" not covered by "type: ignore" comment
directives_type_ignore.py:16: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]
directives_type_ignore.py:16: note: Error code "assignment" not covered by "type: ignore" comment
"""
conformance_automated = "Fail"
errors_diff = """
Line 11: Unexpected errors ['directives_type_ignore.py:11: error: Invalid "type: ignore" comment [syntax]', 'directives_type_ignore.py:11: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]']
Line 14: Unexpected errors ['directives_type_ignore.py:14: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]']
"""
4 changes: 2 additions & 2 deletions conformance/results/results.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1191,9 +1191,9 @@ <h3>Python Type System Conformance Test Results</h3>
<tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;directives_type_ignore</th>
<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not honor "# type: ignore" comment if comment includes additional text.</p></span></div></th>
<th class="column col2 conformant">Pass</th>
<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not honor "# type: ignore" comment if comment includes additional text.</p></span></div></th>
<th class="column col2 conformant">Pass</th>
<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Treats `# type: ignore[error-code]` as only ignoring errors that match the error code `error-code`.</p></span></div></th>
<th class="column col2 conformant">Pass</th>
<th class="column col2 conformant">Pass</th>
</tr>
<tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;directives_type_ignore_file1</th>
<th class="column col2 conformant">Pass</th>
Expand Down
9 changes: 2 additions & 7 deletions conformance/results/ty/directives_type_ignore.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,6 @@
conformance_automated = "Fail"
conformant = "Partial"
notes = """
Treats `# type: ignore[error-code]` as only ignoring errors that match the error code `error-code`.
"""
conformance_automated = "Pass"
errors_diff = """
Line 14: Unexpected errors ['directives_type_ignore.py:14:10: error[invalid-assignment] Object of type `Literal[""]` is not assignable to `int`']
"""
output = """
directives_type_ignore.py:14:10: error[invalid-assignment] Object of type `Literal[""]` is not assignable to `int`
directives_type_ignore.py:16:10: error[invalid-assignment] Object of type `Literal[""]` is not assignable to `int`
"""
11 changes: 3 additions & 8 deletions conformance/results/zuban/directives_type_ignore.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
conformant = "Partial"
notes = """
Does not honor "# type: ignore" comment if comment includes additional text.
"""
conformance_automated = "Fail"
conformance_automated = "Pass"
errors_diff = """
Line 14: Unexpected errors ['directives_type_ignore.py:14: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]']
"""
output = """
directives_type_ignore.py:14: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]
directives_type_ignore.py:14: note: Error code "assignment" not covered by "type: ignore" comment
directives_type_ignore.py:16: error: Incompatible types in assignment (expression has type "str", variable has type "int") [assignment]
directives_type_ignore.py:16: note: Error code "assignment" not covered by "type: ignore" comment
"""
6 changes: 4 additions & 2 deletions conformance/tests/directives_type_ignore.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@
# The following type violation should be suppressed.
y: int = "" # type: ignore - additional stuff

# The following type violation should be suppressed.
z: int = "" # type: ignore[additional_stuff]
# The following type violation may be suppressed, if the type checker
# actually uses the code `an-empty-str-is-not-an-int` (unlikely!), or if
# it treats unknown codes as blanket ignores.
z: int = "" # type: ignore[an-empty-str-is-not-an-int] # E?

# > 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
Expand Down
9 changes: 9 additions & 0 deletions docs/spec/directives.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,15 @@ other comments and linting markers:

# type: ignore # <comment or other marker>

The form ``# type: ignore[...]`` may be used to suppress only type errors with a
given error code, though support for this is optional and may vary by type checker:
Copy link
Copy Markdown
Contributor

@JukkaL JukkaL Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about also documenting that multiple error codes can be given (comma-separated), and unrecognized error codes should be ignored, if a type checker supports ignoring errors based on specific error code, as @ilevkivskyi suggested here.

Copy link
Copy Markdown
Collaborator Author

@davidhalter davidhalter Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any other opinions on this? I'm pretty open to changes here.

I personally think that the comma separated form doesn't need to be specified explicitly.

unrecognized error codes should be ignored, if a type checker supports ignoring errors based on specific error code

Does this mean that Mypy would need to ignore the error code "undefined"? Currently it adds errors at least when using --warn-unused-ignores: https://mypy-play.net/?mypy=latest&python=3.12&flags=warn-unused-ignores&gist=27ebc9511f193a9f348b0235412cbcc9

Copy link
Copy Markdown
Member

@carljm carljm Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally think that the approach outlined by @ilevkivskyi is the right one for multi-type-checker interoperability (much better than requiring totally separate ignore comments for each type checker), and I would be happy to fully specify it. But that would be a specification change that puts pyright and pyrefly out of conformance. If we did that, then I think the fulI behavior, including multiple comma separated codes, should be specified. I guess maybe we need feedback at least from pyrefly here: is the "always blanket ignore" behavior pyrefly's UX preference, or just something that was done to satisfy the previous conformance suite requirements?

But I think as long as the specification here is looser, as currently written (to accommodate both the pyright/pyrefly behavior and the mypy/zuban/ty behavior), it's not really important to document the multiple-error-codes handling, since effectively all this spec is now saying is that type checkers can do whatever they want with the information inside the brackets.

(Either way, I don't think the spec should _require_that type checkers be silent about unknown codes; it should be OK to warn users about them, as mypy does with --warn-unused-ignores. This is better behavior for users who aren't using multiple type checkers. Ideally users in multi-type-checker scenarios can turn off that warning if they don't want it.)

I'm happy with the current state of this PR as a first step, at least.

Copy link
Copy Markdown
Collaborator

@rchen152 rchen152 Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with the current wording in this PR.

As for @ilevkivskyi's suggestion - I personally like it, but I'd like to run this by some other pyrefly devs who have thought a lot more than I have about configuration and adoption, to make sure this isn't incompatible with our tooling in some way that I'm missing.

Copy link
Copy Markdown
Collaborator

@rchen152 rchen152 Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As for @ilevkivskyi's suggestion - I personally like it, but I'd like to run this by some other pyrefly devs [...]

We discussed this and flagged a couple questions/concerns:

  • Are there any plans to standardize what lines errors are reported on? Without standardization there, this proposed change seems less useful, since multiple # type: ignores on different lines would still be needed to satisfy multiple type checkers.
  • Pyrefly has a --remove-unused-ignores flag to remove # pyrefly: ignore directives that are no longer used (useful for automated pyrefly version upgrades). This would be trickier in a world in which every type checker uses # type: ignore, since error codes could be used by other checkers rather than unused.

Copy link
Copy Markdown
Member

@carljm carljm Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably move this to a Discuss thread if someone wants to champion actually specifying the multiple-codes-in-type-ignore approach. I think the issues raised by the Pyrefly team are definitely real ones.

Regarding the first, I would just say that it's already a minority of type errors where checkers vary on the reported line, so the proposal is still a strict improvement for the ~90+% where type checkers naturally agree (because there's no real ambiguity). So some effort to standardize more of course wouldn't hurt, but this doesn't seem like a blocker.

Regarding the second, what ty does is expect all our codes in # type: ignore[...] to be prefixed with ty:, so we can still flag/remove all unused definitely-for-ty ignores, which is on par with what we can do with # ty: ignore. Whether we should ever remove (or flag as unused) ignores which might apply to other type checkers, is I think a UX question for each type checker. Might be useful for single-type-checker users, but definitely not desirable for multi-type-checker users, so at best it would need to be configurable.


- Given ``# 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, given ``# type: ignore[my_code1]`` a type checker may suppress the
error only if the error cause matches the error code ``my_code1``.
- A bare ``# type: ignore`` must always suppress all type errors.

.. _`cast`:

``cast()``
Expand Down