From 6cec139ce8974bdf01a2d078469635228561a8b7 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 26 Aug 2025 15:44:06 +0100 Subject: [PATCH 1/2] Add link anchors for each step of the overload call evaluation algorithm --- docs/spec/overload.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/spec/overload.rst b/docs/spec/overload.rst index 9ddfe601..7b1778da 100644 --- a/docs/spec/overload.rst +++ b/docs/spec/overload.rst @@ -196,8 +196,10 @@ Only the overloads (the ``@overload``-decorated signatures) should be considered for matching purposes. The implementation, if provided, should be ignored for purposes of overload matching. +Step 1 +~~~~~~ -Step 1: Examine the argument list to determine the number of +Examine the argument list to determine the number of positional and keyword arguments. Use this information to eliminate any overload candidates that are not plausible based on their input signatures. @@ -207,8 +209,10 @@ input signatures. it as if it were a non-overloaded function call and stop. - If two or more candidate overloads remain, proceed to step 2. +Step 2 +~~~~~~ -Step 2: Evaluate each remaining overload as a regular (non-overloaded) +Evaluate each remaining overload as a regular (non-overloaded) call to determine whether it is compatible with the supplied argument list. Unlike step 1, this step considers the types of the parameters and arguments. During this step, do not generate any user-visible errors. @@ -219,8 +223,10 @@ Simply record which of the overloads result in evaluation errors. Evaluate it as if it were a non-overloaded function call and stop. - If two or more candidate overloads remain, proceed to step 4. +Step 3 +~~~~~~ -Step 3: If step 2 produces errors for all overloads, perform +If step 2 produces errors for all overloads, perform "argument type expansion". Union types can be expanded into their constituent subtypes. For example, the type ``int | str`` can be expanded into ``int`` and ``str``. @@ -248,8 +254,10 @@ expanded argument lists. For additional details about argument type expansion, see `argument-type-expansion`_ below. +Step 4 +~~~~~~ -Step 4: If the argument list is compatible with two or more overloads, +If the argument list is compatible with two or more overloads, determine whether one or more of the overloads has a variadic parameter (either ``*args`` or ``**kwargs``) that maps to a corresponding argument that supplies an indeterminate number of positional or keyword arguments. @@ -260,8 +268,10 @@ If so, eliminate overloads that do not have a variadic parameter. call and stop. - If two or more candidate overloads remain, proceed to step 5. +Step 5 +~~~~~~ -Step 5: For all arguments, determine whether all possible +For all arguments, determine whether all possible :term:`materializations ` of the argument's type are assignable to the corresponding parameter type for each of the remaining overloads. If so, eliminate all of the subsequent remaining overloads. @@ -295,8 +305,10 @@ for all remaining overloads are :term:`equivalent`, proceed to step 6. If the return types are not equivalent, overload matching is ambiguous. In this case, assume a return type of ``Any`` and stop. +Step 6 +~~~~~~ -Step 6: Choose the first remaining candidate overload as the winning +Choose the first remaining candidate overload as the winning match. Evaluate it as if it were a non-overloaded function call and stop. Example 1:: From bdf7f3aa192676f7afea304e71ba2b240a6bf87d Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 26 Aug 2025 15:54:40 +0100 Subject: [PATCH 2/2] put examples in a separate subsection to "Step 6" --- docs/spec/overload.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/spec/overload.rst b/docs/spec/overload.rst index 7b1778da..52982c54 100644 --- a/docs/spec/overload.rst +++ b/docs/spec/overload.rst @@ -311,6 +311,9 @@ Step 6 Choose the first remaining candidate overload as the winning match. Evaluate it as if it were a non-overloaded function call and stop. +Examples +~~~~~~~~ + Example 1:: @overload