René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Mypy doesn't narrow a matched object's type (generic or not) based on attribute subpattern match","articleBody":"# Bug Report\n\n## Summary\n\n### TLDR\n\nMypy doesn't narrow a parent object's type when subpattern-matching on one of its attributes.\n\n### Longer summary\n\nMypy doesn't always use [attribute sub-pattern matches](https://peps.python.org/pep-0636/#matching-positional-attributes) (e.g. `case Err(ValueError())`) to narrow the parent object (e.g. `Err[ValueError | AttributeError]` isn't narrowed to `Err[ValueError]`). This prevents an error-free type-level exhaustiveness check using `assert_never` after matching all possible patterns.\n\nSome of the examples below show that mypy successfully narrows the attribute itself, but doesn't propagate this narrowing up to the object being matched, even when there's a generic type argument that could be narrowed. E.g. if `val` is narrowed to `ValueError`, mypy should be able to narrow the object from `Err[ValueError | AttributeError]` to `Err[ValueError]`.\n\nIdeally, in the `case _` after exhausting all patterns/subpatterns, the object could be narrowed to `Never`.\n\nIt's possible that it's expected that mypy can't narrow a non-generic type, if it needs a type argument that can explicitly be narrowed. I've included a non-generic example below anyway though, for completeness, since it does have all its patterns matched but fails the exhaustiveness check.\n\n### Context\n\nThe real-world context for this issue was an attempt to pattern match on [poltergeist's `Result = Ok[_T] | Err[_E]` type](https://github.com/alexandermalyga/poltergeist/blob/main/poltergeist/result.py), where Err can be constrained to a specific subset of exceptions. Finishing a `match result:` statement with `case _: assert_never(result)` only works if we avoid matching error sub-patterns: i.e. if we do `case Err(err)` and avoid `case Err(ValueError())`.\n\nIn this context, this issue takes away from some of the potential power of a library like poltergeist, which seeks to make error handling more explicit and type-safe.\n\nI guess a workaround could be to just add a nested `match` statement on `err._value` itself within the `case Err(err)` block. But that feels unfortunate to have to do when `match` was built to be powerful around subpattern matching, and [PEP 636 – Structural Pattern Matching: Tutorial](https://peps.python.org/pep-0636/#composing-patterns) states that \"Patterns can be nested within each other\" (which is the case here, it's just the type-checking that doesn't use all the type info it has).\n\n## To Reproduce\n\n### Example 1: Result (generic)\n\nHere, I'd expect mypy to narrow the type of `result`, e.g. to `Err[ValueError]` inside the `case Err(ValueError() as val)` block, and to `Never` inside the `case _` block.\n\n```python\nSuccessType = TypeVar(\"SuccessType\")\nFailureType = TypeVar(\"FailureType\")\n\n\nclass Ok(Generic[SuccessType]):\n    __match_args__ = (\"_value\",)\n\n    def __init__(self, value: SuccessType) -\u003e None:\n        self._value = value\n\n\nclass Err(Generic[FailureType]):\n    __match_args__ = (\"_value\",)\n\n    def __init__(self, value: FailureType) -\u003e None:\n        self._value = value\n\n\nResult = Ok[SuccessType] | Err[FailureType]\n\n\ndef handle_result(result: Result[str, ValueError | AttributeError]) -\u003e None:\n    match result:\n        case Ok(success_value):\n            # Revealed type is \"builtins.str\" Mypy\n            reveal_type(success_value)\n            # Revealed type is \"Ok[builtins.str]\" Mypy\n            reveal_type(result)\n        case Err(ValueError() as val):\n            # Revealed type is \"builtins.ValueError\" Mypy\n            reveal_type(val)\n            # Revealed type is \"Err[Union[builtins.ValueError, builtins.AttributeError]]\" Mypy\n            reveal_type(result)\n        case Err(AttributeError()):\n            # Revealed type is \"Err[Union[builtins.ValueError, builtins.AttributeError]]\" Mypy\n            reveal_type(result)\n        case _:\n            # Argument 1 to \"assert_never\" has incompatible type \"Err[ValueError | AttributeError]\"; expected \"Never\" Mypy(arg-type)\n            assert_never(result)\n```\n\n### Example 2: NonGenericErr (non-generic)\n\nHere, I narrowed the scope to matching on the error class, and made it non-generic. Even here, mypy can narrow the attribute (`val: ValueError`), but not the object (`err: NonGenericErr` and `err._value: ValueError | AttributeError`). And doesn't realize in the `case _` block that we've already exhausted all patterns above.\n\n```python\nclass NonGenericErr:\n    __match_args__ = (\"_value\",)\n\n    def __init__(self, value: ValueError | AttributeError) -\u003e None:\n        self._value = value\n\n\ndef handle_non_generic_err(err: NonGenericErr) -\u003e None:\n    # Revealed type is \"NonGenericErr\" Mypy\n    reveal_type(err)\n    match err:\n        case NonGenericErr(ValueError() as val):\n            # Revealed type is \"builtins.ValueError\" Mypy\n            reveal_type(val)\n            # Revealed type is \"Union[builtins.ValueError, builtins.AttributeError]\" Mypy\n            reveal_type(err._value)\n            # Revealed type is \"NonGenericErr\" Mypy\n            reveal_type(err)\n        case NonGenericErr(AttributeError()):\n            # Revealed type is \"NonGenericErr\" Mypy\n            reveal_type(err)\n        case _:\n            # Argument 1 to \"assert_never\" has incompatible type \"NonGenericErr\"; expected \"Never\" Mypy(arg-type)\n            assert_never(err)\n```\n\n### Example 3: FailureResult (generic, dataclass)\n\nI could see the logic that Example 2 is constrained by the lack of a generic type for mypy to use to narrow `err` beyond `NonGenericErr`. But even if we add that back, mypy can't narrow `err` as expected within any of the `case` blocks.\n\nThis example is basically a trimmed down / tighter-scoped version of Example 1.\n\n```python\nfrom dataclasses import dataclass\n\n\n@dataclass\nclass FailureResult[ErrorType]:\n    error: ErrorType\n\n\ndef handle_failure_result(failure_result: FailureResult[ValueError | AttributeError]) -\u003e None:\n    match failure_result:\n        case FailureResult(ValueError() as error):\n            # Revealed type is \"builtins.ValueError\" Mypy\n            reveal_type(error)\n            # Revealed type is \"Union[builtins.ValueError, builtins.AttributeError]\" Mypy\n            reveal_type(failure_result.error)\n            # Revealed type is \"FailureResult[Union[builtins.ValueError, builtins.AttributeError]]\" Mypy\n            reveal_type(failure_result)\n        case FailureResult(AttributeError()):\n            # Revealed type is \"FailureResult[Union[builtins.ValueError, builtins.AttributeError]]\" Mypy\n            reveal_type(failure_result)\n        case _:\n            # Argument 1 to \"assert_never\" has incompatible type \"FailureResult[ValueError | AttributeError]\"; expected \"Never\" Mypy(arg-type)\n            assert_never(failure_result)\n```\n\n## Expected Behavior\n\nMypy successfully narrows the type of an object we're pattern matching on, based on how we've matched on its attribute, allowing for an exhaustive `match` statement ending with `assert_never` if we have indeed exhausted all possible patterns.\n\n## Actual Behavior\n\nSee errors and unexpected `reveal_type` outputs above\n\n## Your Environment\n\n- Mypy version used: mypy 1.15.0\n- Mypy configuration options from `mypy.ini` (and other config files):\n\u003cdetails\u003e\u003csummary\u003e`mypy.ini`\u003c/summary\u003e\n\n```ini\n[mypy]\npython_version = 3.13\nmypy_path = typings\nignore_missing_imports = True\ncheck_untyped_defs = True\ndisallow_untyped_defs = True\ndisallow_untyped_calls = True\nstrict_equality = True\ndisallow_any_unimported = True\nwarn_return_any = True\nno_implicit_optional = True\npretty = True\nshow_error_context = True\nshow_error_codes = True\nshow_error_code_links = True\nno_namespace_packages = True\n```\n\u003c/details\u003e\n- Python version used: 3.13\n\n---\n\nThanks for all the work done to make mypy what it is!\n","author":{"url":"https://github.com/alythobani","@type":"Person","name":"alythobani"},"datePublished":"2025-05-12T18:47:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/19081/mypy/issues/19081"}