python / python/mypy

MyPy fails type narrowing on `not issubclass(X, type[T]): raise`

Open
#19,917 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Bug Report

MyPy fails to narrow types using issubclass, and expects an isinstance check which is wrong.

MyPy fails type narrowing on not issubclass(X, type[T]): raise and complains about returning X() later for the function marked as returning T.

To Reproduce

[Mypy Playground example](https://gist.github.com/mypy-play/dcd17343b289523c197a31f850eca90f)

```python from collections.abc import Iterator from typing import TYPE_CHECKING

class MySentinel:
    pass

# Works as expected
class OptionalSentinel:
    def __init__(self, value: object) -> None:
        self._value = value

    def get_value[T](self, expected: type[T]) -> Iterator[T]:
        if not isinstance(self._value, expected):
            raise TypeError

        yield self._value

# Reveals bug
class MagicIterator:
    def raw[T](self, expected: type[T]) -> Iterator[T]:
        """Get a list of repositories which accept a specific lint to run."""
        if not issubclass(MySentinel, expected):
            raise ValueError

        # if TYPE_CHECKING:
        #     # an ugly workaround to make mypy happy
        #     if not isinstance(expected, MySentinel):
        #         raise ValueError

        for project in [MySentinel(), MySentinel()]:
            yield project  # error: Incompatible types in "yield" (actual type "MySentinel", expected type "T")  [misc]
```

Expected Behavior

I expected mypy to infer that after an if not issubclass(T, X): raise block X must be subclass T and it should be ok to return X in place of T.

Since I pass a type and want to compare it to a type an isinstance check is not appropriate for MagicIterator, neiter o I think the issubclass check is the most appropriate (I would prefer to check using expected is not T to guarantee that expected is actually exactly T but ìs`i not listed in the list of supported narrowing expressions.

Actual Behavior

Mypy is only happy if I add an isinstance check, which I deem wrong since I dont pass an instance but a type to the function. Thus, if I do not put the incorrect code in a if TYPE_CHECKCING block my program crashes

src/typeTest.py:31: error: Incompatible types in "yield" (actual type "MySentinel", expected type "T")  [misc]
Found 1 error in 1 file (checked 1 source file)

Your Environment

  • Mypy version used: mypy 1.18.2 (compiled: yes)
  • Mypy command-line flags: none (mypy src)
  • Mypy configuration options from pyproject.toml (and other config files):
  • Python version used: 3.13.7 (uv)

** Possibly related **:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked MyPy Playground example and compare the failing issubclass narrowing path with the working isinstance example. Read related issues #10680, #19529, #9003, and #17728 before locating the relevant narrowing tests and implementation; done means the example type-checks without the incorrect runtime workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.