Rename Red Knot (#17820)

2025-08-09 13:18:52 +00:00 · 2025-05-03 19:49:15 +02:00 · 2025-05-03 19:49:15 +02:00 · b51c4f82ea
commit b51c4f82ea
parent e6a798b962
1564 changed files with 1598 additions and 1578 deletions
--- a/crates/ty_python_semantic/resources/mdtest/binary/booleans.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/booleans.md
@ -0,0 +1,93 @@
+## Binary operations on booleans
+
+## Basic Arithmetic
+
+We try to be precise and all operations except for division will result in Literal type.
+
+```py
+a = True
+b = False
+
+reveal_type(a + a)  # revealed: Literal[2]
+reveal_type(a + b)  # revealed: Literal[1]
+reveal_type(b + a)  # revealed: Literal[1]
+reveal_type(b + b)  # revealed: Literal[0]
+
+reveal_type(a - a)  # revealed: Literal[0]
+reveal_type(a - b)  # revealed: Literal[1]
+reveal_type(b - a)  # revealed: Literal[-1]
+reveal_type(b - b)  # revealed: Literal[0]
+
+reveal_type(a * a)  # revealed: Literal[1]
+reveal_type(a * b)  # revealed: Literal[0]
+reveal_type(b * a)  # revealed: Literal[0]
+reveal_type(b * b)  # revealed: Literal[0]
+
+reveal_type(a % a)  # revealed: Literal[0]
+reveal_type(b % a)  # revealed: Literal[0]
+
+reveal_type(a // a)  # revealed: Literal[1]
+reveal_type(b // a)  # revealed: Literal[0]
+
+reveal_type(a**a)  # revealed: Literal[1]
+reveal_type(a**b)  # revealed: Literal[1]
+reveal_type(b**a)  # revealed: Literal[0]
+reveal_type(b**b)  # revealed: Literal[1]
+
+# Division
+reveal_type(a / a)  # revealed: float
+reveal_type(b / a)  # revealed: float
+b / b  # error: [division-by-zero] "Cannot divide object of type `Literal[False]` by zero"
+a / b  # error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+
+# bitwise OR
+reveal_type(a | a)  # revealed: Literal[True]
+reveal_type(a | b)  # revealed: Literal[True]
+reveal_type(b | a)  # revealed: Literal[True]
+reveal_type(b | b)  # revealed: Literal[False]
+```
+
+## Arithmetic with a variable
+
+```py
+def _(a: bool):
+    def lhs_is_int(x: int):
+        reveal_type(x + a)  # revealed: int
+        reveal_type(x - a)  # revealed: int
+        reveal_type(x * a)  # revealed: int
+        reveal_type(x // a)  # revealed: int
+        reveal_type(x / a)  # revealed: int | float
+        reveal_type(x % a)  # revealed: int
+
+    def rhs_is_int(x: int):
+        reveal_type(a + x)  # revealed: int
+        reveal_type(a - x)  # revealed: int
+        reveal_type(a * x)  # revealed: int
+        reveal_type(a // x)  # revealed: int
+        reveal_type(a / x)  # revealed: int | float
+        reveal_type(a % x)  # revealed: int
+
+    def lhs_is_bool(x: bool):
+        reveal_type(x + a)  # revealed: int
+        reveal_type(x - a)  # revealed: int
+        reveal_type(x * a)  # revealed: int
+        reveal_type(x // a)  # revealed: int
+        reveal_type(x / a)  # revealed: int | float
+        reveal_type(x % a)  # revealed: int
+
+    def rhs_is_bool(x: bool):
+        reveal_type(a + x)  # revealed: int
+        reveal_type(a - x)  # revealed: int
+        reveal_type(a * x)  # revealed: int
+        reveal_type(a // x)  # revealed: int
+        reveal_type(a / x)  # revealed: int | float
+        reveal_type(a % x)  # revealed: int
+
+    def both_are_bool(x: bool, y: bool):
+        reveal_type(x + y)  # revealed: int
+        reveal_type(x - y)  # revealed: int
+        reveal_type(x * y)  # revealed: int
+        reveal_type(x // y)  # revealed: int
+        reveal_type(x / y)  # revealed: int | float
+        reveal_type(x % y)  # revealed: int
+```
--- a/crates/ty_python_semantic/resources/mdtest/binary/classes.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/classes.md
@ -0,0 +1,27 @@
+# Binary operations on classes
+
+## Union of two classes
+
+Unioning two classes via the `|` operator is only available in Python 3.10 and later.
+
+```toml
+[environment]
+python-version = "3.10"
+```
+
+```py
+class A: ...
+class B: ...
+
+reveal_type(A | B)  # revealed: UnionType
+```
+
+## Union of two classes (prior to 3.10)
+
+```py
+class A: ...
+class B: ...
+
+# error: "Operator `|` is unsupported between objects of type `Literal[A]` and `Literal[B]`"
+reveal_type(A | B)  # revealed: Unknown
+```
--- a/crates/ty_python_semantic/resources/mdtest/binary/custom.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/custom.md
@ -0,0 +1,379 @@
+# Custom binary operations
+
+## Class instances
+
+```py
+from typing import Literal
+
+class Yes:
+    def __add__(self, other) -> Literal["+"]:
+        return "+"
+
+    def __sub__(self, other) -> Literal["-"]:
+        return "-"
+
+    def __mul__(self, other) -> Literal["*"]:
+        return "*"
+
+    def __matmul__(self, other) -> Literal["@"]:
+        return "@"
+
+    def __truediv__(self, other) -> Literal["/"]:
+        return "/"
+
+    def __mod__(self, other) -> Literal["%"]:
+        return "%"
+
+    def __pow__(self, other) -> Literal["**"]:
+        return "**"
+
+    def __lshift__(self, other) -> Literal["<<"]:
+        return "<<"
+
+    def __rshift__(self, other) -> Literal[">>"]:
+        return ">>"
+
+    def __or__(self, other) -> Literal["|"]:
+        return "|"
+
+    def __xor__(self, other) -> Literal["^"]:
+        return "^"
+
+    def __and__(self, other) -> Literal["&"]:
+        return "&"
+
+    def __floordiv__(self, other) -> Literal["//"]:
+        return "//"
+
+class Sub(Yes): ...
+class No: ...
+
+# Yes implements all of the dunder methods.
+reveal_type(Yes() + Yes())  # revealed: Literal["+"]
+reveal_type(Yes() - Yes())  # revealed: Literal["-"]
+reveal_type(Yes() * Yes())  # revealed: Literal["*"]
+reveal_type(Yes() @ Yes())  # revealed: Literal["@"]
+reveal_type(Yes() / Yes())  # revealed: Literal["/"]
+reveal_type(Yes() % Yes())  # revealed: Literal["%"]
+reveal_type(Yes() ** Yes())  # revealed: Literal["**"]
+reveal_type(Yes() << Yes())  # revealed: Literal["<<"]
+reveal_type(Yes() >> Yes())  # revealed: Literal[">>"]
+reveal_type(Yes() | Yes())  # revealed: Literal["|"]
+reveal_type(Yes() ^ Yes())  # revealed: Literal["^"]
+reveal_type(Yes() & Yes())  # revealed: Literal["&"]
+reveal_type(Yes() // Yes())  # revealed: Literal["//"]
+
+# Sub inherits Yes's implementation of the dunder methods.
+reveal_type(Sub() + Sub())  # revealed: Literal["+"]
+reveal_type(Sub() - Sub())  # revealed: Literal["-"]
+reveal_type(Sub() * Sub())  # revealed: Literal["*"]
+reveal_type(Sub() @ Sub())  # revealed: Literal["@"]
+reveal_type(Sub() / Sub())  # revealed: Literal["/"]
+reveal_type(Sub() % Sub())  # revealed: Literal["%"]
+reveal_type(Sub() ** Sub())  # revealed: Literal["**"]
+reveal_type(Sub() << Sub())  # revealed: Literal["<<"]
+reveal_type(Sub() >> Sub())  # revealed: Literal[">>"]
+reveal_type(Sub() | Sub())  # revealed: Literal["|"]
+reveal_type(Sub() ^ Sub())  # revealed: Literal["^"]
+reveal_type(Sub() & Sub())  # revealed: Literal["&"]
+reveal_type(Sub() // Sub())  # revealed: Literal["//"]
+
+# No does not implement any of the dunder methods.
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `No` and `No`"
+reveal_type(No() + No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `-` is unsupported between objects of type `No` and `No`"
+reveal_type(No() - No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `*` is unsupported between objects of type `No` and `No`"
+reveal_type(No() * No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `@` is unsupported between objects of type `No` and `No`"
+reveal_type(No() @ No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `/` is unsupported between objects of type `No` and `No`"
+reveal_type(No() / No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `%` is unsupported between objects of type `No` and `No`"
+reveal_type(No() % No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `**` is unsupported between objects of type `No` and `No`"
+reveal_type(No() ** No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `<<` is unsupported between objects of type `No` and `No`"
+reveal_type(No() << No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>>` is unsupported between objects of type `No` and `No`"
+reveal_type(No() >> No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `|` is unsupported between objects of type `No` and `No`"
+reveal_type(No() | No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `^` is unsupported between objects of type `No` and `No`"
+reveal_type(No() ^ No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `&` is unsupported between objects of type `No` and `No`"
+reveal_type(No() & No())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `//` is unsupported between objects of type `No` and `No`"
+reveal_type(No() // No())  # revealed: Unknown
+
+# Yes does not implement any of the reflected dunder methods.
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() + Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `-` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() - Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `*` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() * Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `@` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() @ Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `/` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() / Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `%` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() % Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `**` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() ** Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `<<` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() << Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>>` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() >> Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `|` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() | Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `^` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() ^ Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `&` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() & Yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `//` is unsupported between objects of type `No` and `Yes`"
+reveal_type(No() // Yes())  # revealed: Unknown
+```
+
+## Subclass reflections override superclass dunders
+
+```py
+from typing import Literal
+
+class Yes:
+    def __add__(self, other) -> Literal["+"]:
+        return "+"
+
+    def __sub__(self, other) -> Literal["-"]:
+        return "-"
+
+    def __mul__(self, other) -> Literal["*"]:
+        return "*"
+
+    def __matmul__(self, other) -> Literal["@"]:
+        return "@"
+
+    def __truediv__(self, other) -> Literal["/"]:
+        return "/"
+
+    def __mod__(self, other) -> Literal["%"]:
+        return "%"
+
+    def __pow__(self, other) -> Literal["**"]:
+        return "**"
+
+    def __lshift__(self, other) -> Literal["<<"]:
+        return "<<"
+
+    def __rshift__(self, other) -> Literal[">>"]:
+        return ">>"
+
+    def __or__(self, other) -> Literal["|"]:
+        return "|"
+
+    def __xor__(self, other) -> Literal["^"]:
+        return "^"
+
+    def __and__(self, other) -> Literal["&"]:
+        return "&"
+
+    def __floordiv__(self, other) -> Literal["//"]:
+        return "//"
+
+class Sub(Yes):
+    def __radd__(self, other) -> Literal["r+"]:
+        return "r+"
+
+    def __rsub__(self, other) -> Literal["r-"]:
+        return "r-"
+
+    def __rmul__(self, other) -> Literal["r*"]:
+        return "r*"
+
+    def __rmatmul__(self, other) -> Literal["r@"]:
+        return "r@"
+
+    def __rtruediv__(self, other) -> Literal["r/"]:
+        return "r/"
+
+    def __rmod__(self, other) -> Literal["r%"]:
+        return "r%"
+
+    def __rpow__(self, other) -> Literal["r**"]:
+        return "r**"
+
+    def __rlshift__(self, other) -> Literal["r<<"]:
+        return "r<<"
+
+    def __rrshift__(self, other) -> Literal["r>>"]:
+        return "r>>"
+
+    def __ror__(self, other) -> Literal["r|"]:
+        return "r|"
+
+    def __rxor__(self, other) -> Literal["r^"]:
+        return "r^"
+
+    def __rand__(self, other) -> Literal["r&"]:
+        return "r&"
+
+    def __rfloordiv__(self, other) -> Literal["r//"]:
+        return "r//"
+
+class No:
+    def __radd__(self, other) -> Literal["r+"]:
+        return "r+"
+
+    def __rsub__(self, other) -> Literal["r-"]:
+        return "r-"
+
+    def __rmul__(self, other) -> Literal["r*"]:
+        return "r*"
+
+    def __rmatmul__(self, other) -> Literal["r@"]:
+        return "r@"
+
+    def __rtruediv__(self, other) -> Literal["r/"]:
+        return "r/"
+
+    def __rmod__(self, other) -> Literal["r%"]:
+        return "r%"
+
+    def __rpow__(self, other) -> Literal["r**"]:
+        return "r**"
+
+    def __rlshift__(self, other) -> Literal["r<<"]:
+        return "r<<"
+
+    def __rrshift__(self, other) -> Literal["r>>"]:
+        return "r>>"
+
+    def __ror__(self, other) -> Literal["r|"]:
+        return "r|"
+
+    def __rxor__(self, other) -> Literal["r^"]:
+        return "r^"
+
+    def __rand__(self, other) -> Literal["r&"]:
+        return "r&"
+
+    def __rfloordiv__(self, other) -> Literal["r//"]:
+        return "r//"
+
+# Subclass reflected dunder methods take precedence over the superclass's regular dunders.
+reveal_type(Yes() + Sub())  # revealed: Literal["r+"]
+reveal_type(Yes() - Sub())  # revealed: Literal["r-"]
+reveal_type(Yes() * Sub())  # revealed: Literal["r*"]
+reveal_type(Yes() @ Sub())  # revealed: Literal["r@"]
+reveal_type(Yes() / Sub())  # revealed: Literal["r/"]
+reveal_type(Yes() % Sub())  # revealed: Literal["r%"]
+reveal_type(Yes() ** Sub())  # revealed: Literal["r**"]
+reveal_type(Yes() << Sub())  # revealed: Literal["r<<"]
+reveal_type(Yes() >> Sub())  # revealed: Literal["r>>"]
+reveal_type(Yes() | Sub())  # revealed: Literal["r|"]
+reveal_type(Yes() ^ Sub())  # revealed: Literal["r^"]
+reveal_type(Yes() & Sub())  # revealed: Literal["r&"]
+reveal_type(Yes() // Sub())  # revealed: Literal["r//"]
+
+# But for an unrelated class, the superclass regular dunders are used.
+reveal_type(Yes() + No())  # revealed: Literal["+"]
+reveal_type(Yes() - No())  # revealed: Literal["-"]
+reveal_type(Yes() * No())  # revealed: Literal["*"]
+reveal_type(Yes() @ No())  # revealed: Literal["@"]
+reveal_type(Yes() / No())  # revealed: Literal["/"]
+reveal_type(Yes() % No())  # revealed: Literal["%"]
+reveal_type(Yes() ** No())  # revealed: Literal["**"]
+reveal_type(Yes() << No())  # revealed: Literal["<<"]
+reveal_type(Yes() >> No())  # revealed: Literal[">>"]
+reveal_type(Yes() | No())  # revealed: Literal["|"]
+reveal_type(Yes() ^ No())  # revealed: Literal["^"]
+reveal_type(Yes() & No())  # revealed: Literal["&"]
+reveal_type(Yes() // No())  # revealed: Literal["//"]
+```
+
+## Classes
+
+Dunder methods defined in a class are available to instances of that class, but not to the class
+itself. (For these operators to work on the class itself, they would have to be defined on the
+class's type, i.e. `type`.)
+
+```py
+from typing import Literal
+
+class Yes:
+    def __add__(self, other) -> Literal["+"]:
+        return "+"
+
+class Sub(Yes): ...
+class No: ...
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `Literal[Yes]` and `Literal[Yes]`"
+reveal_type(Yes + Yes)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `Literal[Sub]` and `Literal[Sub]`"
+reveal_type(Sub + Sub)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `Literal[No]` and `Literal[No]`"
+reveal_type(No + No)  # revealed: Unknown
+```
+
+## Subclass
+
+```py
+from typing import Literal
+
+class Yes:
+    def __add__(self, other) -> Literal["+"]:
+        return "+"
+
+class Sub(Yes): ...
+class No: ...
+
+def yes() -> type[Yes]:
+    return Yes
+
+def sub() -> type[Sub]:
+    return Sub
+
+def no() -> type[No]:
+    return No
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `type[Yes]` and `type[Yes]`"
+reveal_type(yes() + yes())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `type[Sub]` and `type[Sub]`"
+reveal_type(sub() + sub())  # revealed: Unknown
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `type[No]` and `type[No]`"
+reveal_type(no() + no())  # revealed: Unknown
+```
+
+## Function literals
+
+```py
+def f():
+    pass
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f + f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `-` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f - f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `*` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f * f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `@` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f @ f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `/` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f / f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `%` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f % f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `**` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f**f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `<<` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f << f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `>>` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f >> f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `|` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f | f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `^` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f ^ f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `&` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f & f)  # revealed: Unknown
+# error: [unsupported-operator] "Operator `//` is unsupported between objects of type `def f() -> Unknown` and `def f() -> Unknown`"
+reveal_type(f // f)  # revealed: Unknown
+```
--- a/crates/ty_python_semantic/resources/mdtest/binary/instances.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/instances.md
@ -0,0 +1,475 @@
+# Binary operations on instances
+
+Binary operations in Python are implemented by means of magic double-underscore methods.
+
+For references, see:
+
+- <https://snarky.ca/unravelling-binary-arithmetic-operations-in-python/>
+- <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>
+
+## Operations
+
+We support inference for all Python's binary operators: `+`, `-`, `*`, `@`, `/`, `//`, `%`, `**`,
+`<<`, `>>`, `&`, `^`, and `|`.
+
+```py
+class A:
+    def __add__(self, other) -> "A":
+        return self
+
+    def __sub__(self, other) -> "A":
+        return self
+
+    def __mul__(self, other) -> "A":
+        return self
+
+    def __matmul__(self, other) -> "A":
+        return self
+
+    def __truediv__(self, other) -> "A":
+        return self
+
+    def __floordiv__(self, other) -> "A":
+        return self
+
+    def __mod__(self, other) -> "A":
+        return self
+
+    def __pow__(self, other) -> "A":
+        return self
+
+    def __lshift__(self, other) -> "A":
+        return self
+
+    def __rshift__(self, other) -> "A":
+        return self
+
+    def __and__(self, other) -> "A":
+        return self
+
+    def __xor__(self, other) -> "A":
+        return self
+
+    def __or__(self, other) -> "A":
+        return self
+
+class B: ...
+
+reveal_type(A() + B())  # revealed: A
+reveal_type(A() - B())  # revealed: A
+reveal_type(A() * B())  # revealed: A
+reveal_type(A() @ B())  # revealed: A
+reveal_type(A() / B())  # revealed: A
+reveal_type(A() // B())  # revealed: A
+reveal_type(A() % B())  # revealed: A
+reveal_type(A() ** B())  # revealed: A
+reveal_type(A() << B())  # revealed: A
+reveal_type(A() >> B())  # revealed: A
+reveal_type(A() & B())  # revealed: A
+reveal_type(A() ^ B())  # revealed: A
+reveal_type(A() | B())  # revealed: A
+```
+
+## Reflected
+
+We also support inference for reflected operations:
+
+```py
+class A:
+    def __radd__(self, other) -> "A":
+        return self
+
+    def __rsub__(self, other) -> "A":
+        return self
+
+    def __rmul__(self, other) -> "A":
+        return self
+
+    def __rmatmul__(self, other) -> "A":
+        return self
+
+    def __rtruediv__(self, other) -> "A":
+        return self
+
+    def __rfloordiv__(self, other) -> "A":
+        return self
+
+    def __rmod__(self, other) -> "A":
+        return self
+
+    def __rpow__(self, other) -> "A":
+        return self
+
+    def __rlshift__(self, other) -> "A":
+        return self
+
+    def __rrshift__(self, other) -> "A":
+        return self
+
+    def __rand__(self, other) -> "A":
+        return self
+
+    def __rxor__(self, other) -> "A":
+        return self
+
+    def __ror__(self, other) -> "A":
+        return self
+
+class B: ...
+
+reveal_type(B() + A())  # revealed: A
+reveal_type(B() - A())  # revealed: A
+reveal_type(B() * A())  # revealed: A
+reveal_type(B() @ A())  # revealed: A
+reveal_type(B() / A())  # revealed: A
+reveal_type(B() // A())  # revealed: A
+reveal_type(B() % A())  # revealed: A
+reveal_type(B() ** A())  # revealed: A
+reveal_type(B() << A())  # revealed: A
+reveal_type(B() >> A())  # revealed: A
+reveal_type(B() & A())  # revealed: A
+reveal_type(B() ^ A())  # revealed: A
+reveal_type(B() | A())  # revealed: A
+```
+
+## Returning a different type
+
+The magic methods aren't required to return the type of `self`:
+
+```py
+class A:
+    def __add__(self, other) -> int:
+        return 1
+
+    def __rsub__(self, other) -> int:
+        return 1
+
+class B: ...
+
+reveal_type(A() + B())  # revealed: int
+reveal_type(B() - A())  # revealed: int
+```
+
+## Non-reflected precedence in general
+
+In general, if the left-hand side defines `__add__` and the right-hand side defines `__radd__` and
+the right-hand side is not a subtype of the left-hand side, `lhs.__add__` will take precedence:
+
+```py
+class A:
+    def __add__(self, other: "B") -> int:
+        return 42
+
+class B:
+    def __radd__(self, other: "A") -> str:
+        return "foo"
+
+reveal_type(A() + B())  # revealed:  int
+
+# Edge case: C is a subtype of C, *but* if the two sides are of *equal* types,
+# the lhs *still* takes precedence
+class C:
+    def __add__(self, other: "C") -> int:
+        return 42
+
+    def __radd__(self, other: "C") -> str:
+        return "foo"
+
+reveal_type(C() + C())  # revealed: int
+```
+
+## Reflected precedence for subtypes (in some cases)
+
+If the right-hand operand is a subtype of the left-hand operand and has a different implementation
+of the reflected method, the reflected method on the right-hand operand takes precedence.
+
+```py
+class A:
+    def __add__(self, other) -> str:
+        return "foo"
+
+    def __radd__(self, other) -> str:
+        return "foo"
+
+class MyString(str): ...
+
+class B(A):
+    def __radd__(self, other) -> MyString:
+        return MyString()
+
+reveal_type(A() + B())  # revealed: MyString
+
+# N.B. Still a subtype of `A`, even though `A` does not appear directly in the class's `__bases__`
+class C(B): ...
+
+reveal_type(A() + C())  # revealed: MyString
+```
+
+## Reflected precedence 2
+
+If the right-hand operand is a subtype of the left-hand operand, but does not override the reflected
+method, the left-hand operand's non-reflected method still takes precedence:
+
+```py
+class A:
+    def __add__(self, other) -> str:
+        return "foo"
+
+    def __radd__(self, other) -> int:
+        return 42
+
+class B(A): ...
+
+reveal_type(A() + B())  # revealed: str
+```
+
+## Only reflected supported
+
+For example, at runtime, `(1).__add__(1.2)` is `NotImplemented`, but `(1.2).__radd__(1) == 2.2`,
+meaning that `1 + 1.2` succeeds at runtime (producing `2.2`). The runtime tries the second one only
+if the first one returns `NotImplemented` to signal failure.
+
+Typeshed and other stubs annotate dunder-method calls that would return `NotImplemented` as being
+"illegal" calls. `int.__add__` is annotated as only "accepting" `int`s, even though it
+strictly-speaking "accepts" any other object without raising an exception -- it will simply return
+`NotImplemented`, allowing the runtime to try the `__radd__` method of the right-hand operand as
+well.
+
+```py
+class A:
+    def __sub__(self, other: "A") -> "A":
+        return A()
+
+class B:
+    def __rsub__(self, other: A) -> "B":
+        return B()
+
+reveal_type(A() - B())  # revealed: B
+```
+
+## Callable instances as dunders
+
+Believe it or not, this is supported at runtime:
+
+```py
+class A:
+    def __call__(self, other) -> int:
+        return 42
+
+class B:
+    __add__ = A()
+
+reveal_type(B() + B())  # revealed: Unknown | int
+```
+
+Note that we union with `Unknown` here because `__add__` is not declared. We do infer just `int` if
+the callable is declared:
+
+```py
+class B2:
+    __add__: A = A()
+
+reveal_type(B2() + B2())  # revealed: int
+```
+
+## Integration test: numbers from typeshed
+
+We get less precise results from binary operations on float/complex literals due to the special case
+for annotations of `float` or `complex`, which applies also to return annotations for typeshed
+dunder methods. Perhaps we could have a special-case on the special-case, to exclude these typeshed
+return annotations from the widening, and preserve a bit more precision here?
+
+```py
+reveal_type(3j + 3.14)  # revealed: int | float | complex
+reveal_type(4.2 + 42)  # revealed: int | float
+reveal_type(3j + 3)  # revealed: int | float | complex
+reveal_type(3.14 + 3j)  # revealed: int | float | complex
+reveal_type(42 + 4.2)  # revealed: int | float
+reveal_type(3 + 3j)  # revealed: int | float | complex
+
+def _(x: bool, y: int):
+    reveal_type(x + y)  # revealed: int
+    reveal_type(4.2 + x)  # revealed: int | float
+    reveal_type(y + 4.12)  # revealed: int | float
+```
+
+## With literal types
+
+When we have a literal type for one operand, we're able to fall back to the instance handling for
+its instance super-type.
+
+```py
+class A:
+    def __add__(self, other) -> "A":
+        return self
+
+    def __radd__(self, other) -> "A":
+        return self
+
+reveal_type(A() + 1)  # revealed: A
+reveal_type(1 + A())  # revealed: A
+
+reveal_type(A() + "foo")  # revealed: A
+reveal_type("foo" + A())  # revealed: A
+
+reveal_type(A() + b"foo")  # revealed: A
+# TODO should be `A` since `bytes.__add__` doesn't support `A` instances
+reveal_type(b"foo" + A())  # revealed: bytes
+
+reveal_type(A() + ())  # revealed: A
+# TODO this should be `A`, since `tuple.__add__` doesn't support `A` instances
+reveal_type(() + A())  # revealed: @Todo(full tuple[...] support)
+
+literal_string_instance = "foo" * 1_000_000_000
+# the test is not testing what it's meant to be testing if this isn't a `LiteralString`:
+reveal_type(literal_string_instance)  # revealed: LiteralString
+
+reveal_type(A() + literal_string_instance)  # revealed: A
+reveal_type(literal_string_instance + A())  # revealed: A
+```
+
+## Operations involving instances of classes inheriting from `Any`
+
+`Any` and `Unknown` represent a set of possible runtime objects, wherein the bounds of the set are
+unknown. Whether the left-hand operand's dunder or the right-hand operand's reflected dunder depends
+on whether the right-hand operand is an instance of a class that is a subclass of the left-hand
+operand's class and overrides the reflected dunder. In the following example, because of the
+unknowable nature of `Any`/`Unknown`, we must consider both possibilities: `Any`/`Unknown` might
+resolve to an unknown third class that inherits from `X` and overrides `__radd__`; but it also might
+not. Thus, the correct answer here for the `reveal_type` is `int | Unknown`.
+
+```py
+from does_not_exist import Foo  # error: [unresolved-import]
+
+reveal_type(Foo)  # revealed: Unknown
+
+class X:
+    def __add__(self, other: object) -> int:
+        return 42
+
+class Y(Foo): ...
+
+# TODO: Should be `int | Unknown`; see above discussion.
+reveal_type(X() + Y())  # revealed: int
+```
+
+## Operations involving types with invalid `__bool__` methods
+
+<!-- snapshot-diagnostics -->
+
+```py
+class NotBoolable:
+    __bool__: int = 3
+
+a = NotBoolable()
+
+# error: [unsupported-bool-conversion]
+10 and a and True
+```
+
+## Operations on class objects
+
+When operating on class objects, the corresponding dunder methods are looked up on the metaclass.
+
+```py
+from __future__ import annotations
+
+class Meta(type):
+    def __add__(self, other: Meta) -> int:
+        return 1
+
+    def __lt__(self, other: Meta) -> bool:
+        return True
+
+    def __getitem__(self, key: int) -> str:
+        return "a"
+
+class A(metaclass=Meta): ...
+class B(metaclass=Meta): ...
+
+reveal_type(A + B)  # revealed: int
+# error: [unsupported-operator] "Operator `-` is unsupported between objects of type `Literal[A]` and `Literal[B]`"
+reveal_type(A - B)  # revealed: Unknown
+
+reveal_type(A < B)  # revealed: bool
+reveal_type(A > B)  # revealed: bool
+
+# error: [unsupported-operator] "Operator `<=` is not supported for types `Literal[A]` and `Literal[B]`"
+reveal_type(A <= B)  # revealed: Unknown
+
+reveal_type(A[0])  # revealed: str
+```
+
+## Unsupported
+
+### Dunder as instance attribute
+
+The magic method must exist on the class, not just on the instance:
+
+```py
+def add_impl(self, other) -> int:
+    return 1
+
+class A:
+    def __init__(self):
+        self.__add__ = add_impl
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `A` and `A`"
+# revealed: Unknown
+reveal_type(A() + A())
+```
+
+### Missing dunder
+
+```py
+class A: ...
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(A() + A())
+```
+
+### Wrong position
+
+A left-hand dunder method doesn't apply for the right-hand operand, or vice versa:
+
+```py
+class A:
+    def __add__(self, other) -> int:
+        return 1
+
+class B:
+    def __radd__(self, other) -> int:
+        return 1
+
+class C: ...
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(C() + A())
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(B() + C())
+```
+
+### Reflected dunder is not tried between two objects of the same type
+
+For the specific case where the left-hand operand is the exact same type as the right-hand operand,
+the reflected dunder of the right-hand operand is not tried; the runtime short-circuits after trying
+the unreflected dunder of the left-hand operand. For context, see
+[this mailing list discussion](https://mail.python.org/archives/list/python-dev@python.org/thread/7NZUCODEAPQFMRFXYRMGJXDSIS3WJYIV/).
+
+```py
+class Foo:
+    def __radd__(self, other: "Foo") -> "Foo":
+        return self
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(Foo() + Foo())
+```
+
+### Wrong type
+
+TODO: check signature and error if `other` is the wrong type
--- a/crates/ty_python_semantic/resources/mdtest/binary/integers.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/integers.md
@ -0,0 +1,112 @@
+# Binary operations on integers
+
+## Basic Arithmetic
+
+```py
+reveal_type(2 + 1)  # revealed: Literal[3]
+reveal_type(3 - 4)  # revealed: Literal[-1]
+reveal_type(3 * -1)  # revealed: Literal[-3]
+reveal_type(-3 // 3)  # revealed: Literal[-1]
+reveal_type(-3 / 3)  # revealed: float
+reveal_type(5 % 3)  # revealed: Literal[2]
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `Literal[2]` and `Literal["f"]`"
+reveal_type(2 + "f")  # revealed: Unknown
+
+def lhs(x: int):
+    reveal_type(x + 1)  # revealed: int
+    reveal_type(x - 4)  # revealed: int
+    reveal_type(x * -1)  # revealed: int
+    reveal_type(x // 3)  # revealed: int
+    reveal_type(x / 3)  # revealed: int | float
+    reveal_type(x % 3)  # revealed: int
+
+def rhs(x: int):
+    reveal_type(2 + x)  # revealed: int
+    reveal_type(3 - x)  # revealed: int
+    reveal_type(3 * x)  # revealed: int
+    reveal_type(-3 // x)  # revealed: int
+    reveal_type(-3 / x)  # revealed: int | float
+    reveal_type(5 % x)  # revealed: int
+
+def both(x: int):
+    reveal_type(x + x)  # revealed: int
+    reveal_type(x - x)  # revealed: int
+    reveal_type(x * x)  # revealed: int
+    reveal_type(x // x)  # revealed: int
+    reveal_type(x / x)  # revealed: int | float
+    reveal_type(x % x)  # revealed: int
+```
+
+## Power
+
+For power if the result fits in the int literal type it will be a Literal type. Otherwise the
+outcome is int.
+
+```py
+largest_u32 = 4_294_967_295
+reveal_type(2**2)  # revealed: Literal[4]
+reveal_type(1 ** (largest_u32 + 1))  # revealed: int
+reveal_type(2**largest_u32)  # revealed: int
+
+def variable(x: int):
+    reveal_type(x**2)  # revealed: int
+    # TODO: should be `Any` (overload 5 on `__pow__`), requires correct overload matching
+    reveal_type(2**x)  # revealed: int
+    # TODO: should be `Any` (overload 5 on `__pow__`), requires correct overload matching
+    reveal_type(x**x)  # revealed: int
+```
+
+If the second argument is \<0, a `float` is returned at runtime. If the first argument is \<0 but
+the second argument is >=0, an `int` is still returned:
+
+```py
+reveal_type(1**0)  # revealed: Literal[1]
+reveal_type(0**1)  # revealed: Literal[0]
+reveal_type(0**0)  # revealed: Literal[1]
+reveal_type((-1) ** 2)  # revealed: Literal[1]
+reveal_type(2 ** (-1))  # revealed: float
+reveal_type((-1) ** (-1))  # revealed: float
+```
+
+## Division by Zero
+
+This error is really outside the current Python type system, because e.g. `int.__truediv__` and
+friends are not annotated to indicate that it's an error, and we don't even have a facility to
+permit such an annotation. So arguably divide-by-zero should be a lint error rather than a type
+checker error. But we choose to go ahead and error in the cases that are very likely to be an error:
+dividing something typed as `int` or `float` by something known to be `Literal[0]`.
+
+This isn't _definitely_ an error, because the object typed as `int` or `float` could be an instance
+of a custom subclass which overrides division behavior to handle zero without error. But if this
+unusual case occurs, the error can be avoided by explicitly typing the dividend as that safe custom
+subclass; we only emit the error if the LHS type is exactly `int` or `float`, not if its a subclass.
+
+```py
+a = 1 / 0  # error: "Cannot divide object of type `Literal[1]` by zero"
+reveal_type(a)  # revealed: float
+
+b = 2 // 0  # error: "Cannot floor divide object of type `Literal[2]` by zero"
+reveal_type(b)  # revealed: int
+
+c = 3 % 0  # error: "Cannot reduce object of type `Literal[3]` modulo zero"
+reveal_type(c)  # revealed: int
+
+# error: "Cannot divide object of type `int` by zero"
+reveal_type(int() / 0)  # revealed: int | float
+
+# error: "Cannot divide object of type `Literal[1]` by zero"
+reveal_type(1 / False)  # revealed: float
+# error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+True / False
+# error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+bool(1) / False
+
+# error: "Cannot divide object of type `float` by zero"
+reveal_type(1.0 / 0)  # revealed: int | float
+
+class MyInt(int): ...
+
+# No error for a subclass of int
+reveal_type(MyInt(3) / 0)  # revealed: int | float
+```
--- a/crates/ty_python_semantic/resources/mdtest/binary/tuples.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/tuples.md
@ -0,0 +1,22 @@
+# Binary operations on tuples
+
+## Concatenation for heterogeneous tuples
+
+```py
+reveal_type((1, 2) + (3, 4))  # revealed: tuple[Literal[1], Literal[2], Literal[3], Literal[4]]
+reveal_type(() + (1, 2))  # revealed: tuple[Literal[1], Literal[2]]
+reveal_type((1, 2) + ())  # revealed: tuple[Literal[1], Literal[2]]
+reveal_type(() + ())  # revealed: tuple[()]
+
+def _(x: tuple[int, str], y: tuple[None, tuple[int]]):
+    reveal_type(x + y)  # revealed: tuple[int, str, None, tuple[int]]
+    reveal_type(y + x)  # revealed: tuple[None, tuple[int], int, str]
+```
+
+## Concatenation for homogeneous tuples
+
+```py
+def _(x: tuple[int, ...], y: tuple[str, ...]):
+    reveal_type(x + y)  # revealed: @Todo(full tuple[...] support)
+    reveal_type(x + (1, 2))  # revealed: @Todo(full tuple[...] support)
+```
--- a/crates/ty_python_semantic/resources/mdtest/binary/unions.md
+++ b/crates/ty_python_semantic/resources/mdtest/binary/unions.md
@ -0,0 +1,59 @@
+# Binary operations on union types
+
+Binary operations on union types are only available if they are supported for all possible
+combinations of types:
+
+```py
+def f1(i: int, u: int | None):
+    # error: [unsupported-operator] "Operator `+` is unsupported between objects of type `int` and `int | None`"
+    reveal_type(i + u)  # revealed: Unknown
+    # error: [unsupported-operator] "Operator `+` is unsupported between objects of type `int | None` and `int`"
+    reveal_type(u + i)  # revealed: Unknown
+```
+
+`int` can be added to `int`, and `str` can be added to `str`, but expressions of type `int | str`
+cannot be added, because that would require addition of `int` and `str` or vice versa:
+
+```py
+def f2(i: int, s: str, int_or_str: int | str):
+    i + i
+    s + s
+    # error: [unsupported-operator] "Operator `+` is unsupported between objects of type `int | str` and `int | str`"
+    reveal_type(int_or_str + int_or_str)  # revealed: Unknown
+```
+
+However, if an operation is supported for all possible combinations, the result will be a union of
+the possible outcomes:
+
+```py
+from typing import Literal
+
+def f3(two_or_three: Literal[2, 3], a_or_b: Literal["a", "b"]):
+    reveal_type(two_or_three + two_or_three)  # revealed: Literal[4, 5, 6]
+    reveal_type(two_or_three**two_or_three)  # revealed: Literal[4, 8, 9, 27]
+
+    reveal_type(a_or_b + a_or_b)  # revealed: Literal["aa", "ab", "ba", "bb"]
+
+    reveal_type(two_or_three * a_or_b)  # revealed: Literal["aa", "bb", "aaa", "bbb"]
+```
+
+We treat a type annotation of `float` as a union of `int` and `float`, so union handling is relevant
+here:
+
+```py
+def f4(x: float, y: float):
+    reveal_type(x + y)  # revealed: int | float
+    reveal_type(x - y)  # revealed: int | float
+    reveal_type(x * y)  # revealed: int | float
+    reveal_type(x / y)  # revealed: int | float
+    reveal_type(x // y)  # revealed: int | float
+    reveal_type(x % y)  # revealed: int | float
+```
+
+If any of the union elements leads to a division by zero, we will report an error:
+
+```py
+def f5(m: int, n: Literal[-1, 0, 1]):
+    # error: [division-by-zero] "Cannot divide object of type `int` by zero"
+    return m / n
+```