Documentation: --warn-unreachable should clarify special handling of pass statements

Documentation
The documentation for the --warn-unreachable flag currently does not mention that unreachable blocks containing only a pass statement are silently ignored and do not trigger a warning. This creates confusion.

The current documentation lists two specific cases where unreachable statements are silenced:

When the statement raises an error or terminates the program.
When the statement is intentionally marked with platform/version checks.
The behavior for pass is a third, distinct case that is not documented.

Link: https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-warn-unreachable

reference: #20251

Not just pass: that should be pass, ..., assert False, return NotImplemented (kind of exceptional, because that's how operator dunders are typically type hinted), raise Something and assert_never kind of things (but I don't remember how generic the implementation of the last one is).

Grep for is_noop_for_reachability function if you want to mention all those cases in the docs (it's probably in checker.py), or maybe we could say smth like "if the block is trivial or is equivalent to immediately raising an error" to avoid listing them verbatim and just give a hint that some blocks are ignored intentionally.

Not just pass: that should be pass, ..., assert False, return NotImplemented (kind of exceptional, because that's how operator dunders are typically type hinted), raise Something and assert_never kind of things (but I don't remember how generic the implementation of the last one is).

Grep for is_noop_for_reachability function if you want to mention all those cases in the docs (it's probably in checker.py), or maybe we could say smth like "if the block is trivial or is equivalent to immediately raising an error" to avoid listing them verbatim and just give a hint that some blocks are ignored intentionally.

I'm leaning towards either listing them all or providing a general description that also references the is_noop_for_reachability function.

@sterliakov

Not just pass: that should be pass, ..., assert False, return NotImplemented (kind of exceptional, because that's how operator dunders are typically type hinted), raise Something and assert_never kind of things (but I don't remember how generic the implementation of the last one is).
Grep for is_noop_for_reachability function if you want to mention all those cases in the docs (it's probably in checker.py), or maybe we could say smth like "if the block is trivial or is equivalent to immediately raising an error" to avoid listing them verbatim and just give a hint that some blocks are ignored intentionally.

I'm leaning towards either listing them all or providing a general description that also references the is_noop_for_reachability function.

@sterliakov I'd like to submit a PR to fix this documentation gap.To make sure I get it right, could you clarify which documentation approach you prefer?

Document unreachability handling of `return NotImplemented` (#20561)

Navigation Menu

Repository navigation

Documentation: --warn-unreachable should clarify special handling of pass statements #20462

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Documentation: --warn-unreachable should clarify special handling of pass statements #20462

Description

Activity

nocoding03 commented on Dec 23, 2025

sterliakov commented on Dec 23, 2025

nocoding03 commented on Dec 24, 2025

nocoding03 commented on Dec 25, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions