Runtime error that type checks. Is this a bug?

[Robert (robert-bn)]

The code below type checks in pyright, but produces a runtime error where assert_never is called.

from collections.abc import Callable
from dataclasses import dataclass
from typing import assert_never


@dataclass
class Left[T]:
    value: T

@dataclass
class Right[T]:
    value: T

@dataclass
class Violation[T](Left[T],Right[T]):
    value: T


type Either[L,R] = Left[L] | Right[R]

def either[L,R,T](
    cls_left: type[L],
    cls_right: type[R],
    value: Either[L,R],
    handle_left: Callable[[L], T],
    handle_right: Callable[[R], T]
) -> T:
    match value:
        case Left():
            return handle_left(value.value)
        case Right():
            return handle_right(value.value)


def handle_left(value: str) -> None:
    if isinstance(value, str):
        return

    assert_never(value)

def handle_right(value: int) -> None:
    if isinstance(value, int):
        return

    assert_never(value)


either(
    cls_left=str,
    cls_right=int,
    value=Violation(3),
    handle_left=handle_left,
    handle_right=handle_right,
)

Code sample in pyright playground

It is unsafe to narrow Left[L] | Right[R] to Left[L] in the Left match arm without considering the possibility of overlap between Left[Any] and Right[R]. I suppose it should be narrowed to something like Left[L] | (Left[Any] & Right[R]) if python had intersection types.

I wonder if this is a known limitation of python's type system. It would be rather inconvenient if one had to mark every class with @final if one wanted type checkers to narrow in match arms.

This also type checks in ty, mypy, and pyrefly, but ty and pyrefly require a bit more persuading to accept the code: Code sample in ty playground. Code sample in pyrefly

[Zayan Khan (ZayanKhan-12)]

Pyright Discussion Answer: Runtime Error That Type Checks

Short Answer

I think this is an unsound narrowing case caused by overlapping union members, not a runtime bug in match.

At runtime, case Left(): does not mean “this object is exclusively a Left.” It means the subject satisfies the Left class pattern. Since Violation[T] inherits from both Left[T] and Right[T], this object satisfies both patterns:

isinstance(Violation(3), Left)   # True
isinstance(Violation(3), Right)  # True

Because match chooses the first successful case, this branch wins:

case Left():
    return handle_left(value.value)

So Violation(3) is routed to handle_left, even though the call type-checks through the Right[int] side of:

type Either[L, R] = Left[L] | Right[R]

For this specific call, the type checker can accept Violation[int] as a valid inhabitant of Right[int], so it can satisfy Either[str, int]. But at runtime, the object also satisfies Left(), and the first branch sends 3 into handle_left, which expects str.

---

Why the Narrowing Is Unsafe

The unsafe static step is the narrowing from:

Left[L] | Right[R]

to:

Left[L]

inside the case Left(): arm.

That narrowing is only sound if Left and Right are known to be disjoint. In this example they are not disjoint, because multiple inheritance creates an overlap:

Violation[T] <: Left[T]
Violation[T] <: Right[T]

A fully sound narrowing would need to preserve that overlap. Conceptually, the Left() branch is closer to something like:

Left[L] | (Left[Any] & Right[R])

or in this specific call:

Left[str] | (Left[Any] & Right[int])

But Python's type system does not have general intersection types or sealed/disjoint class hierarchies, so most type checkers pragmatically narrow as if the union arms are disjoint. That is useful in normal code, but it becomes unsound when union members can overlap through subclassing.

---

Practical Fix 1: Make the Variants Final

The cleanest static fix is to make the variant types disjoint by design.

If subclasses should not exist, mark the variants as @final:

from dataclasses import dataclass
from typing import final

@final
@dataclass
class Left[T]:
    value: T

@final
@dataclass
class Right[T]:
    value: T

That should make this invalid to a type checker:

@dataclass
class Violation[T](Left[T], Right[T]):
    value: T

This is probably the right model if Left and Right are intended to represent a closed sum type.

---

Important Runtime Note About @final

@final is a static typing tool. It tells type checkers that a class should not be subclassed, but Python itself does not enforce that restriction at runtime.

So if runtime enforcement matters, @final is not sufficient by itself. You also need runtime checks.

---

Practical Fix 2: Use Exact-Type Dispatch for Runtime Safety

If you want to reject overlapping subclasses like Violation at runtime, avoid isinstance/class-pattern dispatch and require exact variants:

from collections.abc import Callable
from dataclasses import dataclass
from typing import cast

@dataclass
class Left[T]:
    value: T

@dataclass
class Right[T]:
    value: T

type Either[L, R] = Left[L] | Right[R]

def either[L, R, T](
    cls_left: type[L],
    cls_right: type[R],
    value: Either[L, R],
    handle_left: Callable[[L], T],
    handle_right: Callable[[R], T],
) -> T:
    if type(value) is Left:
        left = cast(Left[L], value)
        return handle_left(left.value)

    if type(value) is Right:
        right = cast(Right[R], value)
        return handle_right(right.value)

    raise TypeError("Expected exactly Left or Right")

That version rejects Violation, which is likely the correct runtime behavior if Either is intended to model a closed two-variant type.

---

Practical Fix 3: Use a Tagged Representation

Another robust approach is to encode the variant explicitly with a tag instead of relying on class inheritance:

from dataclasses import dataclass
from typing import Literal

@dataclass
class Left[T]:
    tag: Literal["left"]
    value: T

@dataclass
class Right[T]:
    tag: Literal["right"]
    value: T

type Either[L, R] = Left[L] | Right[R]

Then dispatch on the tag:

def either[L, R, T](
    value: Either[L, R],
    handle_left: Callable[[L], T],
    handle_right: Callable[[R], T],
) -> T:
    match value.tag:
        case "left":
            return handle_left(value.value)
        case "right":
            return handle_right(value.value)

This avoids the multiple-inheritance overlap problem because the branch condition is based on an explicit discriminant rather than class membership.

---

Final Summary

The runtime behaviour is expected: Violation(3) matches Left() first because it is an instance of Left.

The type-checking behaviour is the interesting part. The checker narrows Left[L] | Right[R] to Left[L] in the case Left(): branch, but that narrowing is only sound if Left and Right are disjoint. Since Python allows multiple inheritance, they are not necessarily disjoint.

So the issue is not that match is behaving incorrectly. The issue is that the type checker cannot fully model the possible intersection between the union arms. A sound model would need something like intersection types or sealed/disjoint class hierarchies.

The practical options are:

1. Use @final if subclasses should be rejected statically.
2. Use exact-type dispatch if subclasses should be rejected at runtime.
3. Use a tagged/discriminated representation if you want a more reliable sum-type pattern.

So I would summarize it as:

The runtime behaviour is expected, but the narrowing is only sound under a disjointness assumption that the Python type system cannot generally express. @final, exact-type dispatch, or a tagged/discriminated representation are the practical ways to enforce the invariant.