Files
David PeterandAlex Waygood 10775b0d4c [ty] Rename incompatible override rules (#30142)
Rename the method, attribute, property, and mutable override rules to
`incompatible-…-override`. The old names remain aliases in configuration
and inline suppressions:

| Before | After |
|---|---|
| `invalid-method-override` | `incompatible-method-override` |
| `invalid-attribute-override` | `incompatible-attribute-override` |
| `invalid-property-type-override` | `incompatible-property-override` |
| `invalid-mutable-override` | `incompatible-mutable-override` |

A follow-up PR will split `invalid-method-override` into two rules.

Fixes astral-sh/ty#2001.

---------

Co-authored-by: Alex Waygood <alex.waygood@gmail.com>
2026-11-09 12:14:13 +01:00

17 KiB

Comparison: Intersections

Positive contributions

If we have an intersection type A & B and we get a definitive true/false answer for one of the types, we can infer that the result for the intersection type is also true/false:

from typing import Literal

class Base:
    def __gt__(self, other) -> bool:
        return False

class Child1(Base):
    def __eq__(self, other) -> Literal[True]:
        return True

class Child2(Base): ...

def _(x: Base):
    c1 = Child1()

    # Create an intersection type through narrowing:
    if isinstance(x, Child1):
        if isinstance(x, Child2):
            reveal_type(x)  # revealed: Child1 & Child2

            reveal_type(x == 1)  # revealed: Literal[True]

            # Other comparison operators fall back to the base type:
            reveal_type(x > 1)  # revealed: bool
            reveal_type(x is c1)  # revealed: bool

Negative contributions

Negative contributions to the intersection type only allow simplifications in a few special cases (equality and identity comparisons).

Equality comparisons

Literal strings

x = "x" * 1_000_000_000
y = "y" * 1_000_000_000
reveal_type(x)  # revealed: LiteralString

if x != "abc":
    reveal_type(x)  # revealed: LiteralString & ~Literal["abc"]

    reveal_type(x == "abc")  # revealed: Literal[False]
    reveal_type("abc" == x)  # revealed: Literal[False]
    reveal_type(x == "something else")  # revealed: bool
    reveal_type("something else" == x)  # revealed: bool

    reveal_type(x != "abc")  # revealed: Literal[True]
    reveal_type("abc" != x)  # revealed: Literal[True]
    reveal_type(x != "something else")  # revealed: bool
    reveal_type("something else" != x)  # revealed: bool

    reveal_type(x == y)  # revealed: bool
    reveal_type(y == x)  # revealed: bool
    reveal_type(x != y)  # revealed: bool
    reveal_type(y != x)  # revealed: bool

    reveal_type(x >= "abc")  # revealed: bool
    reveal_type("abc" >= x)  # revealed: bool

    reveal_type(x in "abc")  # revealed: bool
    reveal_type("abc" in x)  # revealed: bool

A negative literal-string constraint does not exclude a runtime string with that value unless the candidate already has known literal origin.

from typing import Literal
from typing_extensions import LiteralString
from ty_extensions import Intersection, Not

def without_literal_origin(value: Intersection[str, Not[LiteralString]]) -> None:
    reveal_type(value == "hello")  # revealed: bool
    reveal_type("hello" == value)  # revealed: bool

A negative string-literal constraint likewise leaves the same runtime value possible, with or without an explicit str constraint.

def excluded_string_literal(value: Intersection[str, Not[Literal["hello"]]]) -> None:
    reveal_type(value == "hello")  # revealed: bool
    reveal_type("hello" == value)  # revealed: bool
    reveal_type(value != "hello")  # revealed: bool

def excluded_literal(value: Not[Literal["hello"]]) -> None:
    reveal_type(value == "hello")  # revealed: bool
    reveal_type("hello" == value)  # revealed: bool
    reveal_type(value != "hello")  # revealed: bool

Integers

def _(x: int):
    if x != 1:
        reveal_type(x)  # revealed: int & ~Literal[1] & ~Literal[True]

        reveal_type(x != 1)  # revealed: bool
        reveal_type(x != 2)  # revealed: bool

        reveal_type(x == 1)  # revealed: bool
        reveal_type(x == 2)  # revealed: bool

Identity comparisons

The type ~None excludes the None object, so its identity comparisons with None have definite results.

def _(o: object):
    n = None

    if o is not None:
        reveal_type(o)  # revealed: ~None
        reveal_type(o is n)  # revealed: Literal[False]
        reveal_type(o is not n)  # revealed: Literal[True]

A single-member enum contains only one object. A value excluded from E cannot be E.ONLY, so the branch below is unreachable and must not emit an attribute error.

from enum import Enum
from ty_extensions import Not

class E(Enum):
    ONLY = 1

def f(value: Not[E]) -> None:
    if value is E.ONLY:
        reveal_type(value)  # revealed: Never
        value.does_not_exist  # no error (unreachable branch)

A NewType negation removes its static tag, not the runtime objects of its base: an integer without that tag can still be identical to the integer passed into the NewType constructor.

from typing import NewType

UserId = NewType("UserId", int)

def f(value: Not[UserId]) -> None:
    reveal_type(value is 1)  # revealed: bool

After not isinstance(value, B), value cannot be identical to a B instance. This remains true when value has also been narrowed to A, so the inner branch is unreachable.

class A: ...
class B: ...

def f(value: object, other_b: B) -> None:
    if isinstance(value, A) and not isinstance(value, B):
        if value is other_b:
            reveal_type(value)  # revealed: Never
            value.does_not_exist  # no error (unreachable branch)

Non-boolean comparison results

Rich comparisons preserve their declared return types after narrowing an operand to an intersection. A return type that is disjoint from bool does not make the comparison unreachable, and an int return type is not narrowed to its bool subtype.

class Comparison:
    def __eq__(self, other: object) -> str:  # error: [incompatible-method-override]
        return "equal"

    def __ne__(self, other: object) -> bytes:  # error: [incompatible-method-override]
        return b"different"

    def __lt__(self, other: object) -> int:
        return 42

    def __contains__(self, other: object) -> str:
        return "contained"

class Excluded: ...

def compare(value: Comparison):
    if not isinstance(value, Excluded):
        reveal_type(value == 0)  # revealed: str
        reveal_type(value != 0)  # revealed: bytes
        reveal_type(value < 0)  # revealed: int

Membership tests still convert their result to bool, even when __contains__ returns another type.

def membership(value: Comparison):
    if not isinstance(value, Excluded):
        reveal_type(0 in value)  # revealed: bool
        reveal_type(0 not in value)  # revealed: bool

A comparison that always raises still has type Never when another component inherits object.__eq__.

from typing_extensions import Never

class NonReturning:
    def __eq__(self, other: object) -> Never:
        raise RuntimeError

def never_returns(value: NonReturning):
    if isinstance(value, Excluded):
        reveal_type(value == 0)  # revealed: Never

Gradual comparison results

Excluding None from an unannotated argument does not constrain its comparison result to bool.

def is_zero(value) -> bool:
    if value is None:
        return False
    return reveal_type(value == 0)  # revealed: Unknown

Gradual operands narrowed to None

Narrowing a gradual type to None fixes its runtime value. Comparisons with a string literal have definite boolean results, even though the narrowed type retains its gradual component.

def compare(value):
    assert value is None
    reveal_type(value)  # revealed: Unknown & None
    reveal_type(value == "ready")  # revealed: Literal[False]
    reveal_type("ready" == value)  # revealed: Literal[False]
    reveal_type(value != "ready")  # revealed: Literal[True]
    reveal_type("ready" != value)  # revealed: Literal[True]

    assert value == "ready"
    "unreachable".missing  # ok (unreachable)

The same applies to Any, including when both operands have been narrowed to None.

from typing import Any

def compare_any(left: Any, right):
    assert left is None
    assert right is None
    reveal_type(left == "ready")  # revealed: Literal[False]
    reveal_type(left == right)  # revealed: Literal[True]
    reveal_type(left != right)  # revealed: Literal[False]

An annotated str operand can be an instance of a subclass with custom comparison methods, so it does not establish a definite result.

def compare_string(value, text: str):
    assert value is None
    reveal_type(value == text)  # revealed: Unknown
    reveal_type(value != text)  # revealed: Unknown

Custom comparison methods can still supply a non-boolean result. A gradual comparison result is not narrowed to bool.

class Custom:
    def __eq__(self, other: object) -> str:  # error: [incompatible-method-override]
        return "equal"

    def __ne__(self, other: object) -> bytes:  # error: [incompatible-method-override]
        return b"different"

def compare_custom(value, custom: Custom):
    assert value is None
    reveal_type(custom == value)  # revealed: str
    reveal_type(custom != value)  # revealed: bytes

    # TODO: Retain the precise return types of the reflected comparisons.
    reveal_type(value == custom)  # revealed: Unknown
    reveal_type(value != custom)  # revealed: Unknown

Conditionally defined comparison methods

A conditional comparison method can fall back to the inherited object method. Narrowing its receiver preserves both the custom result and the boolean fallback.

def enabled() -> bool:
    return True

class Conditional:
    if enabled():
        def __eq__(self, other: object) -> str:  # error: [incompatible-method-override]
            return "equal"

class Excluded: ...

def compare(value: Conditional):
    if not isinstance(value, Excluded):
        reveal_type(value == 0)  # revealed: str | bool

The conditional method must not be discarded in favor of a reflected method that returns a different boolean literal. The left operand can return True without calling the right operand's method.

from typing_extensions import Literal

class ConditionalTrue:
    if enabled():
        def __eq__(self, other: object) -> Literal[True]:
            return True

class ReflectedFalse:
    def __eq__(self, other: object) -> Literal[False]:
        return False

def reflected(left: ConditionalTrue, right: ReflectedFalse):
    if not isinstance(left, Excluded):
        reveal_type(left == right)  # revealed: bool

An intersection with another class that defines a boolean comparison still permits either result of the conditional method.

class BooleanComparison:
    def __eq__(self, other: object) -> bool:
        return False

def positive(left: ConditionalTrue):
    if isinstance(left, BooleanComparison):
        reveal_type(left == 0)  # revealed: bool

The same applies when both classes define their comparison methods conditionally.

class ConditionalBoolean:
    if enabled():
        def __eq__(self, other: object) -> bool:
            return False

def both_conditional(left: ConditionalTrue):
    if isinstance(left, ConditionalBoolean):
        reveal_type(left == 0)  # revealed: bool

Comparison methods returning Self

A comparison method annotated with Self returns the full intersection receiver, just like an explicit method call. Excluding a class from the receiver also excludes it from the comparison result.

from __future__ import annotations
from typing_extensions import Self

class Index:
    def __eq__(self, other: object) -> Self:  # error: [incompatible-method-override]
        return self

    def __lt__(self, other: object) -> Self:
        return self

    def __gt__(self, other: object) -> Index:
        return Index()

class MultiIndex: ...

def equality(index: Index):
    if not isinstance(index, MultiIndex):
        reveal_type(index.__eq__(""))  # revealed: Index & ~MultiIndex
        reveal_type(index == "")  # revealed: Index & ~MultiIndex

An and expression can return either False or the comparison result; it does not convert the comparison result to a boolean.

def conjunction(index: Index):
    reveal_type(not isinstance(index, MultiIndex) and index == "")  # revealed: Literal[False] | (Index & ~MultiIndex)

Positive intersection components are preserved as well. An inherited object.__eq__ on another component does not restrict a custom comparison's result to bool.

def positive(index: Index):
    if isinstance(index, MultiIndex):
        reveal_type(index == "")  # revealed: Index & MultiIndex

Reflected comparisons bind Self to the right-hand receiver. In contrast, a concrete return annotation does not inherit constraints from the receiver: __gt__ can return a different Index.

def reflected(index: Index):
    if not isinstance(index, MultiIndex):
        reveal_type(0 > index)  # revealed: Index & ~MultiIndex
        reveal_type(index > 0)  # revealed: Index

Comparison results containing Self

Receiver binding also applies when Self occurs inside the comparison's return type, rather than being the entire return type.

from typing_extensions import Self

class Comparison:
    def __eq__(self, other: object) -> tuple[Self]:  # error: [incompatible-method-override]
        return (self,)

class Excluded: ...

def equality(value: Comparison):
    if not isinstance(value, Excluded):
        reveal_type(value.__eq__(0))  # revealed: tuple[Comparison & ~Excluded]
        reveal_type(value == 0)  # revealed: tuple[Comparison & ~Excluded]

Reflected comparisons with narrowed receivers

Excluding an unrelated class from either operand does not prevent the right operand from being a subclass with a reflected comparison method. Since the runtime classes of these operands are not known exactly, either method can supply the result.

class Base:
    def __lt__(self, other: object) -> int:
        return 42

class Child(Base):
    def __gt__(self, other: object) -> str:
        return "reflected"

class Excluded: ...

def compare(left: Base, right: Child):
    if not isinstance(left, Excluded):
        reveal_type(left < right)  # revealed: int | str
    if not isinstance(right, Excluded):
        reveal_type(left < right)  # revealed: int | str

NewTypes in intersection comparisons

Narrowing a NewType of float preserves the comparison operations supported by its base type, including comparisons where both operands are intersections.

from typing import NewType

Float = NewType("Float", float)

class Excluded: ...

def compare(left: Float, right: Float):
    if not isinstance(left, Excluded) and not isinstance(right, Excluded):
        reveal_type(left < right)  # revealed: bool

Comparisons with multiple union return types

A comparison can have different union return types on its positive intersection components. When distributing those unions exceeds the complexity limit, we keep a wider union of their return types instead of losing their non-boolean results.

class A: ...
class B: ...
class C: ...
class D: ...
class E: ...

class First:
    def __lt__(self, other: object) -> A | B | C:
        return A()

class Second:
    def __lt__(self, other: object) -> D | E:
        return D()

def compare(value: First):
    if isinstance(value, Second):
        reveal_type(value < 0)  # revealed: A | B | C | D | E

Diagnostics

Unsupported operators for positive contributions

Raise an error if the given operator is unsupported for all positive contributions to the intersection type:

class NonContainer1: ...
class NonContainer2: ...

def _(x: object):
    if isinstance(x, NonContainer1):
        if isinstance(x, NonContainer2):
            reveal_type(x)  # revealed: NonContainer1 & NonContainer2

            # snapshot: unsupported-operator
            reveal_type(2 in x)  # revealed: bool
error[unsupported-operator]: Unsupported `in` operation
  --> src/mdtest_snippet.py:10:25
   |
10 |             reveal_type(2 in x)  # revealed: bool
   |                         -^^^^-
   |                         |    |
   |                         |    Has type `NonContainer1 & NonContainer2`
   |                         Has type `Literal[2]`

Do not raise an error if at least one of the positive contributions to the intersection type support the operator:

class Container:
    def __contains__(self, x) -> bool:
        return False

def _(x: object):
    if isinstance(x, NonContainer1):
        if isinstance(x, Container):
            if isinstance(x, NonContainer2):
                reveal_type(x)  # revealed: NonContainer1 & Container & NonContainer2
                reveal_type(2 in x)  # revealed: bool

Do also raise an error if the intersection has no positive contributions at all, unless the operator is supported on object:

def _(x: object):
    if not isinstance(x, NonContainer1):
        reveal_type(x)  # revealed: ~NonContainer1

        # snapshot: unsupported-operator
        reveal_type(2 in x)  # revealed: bool

        reveal_type(2 is x)  # revealed: bool
        reveal_type(x == 0)  # revealed: bool
        x < 0  # error: [unsupported-operator]
error[unsupported-operator]: Unsupported `in` operation
  --> src/mdtest_snippet.py:26:21
   |
26 |         reveal_type(2 in x)  # revealed: bool
   |                     -^^^^-
   |                     |    |
   |                     |    Has type `~NonContainer1`
   |                     Has type `Literal[2]`

Unsupported operators for negative contributions

Do not raise an error if any of the negative contributions to the intersection type are unsupported for the given operator:

class Container:
    def __contains__(self, x) -> bool:
        return False

class NonContainer: ...

def _(x: object):
    if isinstance(x, Container):
        if not isinstance(x, NonContainer):
            reveal_type(x)  # revealed: Container & ~NonContainer

            # No error here!
            reveal_type(2 in x)  # revealed: bool