Update to the Overloads chapter (#1839)

* First draft of an update to the Overloads chapter.
* Attempts to clearly define the algorithm for overload matching.
* Describes checks for overload consistency, overlapping overloads, and implementation consistency.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Updated draft based on initial round of feedback.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Fixed reference.

* Fixed reference.

* Another reference fix.

* Incorporated PR feedback.

* Made changes to proposed overload chapter based on reviewer feedback.

* Incorporated additional feedback from reviewers.

* Incorporated more feedback.

* Fixed typo in code sample.

* Update docs/spec/overload.rst

Co-authored-by: Eneg <[email protected]>

* (very) initial steps on conformance tests

* fix abstractmethod without implementation check

* split overloads_invalid.py from overloads_basic.py

* add test for final with overload

* add tests for correct usage of override with an overload

* add test for wrong use of override with overload

* rename overloads_invalid to overloads_definitions

* add support for stub test files, add overloads_definitions_stub.pyi

* add initial overloads_consistency tests

* add tests for mixed async-def

* add tests for signature-transforming decorators

* add test for partially overlapping overloads

* add test for fully overlapping overloads

* add tests for step-1 of overload evaluation

* add tests for steps 2 and 3 of overload evaluation

* add tests for bool expansion (no checker does this)

* add tests for enum and tuple expansion

* add test for type[A | B] expansion

* add test for step 4 in overload matching

* add test for steps 5/6 in overload matching

* no expectation of return type if there are call errors

* improve variadic test to not use overlapping overloads

* Apply suggestions from code review

Co-authored-by: Alex Waygood <[email protected]>

* Update conformance/tests/overloads_consistency.py

* Removed section on overlapping overloads. We're struggling to get agreement on the proper behavior, and this section is lower priority. We can revisit in the future if there's a desire to do so.

* Updated Step 5 of overload algorithm based on PR feedback.

* Fixed bug in conformance test.
Updated conformance results for latest versions of type checkers.
Removed outdated references to "overlapping overloads" in spec.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eneg <[email protected]>
Co-authored-by: Carl Meyer <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 6 people

conformance/results/mypy/overloads_basic.toml

@@ -1,11 +1,9 @@
 conformant = "Pass"
 output = """
-overloads_basic.py:37: error: No overload variant of "__getitem__" of "Bytes" matches argument type "str"  [call-overload]
-overloads_basic.py:37: note: Possible overload variants:
-overloads_basic.py:37: note:     def __getitem__(self, int, /) -> int
-overloads_basic.py:37: note:     def __getitem__(self, slice[Any, Any, Any], /) -> bytes
-overloads_basic.py:62: error: Single overload definition, multiple required  [misc]
-overloads_basic.py:74: error: An overloaded function outside a stub file must have an implementation  [no-overload-impl]
+overloads_basic.py:39: error: No overload variant of "__getitem__" of "Bytes" matches argument type "str"  [call-overload]
+overloads_basic.py:39: note: Possible overload variants:
+overloads_basic.py:39: note:     def __getitem__(self, int, /) -> int
+overloads_basic.py:39: note:     def __getitem__(self, slice[Any, Any, Any], /) -> bytes
 """
 conformance_automated = "Pass"
 errors_diff = """

conformance/results/mypy/overloads_consistency.toml

@@ -0,0 +1,8 @@
+conformant = "Pass"
+conformance_automated = "Pass"
+errors_diff = """
+"""
+output = """
+overloads_consistency.py:28: error: Overloaded function implementation cannot produce return type of signature 2  [misc]
+overloads_consistency.py:44: error: Overloaded function implementation does not accept all possible arguments of signature 2  [misc]
+"""

conformance/results/mypy/overloads_definitions.toml

@@ -0,0 +1,24 @@
+conformant = "Partial"
+conformance_automated = "Fail"
+notes = """
+Does not allow an overload with no implementation in an abstract base class.
+Allows @override to be on all overloads and implementation, instead of just implementation.
+"""
+errors_diff = """
+Line 245: Expected 1 errors
+Line 49: Unexpected errors ['overloads_definitions.py:49: error: An overloaded function outside a stub file must have an implementation  [no-overload-impl]']
+"""
+output = """
+overloads_definitions.py:14: error: Single overload definition, multiple required  [misc]
+overloads_definitions.py:26: error: An overloaded function outside a stub file must have an implementation  [no-overload-impl]
+overloads_definitions.py:49: error: An overloaded function outside a stub file must have an implementation  [no-overload-impl]
+overloads_definitions.py:63: error: An overloaded function outside a stub file must have an implementation  [no-overload-impl]
+overloads_definitions.py:78: error: Overload does not consistently use the "@staticmethod" decorator on all function signatures.  [misc]
+overloads_definitions.py:88: error: Overloaded function implementation does not accept all possible arguments of signature 1  [misc]
+overloads_definitions.py:88: error: Overloaded function implementation does not accept all possible arguments of signature 2  [misc]
+overloads_definitions.py:91: error: Overload does not consistently use the "@classmethod" decorator on all function signatures.  [misc]
+overloads_definitions.py:133: error: @final should be applied only to overload implementation  [misc]
+overloads_definitions.py:148: error: @final should be applied only to overload implementation  [misc]
+overloads_definitions.py:196: error: Cannot override final attribute "final_method" (previously declared in base class "Base")  [misc]
+overloads_definitions.py:211: error: Method "bad_override" is marked as an override, but no base method was found with this name  [misc]
+"""

conformance/results/mypy/overloads_definitions_stub.toml

@@ -0,0 +1,18 @@
+conformant = "Partial"
+notes = """
+Allows @override to appear in a stub file not on the first overload.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 168: Expected 1 errors
+"""
+output = """
+overloads_definitions_stub.pyi:13: error: Single overload definition, multiple required  [misc]
+overloads_definitions_stub.pyi:37: error: Overload does not consistently use the "@staticmethod" decorator on all function signatures.  [misc]
+overloads_definitions_stub.pyi:38: error: Self argument missing for a non-static method (or an invalid type for self)  [misc]
+overloads_definitions_stub.pyi:46: error: Overload does not consistently use the "@classmethod" decorator on all function signatures.  [misc]
+overloads_definitions_stub.pyi:85: error: In a stub file @final must be applied only to the first overload  [misc]
+overloads_definitions_stub.pyi:101: error: In a stub file @final must be applied only to the first overload  [misc]
+overloads_definitions_stub.pyi:128: error: Cannot override final attribute "final_method" (previously declared in base class "Base")  [misc]
+overloads_definitions_stub.pyi:140: error: Method "bad_override" is marked as an override, but no base method was found with this name  [misc]
+"""

conformance/results/mypy/overloads_evaluation.toml

@@ -0,0 +1,43 @@
+conformant = "Partial"
+notes = """
+Does not expand boolean arguments to Literal[True] and Literal[False].
+Does not expand enum arguments to literal variants.
+Does not expand tuple arguments to possible combinations.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 106: Unexpected errors ['overloads_evaluation.py:106: error: No overload variant of "expand_bool" matches argument type "bool"  [call-overload]']
+Line 107: Unexpected errors ['overloads_evaluation.py:107: error: Expression is of type "Any", not "Literal[0, 1]"  [assert-type]']
+Line 129: Unexpected errors ['overloads_evaluation.py:129: error: No overload variant of "expand_enum" matches argument type "Color"  [call-overload]']
+Line 130: Unexpected errors ['overloads_evaluation.py:130: error: Expression is of type "Any", not "Literal[0, 1]"  [assert-type]']
+Line 169: Unexpected errors ['overloads_evaluation.py:169: error: Argument 1 to "expand_tuple" has incompatible type "tuple[int, int | str]"; expected "tuple[int, int]"  [arg-type]']
+Line 170: Unexpected errors ['overloads_evaluation.py:170: error: Expression is of type "int", not "int | str"  [assert-type]']
+"""
+output = """
+overloads_evaluation.py:32: error: All overload variants of "example1" require at least one argument  [call-overload]
+overloads_evaluation.py:32: note: Possible overload variants:
+overloads_evaluation.py:32: note:     def example1(x: int, y: str) -> int
+overloads_evaluation.py:32: note:     def example1(x: str) -> str
+overloads_evaluation.py:40: error: No overload variant of "example1" matches argument types "int", "int"  [call-overload]
+overloads_evaluation.py:40: note: Possible overload variants:
+overloads_evaluation.py:40: note:     def example1(x: int, y: str) -> int
+overloads_evaluation.py:40: note:     def example1(x: str) -> str
+overloads_evaluation.py:45: error: No overload variant of "example1" matches argument type "int"  [call-overload]
+overloads_evaluation.py:45: note: Possible overload variants:
+overloads_evaluation.py:45: note:     def example1(x: int, y: str) -> int
+overloads_evaluation.py:45: note:     def example1(x: str) -> str
+overloads_evaluation.py:89: error: Argument 1 to "example2" has incompatible type "int | str"; expected "int"  [arg-type]
+overloads_evaluation.py:89: error: Argument 2 to "example2" has incompatible type "int | str"; expected "str"  [arg-type]
+overloads_evaluation.py:106: error: No overload variant of "expand_bool" matches argument type "bool"  [call-overload]
+overloads_evaluation.py:106: note: Possible overload variants:
+overloads_evaluation.py:106: note:     def expand_bool(x: Literal[False]) -> Literal[0]
+overloads_evaluation.py:106: note:     def expand_bool(x: Literal[True]) -> Literal[1]
+overloads_evaluation.py:107: error: Expression is of type "Any", not "Literal[0, 1]"  [assert-type]
+overloads_evaluation.py:129: error: No overload variant of "expand_enum" matches argument type "Color"  [call-overload]
+overloads_evaluation.py:129: note: Possible overload variants:
+overloads_evaluation.py:129: note:     def expand_enum(x: Literal[Color.RED]) -> Literal[0]
+overloads_evaluation.py:129: note:     def expand_enum(x: Literal[Color.BLUE]) -> Literal[1]
+overloads_evaluation.py:130: error: Expression is of type "Any", not "Literal[0, 1]"  [assert-type]
+overloads_evaluation.py:169: error: Argument 1 to "expand_tuple" has incompatible type "tuple[int, int | str]"; expected "tuple[int, int]"  [arg-type]
+overloads_evaluation.py:170: error: Expression is of type "int", not "int | str"  [assert-type]
+"""

conformance/results/mypy/version.toml

@@ -1,2 +1,2 @@
 version = "mypy 1.15.0"
-test_duration = 1.7
+test_duration = 1.6

conformance/results/pyre/overloads_basic.toml

@@ -1,10 +1,6 @@
 conformant = "Pass"
-notes = """
-"""
 output = """
-overloads_basic.py:37:2 Incompatible parameter type [6]: In call `Bytes.__getitem__`, for 1st positional argument, expected `int` but got `str`.
-overloads_basic.py:63:0 Incompatible overload [43]: At least two overload signatures must be present.
-overloads_basic.py:75:0 Missing overload implementation [42]: Overloaded function `func2` must have an implementation.
+overloads_basic.py:39:2 Incompatible parameter type [6]: In call `Bytes.__getitem__`, for 1st positional argument, expected `int` but got `str`.
 """
 conformance_automated = "Pass"
 errors_diff = """

conformance/results/pyre/overloads_consistency.toml

@@ -0,0 +1,18 @@
+conformant = "Partial"
+notes = """
+Does not apply decorator transforms before checking overload consistency.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 108: Unexpected errors ['overloads_consistency.py:108:0 Incompatible overload [43]: The return type of overloaded function `decorated` (`None`) is incompatible with the return type of the implementation (`bytes`).', 'overloads_consistency.py:108:0 Incompatible overload [43]: The implementation of `decorated` does not accept all possible arguments of overload defined on line `108`.']
+Line 112: Unexpected errors ['overloads_consistency.py:112:0 Incompatible overload [43]: The return type of overloaded function `decorated` (`str`) is incompatible with the return type of the implementation (`bytes`).', 'overloads_consistency.py:112:0 Incompatible overload [43]: The implementation of `decorated` does not accept all possible arguments of overload defined on line `112`.', 'overloads_consistency.py:112:0 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+"""
+output = """
+overloads_consistency.py:25:0 Incompatible overload [43]: The return type of overloaded function `return_type` (`str`) is incompatible with the return type of the implementation (`int`).
+overloads_consistency.py:41:0 Incompatible overload [43]: The implementation of `parameter_type` does not accept all possible arguments of overload defined on line `41`.
+overloads_consistency.py:108:0 Incompatible overload [43]: The return type of overloaded function `decorated` (`None`) is incompatible with the return type of the implementation (`bytes`).
+overloads_consistency.py:108:0 Incompatible overload [43]: The implementation of `decorated` does not accept all possible arguments of overload defined on line `108`.
+overloads_consistency.py:112:0 Incompatible overload [43]: The return type of overloaded function `decorated` (`str`) is incompatible with the return type of the implementation (`bytes`).
+overloads_consistency.py:112:0 Incompatible overload [43]: The implementation of `decorated` does not accept all possible arguments of overload defined on line `112`.
+overloads_consistency.py:112:0 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+"""

conformance/results/pyre/overloads_definitions.toml

@@ -0,0 +1,32 @@
+conformant = "Partial"
+conformance_automated = "Fail"
+notes = """
+Does not allow an overload with no implementation in a Protocol or an abstract base class.
+Expects @final/@override on all overloads and implementation, instead of implementation only.
+"""
+errors_diff = """
+Line 245: Expected 1 errors
+Lines 148, 150: Expected error (tag 'invalid_final_2')
+Line 40: Unexpected errors ['overloads_definitions.py:40:4 Missing overload implementation [42]: Overloaded function `MyProto.func3` must have an implementation.']
+Line 51: Unexpected errors ['overloads_definitions.py:51:4 Missing overload implementation [42]: Overloaded function `MyAbstractBase.func4` must have an implementation.']
+Line 128: Unexpected errors ['overloads_definitions.py:128:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+Line 239: Unexpected errors ['overloads_definitions.py:239:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+"""
+output = """
+overloads_definitions.py:15:0 Incompatible overload [43]: At least two overload signatures must be present.
+overloads_definitions.py:27:0 Missing overload implementation [42]: Overloaded function `func2` must have an implementation.
+overloads_definitions.py:40:4 Missing overload implementation [42]: Overloaded function `MyProto.func3` must have an implementation.
+overloads_definitions.py:51:4 Missing overload implementation [42]: Overloaded function `MyAbstractBase.func4` must have an implementation.
+overloads_definitions.py:64:4 Missing overload implementation [42]: Overloaded function `MyAbstractBase.not_abstract` must have an implementation.
+overloads_definitions.py:80:4 Incompatible overload [43]: The implementation of `C.func5` does not accept all possible arguments of overload defined on line `80`.
+overloads_definitions.py:85:4 Incompatible overload [43]: The implementation of `C.func5` does not accept all possible arguments of overload defined on line `85`.
+overloads_definitions.py:88:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions.py:97:4 Incompatible overload [43]: The implementation of `C.func6` does not accept all possible arguments of overload defined on line `97`.
+overloads_definitions.py:97:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions.py:128:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions.py:139:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions.py:204:4 Invalid override [40]: `overloads_definitions.Child.final_method` cannot override final method defined in `Base`.
+overloads_definitions.py:220:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions.py:220:4 Invalid override [40]: `overloads_definitions.Child.bad_override` is decorated with @override, but no method of the same name exists in superclasses of `Child`.
+overloads_definitions.py:239:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+"""

conformance/results/pyre/overloads_definitions_stub.toml

@@ -0,0 +1,27 @@
+conformant = "Partial"
+notes = """
+Expects @final and @override to be present on all overloads, not just first.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 168: Expected 1 errors
+Lines 80, 82, 85, 87: Expected error (tag 'invalid_final')
+Lines 96, 98, 101: Expected error (tag 'invalid_final_2')
+Lines 122, 128, 129, 133: Expected error (tag 'override-final')
+Line 75: Unexpected errors ['overloads_definitions_stub.pyi:75:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+Line 91: Unexpected errors ['overloads_definitions_stub.pyi:91:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+Line 146: Unexpected errors ['overloads_definitions_stub.pyi:146:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+Line 162: Unexpected errors ['overloads_definitions_stub.pyi:162:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+Line 174: Unexpected errors ['overloads_definitions_stub.pyi:174:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).']
+"""
+output = """
+overloads_definitions_stub.pyi:14:0 Incompatible overload [43]: At least two overload signatures must be present.
+overloads_definitions_stub.pyi:43:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:52:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:75:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:91:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:142:4 Invalid override [40]: `overloads_definitions_stub.Child.bad_override` is decorated with @override, but no method of the same name exists in superclasses of `Child`.
+overloads_definitions_stub.pyi:146:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:162:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+overloads_definitions_stub.pyi:174:4 Incompatible overload [43]: This definition does not have the same decorators as the preceding overload(s).
+"""