Clarifications

* "remaining" overloads => "candidate" overloads
* moar tests

Author: rchen152

conformance/results/mypy/overloads_evaluation.toml

@@ -18,6 +18,7 @@ Line 268: Unexpected errors ['overloads_evaluation.py:268: error: Expression is
 Line 284: Unexpected errors ['overloads_evaluation.py:284: error: Expression is of type "list[Any]", not "Any"  [assert-type]']
 Line 306: Unexpected errors ['overloads_evaluation.py:306: error: Expression is of type "Any", not "float"  [assert-type]']
 Line 350: Unexpected errors ['overloads_evaluation.py:350: error: Expression is of type "list[Any]", not "Any"  [assert-type]']
+Line 395: Unexpected errors ['overloads_evaluation.py:395: error: Expression is of type "Any", not "int"  [assert-type]']
 """
 output = """
 overloads_evaluation.py:38: error: All overload variants of "example1_1" require at least one argument  [call-overload]
@@ -50,4 +51,5 @@ overloads_evaluation.py:268: error: Expression is of type "list[Any]", not "Any"
 overloads_evaluation.py:284: error: Expression is of type "list[Any]", not "Any"  [assert-type]
 overloads_evaluation.py:306: error: Expression is of type "Any", not "float"  [assert-type]
 overloads_evaluation.py:350: error: Expression is of type "list[Any]", not "Any"  [assert-type]
+overloads_evaluation.py:395: error: Expression is of type "Any", not "int"  [assert-type]
 """

conformance/results/pyright/overloads_evaluation.toml

@@ -6,7 +6,7 @@ Picks first overload instead of most general return type in some cases where ove
 conformance_automated = "Fail"
 errors_diff = """
 Line 284: Unexpected errors ['overloads_evaluation.py:284:17 - error: "assert_type" mismatch: expected "Any" but received "list[int]" (reportAssertTypeFailure)']
-Line 398: Unexpected errors ['overloads_evaluation.py:398:17 - error: "assert_type" mismatch: expected "A[Any]" but received "A[None]" (reportAssertTypeFailure)']
+Line 464: Unexpected errors ['overloads_evaluation.py:464:17 - error: "assert_type" mismatch: expected "A[Any]" but received "A[None]" (reportAssertTypeFailure)']
 """
 output = """
 overloads_evaluation.py:38:1 - error: No overloads for "example1_1" match the provided arguments
@@ -23,5 +23,5 @@ overloads_evaluation.py:116:17 - error: Argument of type "int | str" cannot be a
   Type "int | str" is not assignable to type "int"
     "str" is not assignable to "int" (reportArgumentType)
 overloads_evaluation.py:284:17 - error: "assert_type" mismatch: expected "Any" but received "list[int]" (reportAssertTypeFailure)
-overloads_evaluation.py:398:17 - error: "assert_type" mismatch: expected "A[Any]" but received "A[None]" (reportAssertTypeFailure)
+overloads_evaluation.py:464:17 - error: "assert_type" mismatch: expected "A[Any]" but received "A[None]" (reportAssertTypeFailure)
 """

conformance/results/ty/overloads_evaluation.toml

@@ -4,12 +4,14 @@ Returns Any instead of most general return type for ambiguous calls.
 """
 conformance_automated = "Fail"
 errors_diff = """
-Line 398: Unexpected errors ['overloads_evaluation.py:398:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `A[Any]`']
+Line 395: Unexpected errors ['overloads_evaluation.py:395:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `int`']
+Line 464: Unexpected errors ['overloads_evaluation.py:464:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `A[Any]`']
 """
 output = """
 overloads_evaluation.py:38:1: error[no-matching-overload] No overload of function `example1_1` matches arguments
 overloads_evaluation.py:46:15: error[invalid-argument-type] Argument to function `example1_1` is incorrect: Expected `str`, found `Literal[1]`
 overloads_evaluation.py:51:12: error[invalid-argument-type] Argument to function `example1_1` is incorrect: Expected `str`, found `Literal[1]`
 overloads_evaluation.py:116:5: error[no-matching-overload] No overload of function `example2` matches arguments
-overloads_evaluation.py:398:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `A[Any]`
+overloads_evaluation.py:395:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `int`
+overloads_evaluation.py:464:5: error[type-assertion-failure] Type `Unknown` does not match asserted type `A[Any]`
 """

conformance/results/zuban/overloads_evaluation.toml

@@ -4,7 +4,8 @@ Returns Any instead of most general return type for ambiguous calls.
 """
 conformance_automated = "Fail"
 errors_diff = """
-Line 398: Unexpected errors ['overloads_evaluation.py:398: error: Expression is of type "Any", not "A[Any]"  [misc]']
+Line 395: Unexpected errors ['overloads_evaluation.py:395: error: Expression is of type "Any", not "int"  [misc]']
+Line 464: Unexpected errors ['overloads_evaluation.py:464: error: Expression is of type "Any", not "A[Any]"  [misc]']
 """
 output = """
 overloads_evaluation.py:38: error: All overload variants of "example1_1" require at least one argument  [call-overload]
@@ -21,5 +22,6 @@ overloads_evaluation.py:51: note:     def example1_1(x: int, y: str) -> int
 overloads_evaluation.py:51: note:     def example1_1(x: str) -> str
 overloads_evaluation.py:116: error: Argument 1 to "example2" has incompatible type "int | str"; expected "int"  [arg-type]
 overloads_evaluation.py:116: error: Argument 2 to "example2" has incompatible type "int | str"; expected "str"  [arg-type]
-overloads_evaluation.py:398: error: Expression is of type "Any", not "A[Any]"  [misc]
+overloads_evaluation.py:395: error: Expression is of type "Any", not "int"  [misc]
+overloads_evaluation.py:464: error: Expression is of type "Any", not "A[Any]"  [misc]
 """

conformance/tests/overloads_evaluation.py

@@ -371,6 +371,72 @@ def check_example8(x: Any):
     assert_type(ret, bool)
 
 
+@overload
+def example9(x: str, y: Literal['o1']) -> bool: ...
+
+
+@overload
+def example9(x: bytes, y: Literal['o1', 'o2']) -> bool: ...
+
+
+@overload
+def example9(x: bytes, y: str) -> int: ...
+
+
+def example9(x: str | bytes, y: str) -> bool | int:
+    return True
+
+
+def check_example9(x: Any):
+    # All three overloads are candidates. The parameter types corresponding to
+    # argument `x` are `str` and `bytes`, which are not equivalent, so none of
+    # the overloads can be eliminated. We pick the most general return type.
+    ret1 = example9(x, 'o1')
+    assert_type(ret1, int)
+    # The second and third overload are candidates. The parameter type
+    # corresponding to argument `x` is `bytes` in both candidates, so we can
+    # eliminate the third overload.
+    ret2 = example9(x, 'o2')
+    assert_type(ret2, bool)
+
+
+@overload
+def example10(x: int) -> bool: ...
+
+
+@overload
+def example10(*args: int) -> int: ...
+
+
+def example10(*args: int, **kwargs: int) -> int:
+    return 0
+
+
+def check_example10(x: Any):
+    # The parameters corresponding to argument `x` (`x` in the first overload
+    # and `*args` in the second) both have type `int`, so the second overload
+    # can be eliminated.
+    assert_type(example10(x), bool)
+
+
+@overload
+def example11(x: int) -> bool: ...
+
+
+@overload
+def example11(**kwargs: int) -> int: ...
+
+
+def example11(*args: int, **kwargs: int) -> int:
+    return 0
+
+def check_example11(x: Any):
+    # The parameters corresponding to argument `x` (`x` in the first overload
+    # and `**kwargs` in the second) both have type `int`, so the second
+    # overload can be eliminated.
+    assert_type(example11(x=x), bool)
+
+
 class A[T]:
     x: T
 
@@ -379,20 +445,20 @@ def f(self) -> T:
 
 
 @overload
-def example9(x: A[None]) -> A[None]: ...
+def example12(x: A[None]) -> A[None]: ...
 
 
 @overload
-def example9(x: A[Any]) -> A[Any]: ...
+def example12(x: A[Any]) -> A[Any]: ...
 
 
-def example9(x: A[Any]) -> A[Any]:
+def example12(x: A[Any]) -> A[Any]:
     return x
 
 
-def check_example9(x: Any):
+def check_example12(x: Any):
     # Step 5 eliminates the first overload because there exists a
     # materialization of `A[Any]` that is not assignable to `A[None]`. Step 6
     # picks the second overload.
-    ret = example9(x)
+    ret = example12(x)
     assert_type(ret, A[Any])

docs/spec/overload.rst

@@ -268,15 +268,15 @@ If so, eliminate overloads that do not have a variadic parameter.
 Step 5
 ~~~~~~
 
-For each of the remaining overloads, determine whether all arguments satisfy at
+For each of the candidate overloads, determine whether all arguments satisfy at
 least one of the following conditions:
 
 - All possible :term:`materializations <materialize>` of the argument's type are
   assignable to the corresponding parameter type, or
-- The parameter types corresponding to this argument in all of the remaining overloads
+- The parameter types corresponding to this argument in all of the candidate overloads
   are :term:`equivalent`.
 
-If so, eliminate all of the subsequent remaining overloads.
+If so, eliminate all of the subsequent candidate overloads.
 
 Consider the following examples::