Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/type-concepts-advanced.md
Original file line number Diff line number Diff line change
Expand Up @@ -326,9 +326,10 @@ Some functions or methods can return one of several different types. In cases wh

3. If only one overload remains, it is the “winner”.

4. If more than one overload remains, the “winner” is chosen based on the order in which the overloads are declared. In general, the first remaining overload is the “winner”. There are two exceptions to this rule.
4. If more than one overload remains, the “winner” is chosen based on the order in which the overloads are declared. In general, the first remaining overload is the “winner”. There are three exceptions to this rule.
Exception 1: When an `*args` (unpacked) argument matches a `*args` parameter in one of the overload signatures, this overrides the normal order-based rule.
Exception 2: When two or more overloads match because an argument evaluates to `Any` or `Unknown`, the matching overload is ambiguous. In this case, pyright examines the return types of the remaining overloads and eliminates types that are duplicates or are subsumed by (i.e. proper subtypes of) other types in the list. If only one type remains after this coalescing step, that type is used. If more than one type remains after this coalescing step, the type of the call expression evaluates to `Unknown`. For example, if two overloads are matched due to an argument that evaluates to `Any`, and those two overloads have return types of `str` and `LiteralString`, pyright will coalesce this to just `str` because `LiteralString` is a proper subtype of `str`. If the two overloads have return types of `str` and `bytes`, the call expression will evaluate to `Unknown` because `str` and `bytes` have no overlap.
Exception 2: When multiple overloads match because an argument contains `Any` or `Unknown` in an invariant type argument, pyright applies the [overload materialization rule](https://typing.python.org/en/latest/spec/overload.html#step-5). An overload that accepts all possible materializations of every argument eliminates all subsequent overloads. If multiple overloads with non-equivalent return types remain, the call evaluates to `Any` when the ambiguity is caused by a nested `Any`, or `Unknown` when it is caused by a nested `Unknown`.
Exception 3: When two or more overloads match because an argument itself evaluates to `Any` or `Unknown`, the matching overload is ambiguous. In this case, pyright examines the return types of the remaining overloads and eliminates types that are duplicates or are subsumed by (i.e. proper subtypes of) other types in the list. If only one type remains after this coalescing step, that type is used. If more than one type remains after this coalescing step, the type of the call expression evaluates to `Unknown`. For example, if two overloads are matched due to an argument that evaluates to `Any`, and those two overloads have return types of `str` and `LiteralString`, pyright will coalesce this to just `str` because `LiteralString` is a proper subtype of `str`. If the two overloads have return types of `str` and `bytes`, the call expression will evaluate to `Unknown` because `str` and `bytes` have no overlap.

5. If no overloads remain, Pyright considers whether any of the arguments are union types. If so, these union types are expanded into their constituent subtypes, and the entire process of overload matching is repeated with the expanded argument types. If two or more overloads match, the union of their respective return types form the final return type for the call expression. This "union expansion" can result in a combinatoric explosion if many arguments evaluate to union types. For example, if four arguments are present, and they all evaluate to unions that expand to ten subtypes, this could result in 10^4 combinations. Pyright expands unions for arguments left to right and halts expansion when the number of signatures exceeds 64.

Expand Down
21 changes: 15 additions & 6 deletions packages/pyright-internal/src/analyzer/constructors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,10 @@ function validateInitMethod(
);

let adjustedClassType = type;

// Overload evaluation keeps the ordinary __init__ return as a placeholder
// and carries argument-dependent constructed types through this separate field,
// including when union-expanded argument lists are combined.
if (
callResult.specializedInitSelfType &&
isClassInstance(callResult.specializedInitSelfType) &&
Expand All @@ -519,12 +523,17 @@ function validateInitMethod(
adjustedClassType = ClassType.cloneAsInstantiable(callResult.specializedInitSelfType);
}

const returnType = applyExpectedTypeForConstructor(
evaluator,
adjustedClassType,
/* inferenceContext */ undefined,
constraints
);
const returnType =
callResult.specializedInitSelfType &&
!type.priv.isTypeArgExplicit &&
(isAny(callResult.specializedInitSelfType) || isUnknown(callResult.specializedInitSelfType))
? callResult.specializedInitSelfType
: applyExpectedTypeForConstructor(
evaluator,
adjustedClassType,
/* inferenceContext */ undefined,
constraints
);

if (callResult.isTypeIncomplete) {
isTypeIncomplete = true;
Expand Down
Loading
Loading