From 43132023f1493ebdc9ed8b42d672d31e76ecb2df Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Thu, 6 Aug 2026 18:15:50 -0700 Subject: [PATCH 1/7] Apply overload materialization to nested Any Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/type-concepts-advanced.md | 5 +- .../src/analyzer/constructors.ts | 17 +- .../src/analyzer/typeEvaluator.ts | 488 +++++++++++++++++- .../src/tests/samples/overloadCall11.py | 22 + .../src/tests/samples/overloadCall6.py | 217 +++++++- .../src/tests/typeEvaluator6.test.ts | 7 +- 6 files changed, 713 insertions(+), 43 deletions(-) create mode 100644 packages/pyright-internal/src/tests/samples/overloadCall11.py diff --git a/docs/type-concepts-advanced.md b/docs/type-concepts-advanced.md index 448d02266caa..f81e7f1ec38b 100644 --- a/docs/type-concepts-advanced.md +++ b/docs/type-concepts-advanced.md @@ -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. diff --git a/packages/pyright-internal/src/analyzer/constructors.ts b/packages/pyright-internal/src/analyzer/constructors.ts index 5a2106f41091..34a58fa83dac 100644 --- a/packages/pyright-internal/src/analyzer/constructors.ts +++ b/packages/pyright-internal/src/analyzer/constructors.ts @@ -519,12 +519,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; diff --git a/packages/pyright-internal/src/analyzer/typeEvaluator.ts b/packages/pyright-internal/src/analyzer/typeEvaluator.ts index 7f759ee2af06..f5717eee976f 100644 --- a/packages/pyright-internal/src/analyzer/typeEvaluator.ts +++ b/packages/pyright-internal/src/analyzer/typeEvaluator.ts @@ -444,6 +444,7 @@ interface MatchedOverloadInfo { constraints: ConstraintTracker; argResults: ArgResult[]; returnType: Type; + specializedInitSelfType?: Type; } interface ValidateArgTypeOptions { @@ -9536,13 +9537,15 @@ export function createTypeEvaluator( inferenceContext: InferenceContext | undefined ): CallResult { const returnTypes: Type[] = []; + const specializedInitSelfTypes: Type[] = []; let matchedOverloads: MatchedOverloadInfo[] = []; let isTypeIncomplete = false; - let overloadsUsedForCall: FunctionType[] = []; + const overloadsUsedForCall: FunctionType[] = []; let isDefinitiveMatchFound = false; const speculativeNode = getSpeculativeNodeForCall(errorNode); for (let expandedTypesIndex = 0; expandedTypesIndex < expandedArgTypes.length; expandedTypesIndex++) { + const overloadsUsedStartIndex = overloadsUsedForCall.length; let matchedOverload: FunctionType | undefined; const argTypeOverride = expandedArgTypes[expandedTypesIndex]; const hasArgTypeOverride = argTypeOverride.some((a) => a !== undefined); @@ -9595,10 +9598,15 @@ export function createTypeEvaluator( constraints: effectiveConstraints, returnType: callResult.returnType, argResults: callResult.argResults ?? [], + specializedInitSelfType: callResult.specializedInitSelfType, }; matchedOverloads.push(matchedOverloadInfo); - if (callResult.anyOrUnknownArg || matchResults.unpackedArgOfUnknownLength) { + if ( + callResult.anyOrUnknownArg || + matchResults.unpackedArgOfUnknownLength || + possibleMatchResults.length > 0 + ) { possibleMatchResults.push(matchedOverloadInfo); if (callResult.anyOrUnknownArg) { @@ -9622,22 +9630,58 @@ export function createTypeEvaluator( if (!isDefinitiveMatchFound && possibleMatchResults.length > 0) { possibleMatchResults = filterOverloadMatchesForUnpackedArgs(possibleMatchResults); possibleMatchResults = filterOverloadMatchesForAnyArgs(possibleMatchResults); + overloadsUsedForCall.splice( + overloadsUsedStartIndex, + overloadsUsedForCall.length - overloadsUsedStartIndex, + ...possibleMatchResults.map((result) => result.overload) + ); // Did the filtering produce a single result? If so, we're done. if (possibleMatchResults.length === 1) { - overloadsUsedForCall = [possibleMatchResults[0].overload]; returnTypes.push(possibleMatchResults[0].returnType); matchedOverloads = [possibleMatchResults[0]]; } else { + const firstArgParamPairs = getOverloadArgParamPairs(possibleMatchResults[0]); + let ambiguousMatchIncludesNestedAny = false; + let ambiguousMatchIncludesNestedUnknown = false; + let ambiguousMatchIncludesTopLevelAnyOrUnknown = false; + + firstArgParamPairs.forEach((pair, index) => { + const paramTypes = possibleMatchResults.map((match) => { + const argParamPairs = getOverloadArgParamPairs(match); + return index < argParamPairs.length ? argParamPairs[index].paramType : UnknownType.create(); + }); + + if (!areTypesSame(paramTypes, { treatAnySameAsUnknown: true })) { + if (isAnyOrUnknown(pair.argType)) { + ambiguousMatchIncludesTopLevelAnyOrUnknown = true; + } else { + const anyOrUnknown = getAnyOrUnknownInInvariantPosition(pair.argType); + if (anyOrUnknown && isAny(anyOrUnknown)) { + ambiguousMatchIncludesNestedAny = true; + } else if (anyOrUnknown && isUnknown(anyOrUnknown)) { + ambiguousMatchIncludesNestedUnknown = true; + } + } + } + }); + // Eliminate any return types that are subsumed by other return types. let dedupedMatchResults: Type[] = []; let dedupedResultsIncludeAny = false; + const isInitSelfMaterializationAmbiguity = + (ambiguousMatchIncludesNestedAny || ambiguousMatchIncludesNestedUnknown) && + possibleMatchResults.some((result) => !!result.specializedInitSelfType); + possibleMatchResults.forEach((result) => { + const resultType = isInitSelfMaterializationAmbiguity + ? getEffectiveOverloadReturnType(result) + : result.returnType; let isSubtypeSubsumed = false; for (let dedupedIndex = 0; dedupedIndex < dedupedMatchResults.length; dedupedIndex++) { - if (assignType(dedupedMatchResults[dedupedIndex], result.returnType)) { + if (assignType(dedupedMatchResults[dedupedIndex], resultType)) { const anyOrUnknown = containsAnyOrUnknown( dedupedMatchResults[dedupedIndex], /* recurse */ false @@ -9648,8 +9692,8 @@ export function createTypeEvaluator( dedupedResultsIncludeAny = true; } break; - } else if (assignType(result.returnType, dedupedMatchResults[dedupedIndex])) { - const anyOrUnknown = containsAnyOrUnknown(result.returnType, /* recurse */ false); + } else if (assignType(resultType, dedupedMatchResults[dedupedIndex])) { + const anyOrUnknown = containsAnyOrUnknown(resultType, /* recurse */ false); if (!anyOrUnknown) { dedupedMatchResults[dedupedIndex] = NeverType.createNever(); } else if (isAny(anyOrUnknown)) { @@ -9660,7 +9704,7 @@ export function createTypeEvaluator( } if (!isSubtypeSubsumed) { - dedupedMatchResults.push(result.returnType); + dedupedMatchResults.push(resultType); } }); @@ -9668,7 +9712,14 @@ export function createTypeEvaluator( const combinedTypes = combineTypes(dedupedMatchResults); let returnType = combinedTypes; - if (dedupedMatchResults.length > 1) { + if (ambiguousMatchIncludesNestedUnknown) { + returnType = UnknownType.createPossibleType( + combinedTypes, + possibleMatchInvolvesIncompleteUnknown + ); + } else if (ambiguousMatchIncludesNestedAny && !ambiguousMatchIncludesTopLevelAnyOrUnknown) { + returnType = AnyType.create(); + } else if (dedupedMatchResults.length > 1) { // If one or more of the deduped types is Any or contains Any, // we will assume that the person who defined the overload really // wanted Any rather than Unknown. In cases where the deduped types @@ -9684,7 +9735,12 @@ export function createTypeEvaluator( } } - returnTypes.push(returnType); + if (isInitSelfMaterializationAmbiguity) { + specializedInitSelfTypes.push(returnType); + returnTypes.push(possibleMatchResults[0].returnType); + } else { + returnTypes.push(returnType); + } } } @@ -9721,7 +9777,10 @@ export function createTypeEvaluator( anyOrUnknownArg: finalCallResult.anyOrUnknownArg, returnType: combineTypes(returnTypes), isTypeIncomplete, - specializedInitSelfType: finalCallResult.specializedInitSelfType, + specializedInitSelfType: + specializedInitSelfTypes.length > 0 + ? combineTypes(specializedInitSelfTypes) + : finalCallResult.specializedInitSelfType, overloadsUsedForCall, }; } @@ -9743,6 +9802,314 @@ export function createTypeEvaluator( return unpackedArgsOverloads; } + function getAnyOrUnknownInInvariantPosition(type: Type, recursionCount = 0): AnyType | UnknownType | undefined { + if (recursionCount > maxTypeRecursionCount) { + return undefined; + } + recursionCount++; + + let result: AnyType | UnknownType | undefined; + const addResult = (newResult: AnyType | UnknownType | undefined) => { + if (newResult) { + result = result ? preserveUnknown(result, newResult) : newResult; + } + }; + + if (isUnion(type)) { + doForEachSubtype(type, (subtype) => { + addResult(getAnyOrUnknownInInvariantPosition(subtype, recursionCount)); + }); + return result; + } + + if (!isClass(type)) { + return undefined; + } + + // Tuple entries are covariant, but they can contain an invariant type. + if (type.priv.tupleTypeArgs) { + type.priv.tupleTypeArgs.forEach((typeArg) => { + addResult(getAnyOrUnknownInInvariantPosition(typeArg.type, recursionCount)); + }); + return result; + } + + if (!type.priv.typeArgs) { + return undefined; + } + + inferVarianceForClass(type); + const typeParams = ClassType.getTypeParams(type); + + type.priv.typeArgs.forEach((typeArg, index) => { + const typeParam = index < typeParams.length ? typeParams[index] : undefined; + const variance = typeParam ? TypeVarType.getVariance(typeParam) : Variance.Invariant; + + if (variance === Variance.Invariant) { + addResult(containsAnyOrUnknown(typeArg, /* recurse */ true)); + } else { + addResult(getAnyOrUnknownInInvariantPosition(typeArg, recursionCount)); + } + }); + + return result; + } + + function getEffectiveOverloadReturnType(match: MatchedOverloadInfo): Type { + return match.specializedInitSelfType ?? match.returnType; + } + + function getOverloadArgParamPairs(match: MatchedOverloadInfo): { argType: Type; paramType: Type }[] { + const pairs: { argType: Type; paramType: Type }[] = []; + match.argResults.forEach((argResult, index) => { + const argParam = + index < match.matchResults.argParams.length ? match.matchResults.argParams[index] : undefined; + if (!argParam?.isDefaultArg) { + pairs.push({ + argType: argResult.argType, + paramType: argParam?.paramType ?? UnknownType.create(), + }); + } + }); + + if (match.overload.priv.boundToType && match.overload.priv.strippedFirstParamType) { + pairs.unshift({ + argType: match.overload.priv.boundToType, + paramType: match.overload.priv.strippedFirstParamType, + }); + } + + return pairs; + } + + type MaterializationCoverage = boolean | undefined; + + function combineMaterializationCoverage(results: MaterializationCoverage[]): MaterializationCoverage { + if (results.some((result) => result === false)) { + return false; + } + + return results.some((result) => result === undefined) ? undefined : true; + } + + function areAllMaterializationsEquivalent( + destType: Type, + srcType: Type, + recursionCount = 0 + ): MaterializationCoverage { + if (recursionCount > maxTypeRecursionCount) { + return undefined; + } + recursionCount++; + + if (!containsAnyOrUnknown(srcType, /* recurse */ true)) { + return isTypeSame(destType, srcType, { treatAnySameAsUnknown: true }); + } + + if (isAnyOrUnknown(destType)) { + return true; + } + + if (isTypeSame(destType, srcType, { treatAnySameAsUnknown: true })) { + return true; + } + + if ( + isTypeVar(destType) || + isUnion(destType) || + isFunction(destType) || + isOverloaded(destType) || + (isClass(destType) && ClassType.isProtocolClass(destType)) + ) { + return undefined; + } + + if (isAnyOrUnknown(srcType)) { + return false; + } + + if (isUnion(srcType) || isUnion(destType) || isFunction(srcType) || isFunction(destType)) { + return undefined; + } + + if (!isClass(destType) || !isClass(srcType)) { + return false; + } + + if (!ClassType.isSameGenericClass(destType, srcType)) { + return false; + } + + if (destType.priv.tupleTypeArgs || srcType.priv.tupleTypeArgs) { + const destTupleTypeArgs = destType.priv.tupleTypeArgs; + const srcTupleTypeArgs = srcType.priv.tupleTypeArgs; + if ( + !destTupleTypeArgs || + !srcTupleTypeArgs || + destTupleTypeArgs.length !== srcTupleTypeArgs.length || + destTupleTypeArgs.some( + (destTypeArg, index) => destTypeArg.isUnbounded !== srcTupleTypeArgs[index].isUnbounded + ) + ) { + return false; + } + + return combineMaterializationCoverage( + srcTupleTypeArgs.map((srcTypeArg, index) => + areAllMaterializationsEquivalent(destTupleTypeArgs[index].type, srcTypeArg.type, recursionCount) + ) + ); + } + + const destTypeArgs = destType.priv.typeArgs; + const srcTypeArgs = srcType.priv.typeArgs; + if (!destTypeArgs || !srcTypeArgs || destTypeArgs.length !== srcTypeArgs.length) { + return false; + } + + return combineMaterializationCoverage( + srcTypeArgs.map((srcTypeArg, index) => + areAllMaterializationsEquivalent(destTypeArgs[index], srcTypeArg, recursionCount) + ) + ); + } + + function areAllMaterializationsAssignable( + destType: Type, + srcType: Type, + recursionCount = 0 + ): MaterializationCoverage { + if (recursionCount > maxTypeRecursionCount) { + return undefined; + } + recursionCount++; + + if (!containsAnyOrUnknown(srcType, /* recurse */ true)) { + return assignType(destType, srcType); + } + + if (isAnyOrUnknown(destType)) { + return true; + } + + if (isTypeSame(destType, srcType, { treatAnySameAsUnknown: true })) { + return true; + } + + if ( + isTypeVar(destType) || + isUnion(destType) || + isFunction(destType) || + isOverloaded(destType) || + (isClass(destType) && ClassType.isProtocolClass(destType)) + ) { + return undefined; + } + + if (isAnyOrUnknown(srcType)) { + if (isTypeVar(destType)) { + return false; + } + return assignType(destType, getObjectType()); + } + + if ( + isUnion(srcType) || + isUnion(destType) || + isFunction(srcType) || + isFunction(destType) || + isOverloaded(srcType) || + isOverloaded(destType) + ) { + return undefined; + } + + if (!isClass(destType) || !isClass(srcType)) { + return false; + } + + if (isTupleClass(destType) && isTupleClass(srcType)) { + const destTupleTypeArgs = destType.priv.tupleTypeArgs; + const srcTupleTypeArgs = srcType.priv.tupleTypeArgs; + if (!destTupleTypeArgs || !srcTupleTypeArgs) { + return undefined; + } + + if (destTupleTypeArgs.length === 1 && destTupleTypeArgs[0].isUnbounded) { + return combineMaterializationCoverage( + srcTupleTypeArgs.map((srcTypeArg) => + areAllMaterializationsAssignable(destTupleTypeArgs[0].type, srcTypeArg.type, recursionCount) + ) + ); + } + + if ( + destTupleTypeArgs.length !== srcTupleTypeArgs.length || + destTupleTypeArgs.some( + (destTypeArg, index) => destTypeArg.isUnbounded !== srcTupleTypeArgs[index].isUnbounded + ) + ) { + return false; + } + + return combineMaterializationCoverage( + srcTupleTypeArgs.map((srcTypeArg, index) => + areAllMaterializationsAssignable(destTupleTypeArgs[index].type, srcTypeArg.type, recursionCount) + ) + ); + } + + let specializedSrcType: ClassType | undefined; + if (ClassType.isSameGenericClass(destType, srcType)) { + specializedSrcType = srcType; + } else { + const instantiableDestType = isClassInstance(destType) ? ClassType.cloneAsInstantiable(destType) : destType; + const baseClass = srcType.shared.mro.find( + (mroClass) => isClass(mroClass) && ClassType.isSameGenericClass(instantiableDestType, mroClass) + ); + if (baseClass && isClass(baseClass)) { + specializedSrcType = specializeForBaseClass(srcType, baseClass); + } + } + + if (!specializedSrcType) { + return ClassType.isBuiltIn(destType, 'object') ? true : undefined; + } + + const typeParams = ClassType.getTypeParams(destType); + if (typeParams.length === 0) { + return true; + } + + const destTypeArgs = destType.priv.typeArgs; + const srcTypeArgs = specializedSrcType.priv.typeArgs; + if (!destTypeArgs) { + return true; + } + if (!srcTypeArgs) { + return false; + } + + inferVarianceForClass(destType); + return combineMaterializationCoverage( + srcTypeArgs.map((srcTypeArg, index) => { + const destTypeArg = index < destTypeArgs.length ? destTypeArgs[index] : UnknownType.create(); + const typeParam = index < typeParams.length ? typeParams[index] : undefined; + const variance = typeParam ? TypeVarType.getVariance(typeParam) : Variance.Invariant; + + if (variance === Variance.Covariant) { + return areAllMaterializationsAssignable(destTypeArg, srcTypeArg, recursionCount); + } + + if (variance === Variance.Invariant) { + return areAllMaterializationsEquivalent(destTypeArg, srcTypeArg, recursionCount); + } + + return undefined; + }) + ); + } + // Determines whether multiple incompatible overloads match // due to an Any or Unknown argument type. function filterOverloadMatchesForAnyArgs(matches: MatchedOverloadInfo[]): MatchedOverloadInfo[] { @@ -9750,31 +10117,90 @@ export function createTypeEvaluator( return matches; } - // If all of the return types match, select the first one. + let firstArgParamPairs = getOverloadArgParamPairs(matches[0]); + const hasInvariantAnyOrUnknownArg = firstArgParamPairs.some((pair) => + getAnyOrUnknownInInvariantPosition(pair.argType) + ); + + // If all of the effective return types match, select the first one. if ( areTypesSame( - matches.map((match) => match.returnType), + matches.map((match) => + hasInvariantAnyOrUnknownArg ? getEffectiveOverloadReturnType(match) : match.returnType + ), { treatAnySameAsUnknown: true } ) ) { return [matches[0]]; } - const firstArgResults = matches[0].argResults; - if (!firstArgResults) { - return matches; + // Apply overload step 5 to arguments that contain a gradual type in an + // invariant position. An overload that covers all materializations + // eliminates only the overloads that follow it. + if (hasInvariantAnyOrUnknownArg) { + let materializationCheckSupported = true; + for (let matchIndex = 0; matchIndex < matches.length; matchIndex++) { + const argParamPairs = getOverloadArgParamPairs(matches[matchIndex]); + const coverage = + argParamPairs.length === firstArgParamPairs.length + ? combineMaterializationCoverage( + argParamPairs.map((pair, index) => { + const argType = firstArgParamPairs[index].argType; + return areAllMaterializationsAssignable(pair.paramType, argType); + }) + ) + : false; + + if (coverage === undefined) { + materializationCheckSupported = false; + break; + } + + if (coverage) { + matches = matches.slice(0, matchIndex + 1); + break; + } + } + + if (materializationCheckSupported) { + if (matches.length < 2) { + return matches; + } + + if ( + areTypesSame( + matches.map((match) => getEffectiveOverloadReturnType(match)), + { treatAnySameAsUnknown: true } + ) + ) { + return [matches[0]]; + } + + firstArgParamPairs = getOverloadArgParamPairs(matches[0]); + for (let i = 0; i < firstArgParamPairs.length; i++) { + if (getAnyOrUnknownInInvariantPosition(firstArgParamPairs[i].argType)) { + const paramTypes = matches.map((match) => { + const argParamPairs = getOverloadArgParamPairs(match); + return i < argParamPairs.length ? argParamPairs[i].paramType : UnknownType.create(); + }); + + if (!areTypesSame(paramTypes, { treatAnySameAsUnknown: true })) { + return matches; + } + } + } + } } let foundAmbiguousAnyArg = false; - for (let i = 0; i < firstArgResults.length; i++) { + for (let i = 0; i < firstArgParamPairs.length; i++) { // If the arg is Any or Unknown, see if the corresponding // parameter types differ in any way. - if (isAnyOrUnknown(firstArgResults[i].argType)) { - const paramTypes = matches.map((match) => - i < match.matchResults.argParams.length - ? match.matchResults.argParams[i].paramType - : UnknownType.create() - ); + if (isAnyOrUnknown(firstArgParamPairs[i].argType)) { + const paramTypes = matches.map((match) => { + const argParamPairs = getOverloadArgParamPairs(match); + return i < argParamPairs.length ? argParamPairs[i].paramType : UnknownType.create(); + }); if (!areTypesSame(paramTypes, { treatAnySameAsUnknown: true })) { foundAmbiguousAnyArg = true; } @@ -9786,7 +10212,10 @@ export function createTypeEvaluator( // that one of the arguments is an unpacked iterator, and it maps to // an indeterminate number of parameters, which means that the overload // selection is ambiguous. - if (foundAmbiguousAnyArg || matches.some((match) => match.argResults.length !== firstArgResults.length)) { + if ( + foundAmbiguousAnyArg || + matches.some((match) => getOverloadArgParamPairs(match).length !== firstArgParamPairs.length) + ) { return matches; } @@ -12292,7 +12721,9 @@ export function createTypeEvaluator( let argumentErrors = false; let argumentMatchScore = 0; let specializedInitSelfType: Type | undefined; - let anyOrUnknownArg: UnknownType | AnyType | undefined; + let anyOrUnknownArg = type.priv.boundToType + ? getAnyOrUnknownInInvariantPosition(type.priv.boundToType) + : undefined; const speculativeNode = getSpeculativeNodeForCall(errorNode); const typeCondition = getTypeCondition(type); const paramSpec = FunctionType.getParamSpecFromArgsKwargs(type); @@ -12426,10 +12857,11 @@ export function createTypeEvaluator( condition = TypeCondition.combine(condition, argResult.condition) ?? []; } - if (isAnyOrUnknown(argResult.argType)) { - anyOrUnknownArg = anyOrUnknownArg - ? preserveUnknown(argResult.argType, anyOrUnknownArg) - : argResult.argType; + const argAnyOrUnknown = isAnyOrUnknown(argResult.argType) + ? argResult.argType + : getAnyOrUnknownInInvariantPosition(argResult.argType); + if (argAnyOrUnknown && !argParam.isDefaultArg) { + anyOrUnknownArg = anyOrUnknownArg ? preserveUnknown(argAnyOrUnknown, anyOrUnknownArg) : argAnyOrUnknown; } if (paramSpec) { diff --git a/packages/pyright-internal/src/tests/samples/overloadCall11.py b/packages/pyright-internal/src/tests/samples/overloadCall11.py new file mode 100644 index 000000000000..bc739fb19baf --- /dev/null +++ b/packages/pyright-internal/src/tests/samples/overloadCall11.py @@ -0,0 +1,22 @@ +# This sample tests overload matching when an invariant container is +# specialized with Any. + +from typing import Any, overload + + +@overload +def overloaded(value: list[int]) -> list[int]: + ... + + +@overload +def overloaded(value: list[str]) -> list[str]: + ... + + +def overloaded(value: Any) -> list[Any]: + return [] + + +def check(value: list[Any]) -> None: + reveal_type(overloaded(value), expected_text="Any") diff --git a/packages/pyright-internal/src/tests/samples/overloadCall6.py b/packages/pyright-internal/src/tests/samples/overloadCall6.py index f40c9c34dd5f..12dc85357ce8 100644 --- a/packages/pyright-internal/src/tests/samples/overloadCall6.py +++ b/packages/pyright-internal/src/tests/samples/overloadCall6.py @@ -3,8 +3,8 @@ # pyright: reportMissingModuleSource=false -from typing import Any, Generic, Literal, TypeVar, overload -from typing_extensions import LiteralString, TypeIs +from typing import Any, Generic, Literal, Sequence, TypeVar, overload +from typing_extensions import LiteralString, TypeIs, deprecated _T = TypeVar("_T") @@ -124,7 +124,212 @@ def overload5(x: list[str] | list[int]) -> list[str] | list[int]: def func6(y: list[Any]): - reveal_type(overload5(y), expected_text="list[int]") + reveal_type(overload5(y), expected_text="Any") + + +def func6_unknown(y: list): + reveal_type(overload5(y), expected_text="Unknown") + + +@overload +def overload5_same_return(x: list[int]) -> int: ... + + +@overload +def overload5_same_return(x: list[str]) -> int: ... + + +def overload5_same_return(x: list[Any]) -> int: + return 0 + + +def func6_same_return(y: list[Any]): + reveal_type(overload5_same_return(y), expected_text="int") + + +@overload +def overload5_covariant(x: Sequence[object]) -> int: ... + + +@overload +def overload5_covariant(x: list[str], y: int = 0) -> str: ... + + +def overload5_covariant(x: Sequence[object], y: int = 0) -> int | str: + return 0 + + +def func6_covariant(y: list[Any]): + reveal_type(overload5_covariant(y), expected_text="int") + + +@overload +def overload5_covariant_base(x: Sequence[int]) -> int: ... + + +@overload +def overload5_covariant_base(x: Sequence[object]) -> object: ... + + +def overload5_covariant_base(x: Sequence[object]) -> object: + return x + + +def func6_covariant_base(y: list[Any]): + reveal_type(overload5_covariant_base(y), expected_text="Any") + + +@overload +def overload5_unsupported_union(x: list[int | str]) -> int: ... + + +@overload +def overload5_unsupported_union(x: list[bytes | float]) -> str: ... + + +def overload5_unsupported_union(x: list[Any]) -> int | str: + return 1 + + +def func6_unsupported_union(y: list[Any]): + reveal_type(overload5_unsupported_union(y), expected_text="int") + + +@overload +def overload5_mixed_any(x: int, y: Sequence[object]) -> int: ... + + +@overload +def overload5_mixed_any(x: str, y: Sequence[object]) -> str: ... + + +def overload5_mixed_any(x: int | str, y: Sequence[object]) -> int | str: + return x + + +def func6_mixed_any(x: Any, y: list[Any]): + reveal_type(overload5_mixed_any(x, y), expected_text="Unknown") + + +_default_list: list[Any] = [] + + +@overload +def overload5_default(tag: Literal[1], value: list[int] = _default_list) -> Literal[1]: ... + + +@overload +def overload5_default(tag: int) -> int: ... + + +def overload5_default(tag: int, value: Any = _default_list) -> int: + return tag + + +reveal_type(overload5_default(1), expected_text="Literal[1]") + + +@overload +def overload5_unknown(x: list[int]) -> Literal[1]: ... + + +@overload +def overload5_unknown(x: list[str]) -> int: ... + + +def overload5_unknown(x: list[Any]) -> int: + return 1 + + +def func6_nested_unknown(x: list): + reveal_type(overload5_unknown(x), expected_text="Unknown") + + +@overload +def overload5_deprecated(x: list[int]) -> int: ... + + +@overload +def overload5_deprecated(x: list[Any]) -> int: ... + + +@overload +@deprecated("fallback is deprecated") +def overload5_deprecated(x: Any) -> int: ... + + +def overload5_deprecated(x: Any) -> int: + return 1 + + +def func6_deprecated(x: list[Any]): + overload5_deprecated(x) + + +@overload +@deprecated("int overload is deprecated") +def overload5_deprecated_union(x: int) -> int: ... + + +@overload +def overload5_deprecated_union(x: list[int]) -> int: ... + + +@overload +def overload5_deprecated_union(x: list[Any]) -> int: ... + + +def overload5_deprecated_union(x: Any) -> int: + return 1 + + +def func6_deprecated_union(x: int | list[Any]): + overload5_deprecated_union(x) + + +class ClassWithOverloadedInit(Generic[_T]): + @overload + def __init__(self: "ClassWithOverloadedInit[int]", value: list[int]) -> None: ... + + @overload + def __init__(self: "ClassWithOverloadedInit[str]", value: list[str]) -> None: ... + + def __init__(self, value: list[Any]) -> None: + pass + + +def func6_overloaded_init(x: list[Any]): + reveal_type(ClassWithOverloadedInit(x), expected_text="Any") + + +class ExplicitClassWithOverloadedInit(Generic[_T]): + @overload + def __init__(self: "ExplicitClassWithOverloadedInit[int]", value: list[int]) -> None: ... + + @overload + def __init__(self, value: list[str]) -> None: ... + + def __init__(self, value: list[Any]) -> None: + pass + + +def func6_explicit_overloaded_init(x: list[Any]): + reveal_type(ExplicitClassWithOverloadedInit[int](x), expected_text="ExplicitClassWithOverloadedInit[int]") + + +@overload +def overload5_contextual(x: list[Any], flag: Literal[True]) -> str: ... + + +@overload +def overload5_contextual(x: list[int], flag: bool) -> object: ... + + +def overload5_contextual(x: list[Any], flag: bool) -> object: + return x + + +reveal_type(overload5_contextual([], True), expected_text="str") class ClassA(Generic[_T]): @@ -139,7 +344,7 @@ def m1(self) -> "ClassA[Any]": def func7(a: ClassA[Any]): - reveal_type(a.m1(), expected_text="ClassA[int]") + reveal_type(a.m1(), expected_text="Any") class ClassB(Generic[_T]): @@ -154,7 +359,7 @@ def m1(self, obj: Any) -> "ClassB[Any]": def func8(b: ClassB[Any]): - reveal_type(b.m1(b), expected_text="ClassB[int]") + reveal_type(b.m1(b), expected_text="Any") _T1 = TypeVar("_T1") @@ -273,7 +478,7 @@ def overload10(x) -> Any: def func18(a: Any, b: list[Any], c: list[str], d: list[int]): reveal_type(overload10(a), expected_text="list[int]") - reveal_type(overload10(b), expected_text="list[int]") + reveal_type(overload10(b), expected_text="Any") reveal_type(overload10(c), expected_text="list[Any]") reveal_type(overload10(d), expected_text="list[int]") diff --git a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts index eb1d6a09ab96..c0d4ad64ff70 100644 --- a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts +++ b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts @@ -67,7 +67,7 @@ test('OverloadCall5', () => { test('OverloadCall6', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadCall6.py']); - TestUtils.validateResults(analysisResults, 2); + TestUtils.validateResults(analysisResults, 2, 0, undefined, undefined, undefined, 1); }); test('OverloadCall7', () => { @@ -90,6 +90,11 @@ test('OverloadCall10', () => { TestUtils.validateResults(analysisResults, 2); }); +test('OverloadCall11', () => { + const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadCall11.py']); + TestUtils.validateResults(analysisResults, 0); +}); + test('OverloadOverride1', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadOverride1.py']); TestUtils.validateResults(analysisResults, 1); From 0b239013f0001261ac3feacdd1f37cdd631cc9ae Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 09:31:27 -0700 Subject: [PATCH 2/7] Expand overload materialization coverage Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/tests/samples/overloadCall12.py | 469 ++++++++++++++++++ .../src/tests/samples/overloadCall6.py | 4 +- .../src/tests/typeEvaluator6.test.ts | 5 + 3 files changed, 476 insertions(+), 2 deletions(-) create mode 100644 packages/pyright-internal/src/tests/samples/overloadCall12.py diff --git a/packages/pyright-internal/src/tests/samples/overloadCall12.py b/packages/pyright-internal/src/tests/samples/overloadCall12.py new file mode 100644 index 000000000000..ae3cb352206c --- /dev/null +++ b/packages/pyright-internal/src/tests/samples/overloadCall12.py @@ -0,0 +1,469 @@ +# This sample tests overload materialization using patterns found in +# real-world libraries and applications. + +import re +from collections.abc import Callable, Sequence +from typing import Any, Generic, Literal, Never, ParamSpec, Protocol, TypeVar, overload +from typing_extensions import deprecated + +_T = TypeVar("_T") +_P = ParamSpec("_P") +_R = TypeVar("_R") + + +class Series(Generic[_T]): + def item(self) -> _T: + raise NotImplementedError + + @overload + def __add__(self: "Series[int]", other: "int | Series[int]") -> "Series[int]": ... + + @overload + def __add__(self: "Series[str]", other: "int | Series[str]") -> "Series[str]": ... + + def __add__(self, other: Any) -> "Series[Any]": + return Series[Any]() + + +class Index(Generic[_T]): + @overload + def __mul__(self: "Index[int]", other: int) -> "Index[int]": ... + + @overload + def __mul__(self: "Index[str]", other: int) -> "Index[str]": ... + + def __mul__(self, other: Any) -> "Index[Any]": + return Index[Any]() + + +def check_pandas_operators( + series_any: Series[Any], + series_unknown: Series, + series_int: Series[int], + index_any: Index[Any], + index_unknown: Index, + index_str: Index[str], +) -> None: + reveal_type(series_any + 1, expected_text="Any") + reveal_type(series_unknown + 1, expected_text="Unknown") + reveal_type(index_any * 2, expected_text="Any") + reveal_type(index_unknown * 2, expected_text="Unknown") + + concrete_series = series_int + 1 + reveal_type(concrete_series, expected_text="Series[int]") + reveal_type(concrete_series.item(), expected_text="int") + reveal_type(index_str * 2, expected_text="Index[str]") + + # This should generate an error. + _ = series_int + "bad" + + +class Flow(Generic[_P, _R]): + @overload + def __call__(self: "Flow[_P, Never]", *args: _P.args, **kwargs: _P.kwargs) -> None: ... + + @overload + def __call__(self: "Flow[_P, _R]", *args: _P.args, **kwargs: _P.kwargs) -> _R: ... + + def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> Any: + return None + + +def check_flow(flow_any: Flow[[], Any], flow_unknown: Flow, flow_int: Flow[[], int]) -> None: + reveal_type(flow_any(), expected_text="Any") + reveal_type(flow_unknown(), expected_text="Unknown") + reveal_type(flow_int(), expected_text="int") + reveal_type(flow_int() + 1, expected_text="int") + + # This should generate an error. + flow_int(1) + + +class EnumMapper(Generic[_T, _R]): + @overload + def from_wire(self, value: _T) -> _R: ... + + @overload + def from_wire(self, value: _T | None) -> _R | None: ... + + def from_wire(self, value: _T | None) -> _R | None: + return None + + +def check_optional_mapper( + mapper_any: EnumMapper[Any, str], + mapper_unknown: EnumMapper, + mapper_int: EnumMapper[int, str], + value: Any, +) -> None: + reveal_type(mapper_any.from_wire(value), expected_text="str") + reveal_type(mapper_unknown.from_wire(value), expected_text="Unknown") + reveal_type(mapper_int.from_wire(1), expected_text="str") + reveal_type(mapper_int.from_wire(1).upper(), expected_text="str") + + +_Shape = TypeVar("_Shape") + + +class Rotation(Generic[_Shape]): + @overload + @classmethod + def concatenate( + cls, values: list["Rotation[tuple[()]]"] + ) -> "Rotation[tuple[int]]": ... + + @overload + @classmethod + def concatenate( + cls, values: list["Rotation[tuple[int]]"] + ) -> "Rotation[tuple[int, int]]": ... + + @classmethod + def concatenate(cls, values: list["Rotation[Any]"]) -> "Rotation[Any]": + return Rotation[Any]() + + +def check_shape_overloads( + rotations_any: list[Rotation[tuple[Any, ...]]], + rotations_unknown: list[Rotation], + rotations_scalar: list[Rotation[tuple[()]]], +) -> None: + reveal_type(Rotation.concatenate(rotations_any), expected_text="Any") + reveal_type(Rotation.concatenate(rotations_unknown), expected_text="Unknown") + reveal_type(Rotation.concatenate(rotations_scalar), expected_text="Rotation[tuple[int]]") + + +def check_pattern( + pattern: re.Pattern, + pattern_any: re.Pattern[Any], + pattern_str: re.Pattern[str], + text: str, +) -> None: + reveal_type(pattern.match(text), expected_text="Unknown") + reveal_type(pattern.sub("", text), expected_text="Unknown") + reveal_type(pattern_any.match(text), expected_text="Any") + reveal_type(pattern_any.sub("", text), expected_text="Any") + reveal_type(pattern_str.match(text), expected_text="Match[str] | None") + reveal_type(pattern_str.sub("", text), expected_text="str") + + +class Table(Generic[_T]): + @overload + def __init__(self: "Table[int]", values: list[int]) -> None: ... + + @overload + def __init__(self: "Table[str]", values: list[str]) -> None: ... + + def __init__(self, values: list[Any]) -> None: + pass + + +def check_constructors(values_any: list[Any], values_unknown: list, values_int: list[int]) -> None: + reveal_type(Table(values_any), expected_text="Any") + reveal_type(Table(values_unknown), expected_text="Unknown") + reveal_type(Table(values_int), expected_text="Table[int]") + reveal_type(Table[int](values_any), expected_text="Table[int]") + + # This should generate an error. + Table[int](["bad"]) + + +@overload +def covariant_case(values: Sequence[int]) -> int: ... + + +@overload +def covariant_case(values: Sequence[object]) -> object: ... + + +def covariant_case(values: Sequence[object]) -> object: + return 0 + + +def check_covariant(values: Sequence[Any], string_values: Sequence[str]) -> None: + reveal_type(covariant_case(values), expected_text="int") + reveal_type(covariant_case(values) + 1, expected_text="int") + reveal_type(covariant_case(string_values), expected_text="object") + + +@overload +def top_level_case(value: int) -> int: ... + + +@overload +def top_level_case(value: str) -> str: ... + + +def top_level_case(value: Any) -> int | str: + return value + + +def check_top_level(value_any: Any, value_unknown) -> None: + reveal_type(top_level_case(value_any), expected_text="Unknown") + reveal_type(top_level_case(value_unknown), expected_text="Unknown") + + +@overload +def equal_return_case(value: list[int]) -> int: ... + + +@overload +def equal_return_case(value: list[str]) -> int: ... + + +def equal_return_case(value: list[Any]) -> int: + return 0 + + +def check_equal_return(values: list[Any]) -> None: + reveal_type(equal_return_case(values), expected_text="int") + reveal_type(equal_return_case(values).bit_length(), expected_text="int") + + +@overload +def literal_case(value: list[int], kind: Literal["int"]) -> int: ... + + +@overload +def literal_case(value: list[str], kind: Literal["str"]) -> str: ... + + +def literal_case(value: list[Any], kind: str) -> int | str: + return 0 + + +def check_literal(values: list[Any]) -> None: + reveal_type(literal_case(values, "int"), expected_text="int") + reveal_type(literal_case(values, "str"), expected_text="str") + + # This should generate an error. + literal_case(values, "bad") + + +_default_values: list[Any] = [] + + +@overload +def default_case(tag: Literal[1], values: list[int] = _default_values) -> Literal[1]: ... + + +@overload +def default_case(tag: int) -> int: ... + + +def default_case(tag: int, values: Any = _default_values) -> int: + return tag + + +@overload +def contextual_case(value: list[Any], flag: Literal[True]) -> str: ... + + +@overload +def contextual_case(value: list[int], flag: bool) -> object: ... + + +def contextual_case(value: list[Any], flag: bool) -> object: + return value + + +def check_defaults_and_context() -> None: + reveal_type(default_case(1), expected_text="Literal[1]") + reveal_type(contextual_case([], True), expected_text="str") + + +_TBound = TypeVar("_TBound", bound=int) +_TConstrained = TypeVar("_TConstrained", int, str) + + +@overload +def generic_second(value: list[int]) -> int: ... + + +@overload +def generic_second(value: list[_T]) -> _T: ... + + +def generic_second(value: list[Any]) -> Any: + return value[0] + + +@overload +def bounded_first(value: list[_TBound]) -> _TBound: ... + + +@overload +def bounded_first(value: list[str]) -> str: ... + + +def bounded_first(value: list[Any]) -> Any: + return value[0] + + +@overload +def constrained_first(value: list[_TConstrained]) -> _TConstrained: ... + + +@overload +def constrained_first(value: list[bytes]) -> bytes: ... + + +def constrained_first(value: list[Any]) -> Any: + return value[0] + + +def check_typevars(values_any: list[Any], values_unknown: list) -> None: + reveal_type(generic_second(values_any), expected_text="int") + reveal_type(generic_second(values_unknown), expected_text="int") + reveal_type(bounded_first(values_any), expected_text="Any") + reveal_type(bounded_first(values_unknown), expected_text="Unknown") + reveal_type(constrained_first(values_any), expected_text="Any") + reveal_type(constrained_first(values_unknown), expected_text="Unknown") + + +@overload +def multi_argument_case(value: list[int], fallback: int) -> int: ... + + +@overload +def multi_argument_case(value: list[str], fallback: str) -> int: ... + + +@overload +def multi_argument_case(value: int, fallback: int) -> list[int]: ... + + +def multi_argument_case(value: list[int] | list[str] | int, fallback: int | str) -> int | list[int]: + return 0 + + +def check_multiple_arguments(values_any: list[Any], value_any: Any) -> None: + result = multi_argument_case(values_any, value_any) + reveal_type(result, expected_text="int") + reveal_type(result.bit_length(), expected_text="int") + reveal_type(multi_argument_case(value_any, 1), expected_text="Unknown") + + +class Reader(Protocol): + def read(self) -> str: ... + + +@overload +def protocol_case(value: list[Reader]) -> int: ... + + +@overload +def protocol_case(value: list[str]) -> str: ... + + +def protocol_case(value: list[Any]) -> int | str: + return 0 + + +@overload +def callable_case(value: list[Callable[[int], int]]) -> int: ... + + +@overload +def callable_case(value: list[str]) -> str: ... + + +def callable_case(value: list[Any]) -> int | str: + return 0 + + +@overload +def union_case(value: list[int | str]) -> int: ... + + +@overload +def union_case(value: list[bytes | float]) -> str: ... + + +def union_case(value: list[Any]) -> int | str: + return 0 + + +@overload +def tuple_case(value: list[tuple[int, int]]) -> int: ... + + +@overload +def tuple_case(value: list[tuple[str, str]]) -> str: ... + + +def tuple_case(value: list[tuple[Any, Any]]) -> int | str: + return 0 + + +@overload +def tuple_union_case(value: list[tuple[int | str]]) -> int: ... + + +@overload +def tuple_union_case(value: list[tuple[bytes | float]]) -> str: ... + + +def tuple_union_case(value: list[tuple[Any]]) -> int | str: + return 0 + + +def check_supported_and_unsupported_shapes( + values_any: list[Any], + values_unknown: list, + tuple_values: list[tuple[Any, Any]], + tuple_unknown_values: list[tuple], + tuple_union_values: list[tuple[Any]], +) -> None: + reveal_type(protocol_case(values_any), expected_text="int") + reveal_type(protocol_case(values_unknown), expected_text="int") + reveal_type(callable_case(values_any), expected_text="int") + reveal_type(callable_case(values_unknown), expected_text="int") + reveal_type(union_case(values_any), expected_text="int") + reveal_type(union_case(values_unknown), expected_text="int") + reveal_type(tuple_case(tuple_values), expected_text="Any") + reveal_type(tuple_case(tuple_unknown_values), expected_text="Unknown") + reveal_type(tuple_union_case(tuple_union_values), expected_text="int") + + +_TContra = TypeVar("_TContra", contravariant=True) + + +class Sink(Generic[_TContra]): + pass + + +@overload +def contravariant_case(value: Sink[int]) -> int: ... + + +@overload +def contravariant_case(value: Sink[str]) -> str: ... + + +def contravariant_case(value: Sink[Any]) -> int | str: + return 0 + + +def check_contravariant(value: Sink[Any], value_unknown: Sink) -> None: + reveal_type(contravariant_case(value), expected_text="int") + reveal_type(contravariant_case(value_unknown), expected_text="int") + + +@overload +@deprecated("integer values are deprecated") +def deprecated_case(value: list[int]) -> int: ... + + +@overload +def deprecated_case(value: list[str]) -> str: ... + + +def deprecated_case(value: list[Any]) -> int | str: + return 0 + + +def check_deprecated(values: list[Any], string_values: list[str]) -> None: + # This should generate a deprecation warning. + reveal_type(deprecated_case(values), expected_text="Any") + reveal_type(deprecated_case(string_values), expected_text="str") diff --git a/packages/pyright-internal/src/tests/samples/overloadCall6.py b/packages/pyright-internal/src/tests/samples/overloadCall6.py index 12dc85357ce8..47618756fe53 100644 --- a/packages/pyright-internal/src/tests/samples/overloadCall6.py +++ b/packages/pyright-internal/src/tests/samples/overloadCall6.py @@ -263,7 +263,7 @@ def overload5_deprecated(x: Any) -> int: def func6_deprecated(x: list[Any]): - overload5_deprecated(x) + reveal_type(overload5_deprecated(x), expected_text="int") @overload @@ -284,7 +284,7 @@ def overload5_deprecated_union(x: Any) -> int: def func6_deprecated_union(x: int | list[Any]): - overload5_deprecated_union(x) + reveal_type(overload5_deprecated_union(x), expected_text="int") class ClassWithOverloadedInit(Generic[_T]): diff --git a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts index c0d4ad64ff70..cd15fe889451 100644 --- a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts +++ b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts @@ -95,6 +95,11 @@ test('OverloadCall11', () => { TestUtils.validateResults(analysisResults, 0); }); +test('OverloadCall12', () => { + const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadCall12.py']); + TestUtils.validateResults(analysisResults, 5, 0, undefined, undefined, undefined, 1); +}); + test('OverloadOverride1', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadOverride1.py']); TestUtils.validateResults(analysisResults, 1); From 8ae5c2d76e3276f4affc3a11d13bfdc68e63db94 Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 09:45:49 -0700 Subject: [PATCH 3/7] Assert deprecated overload diagnostic range Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/pyright-internal/src/tests/typeEvaluator6.test.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts index cd15fe889451..f3d5f0161d3f 100644 --- a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts +++ b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts @@ -68,6 +68,10 @@ test('OverloadCall5', () => { test('OverloadCall6', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadCall6.py']); TestUtils.validateResults(analysisResults, 2, 0, undefined, undefined, undefined, 1); + assert.deepStrictEqual(analysisResults[0].deprecateds[0].range, { + start: { line: 286, character: 4 }, + end: { line: 286, character: 30 }, + }); }); test('OverloadCall7', () => { From 4eed2701c174c481818dca20d29455ee5f9eadaf Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 10:11:44 -0700 Subject: [PATCH 4/7] Correct deprecated diagnostic span Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/pyright-internal/src/tests/typeEvaluator6.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts index f3d5f0161d3f..207777a3fb4c 100644 --- a/packages/pyright-internal/src/tests/typeEvaluator6.test.ts +++ b/packages/pyright-internal/src/tests/typeEvaluator6.test.ts @@ -69,8 +69,8 @@ test('OverloadCall6', () => { const analysisResults = TestUtils.typeAnalyzeSampleFiles(['overloadCall6.py']); TestUtils.validateResults(analysisResults, 2, 0, undefined, undefined, undefined, 1); assert.deepStrictEqual(analysisResults[0].deprecateds[0].range, { - start: { line: 286, character: 4 }, - end: { line: 286, character: 30 }, + start: { line: 286, character: 16 }, + end: { line: 286, character: 42 }, }); }); From dffa274cbfc7edb2ab2217e5af92cbdce0419ca0 Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 12:52:24 -0700 Subject: [PATCH 5/7] ci: suppress missing typing extensions source Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/pyright-internal/src/tests/samples/overloadCall12.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/pyright-internal/src/tests/samples/overloadCall12.py b/packages/pyright-internal/src/tests/samples/overloadCall12.py index ae3cb352206c..06e845cc33ad 100644 --- a/packages/pyright-internal/src/tests/samples/overloadCall12.py +++ b/packages/pyright-internal/src/tests/samples/overloadCall12.py @@ -4,7 +4,7 @@ import re from collections.abc import Callable, Sequence from typing import Any, Generic, Literal, Never, ParamSpec, Protocol, TypeVar, overload -from typing_extensions import deprecated +from typing_extensions import deprecated # pyright: ignore[reportMissingModuleSource] _T = TypeVar("_T") _P = ParamSpec("_P") From 651054b7406194c1138cfadaad35304ed4c6e721 Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 13:18:15 -0700 Subject: [PATCH 6/7] Address overload materialization review feedback Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/analyzer/typeEvaluator.ts | 18 +++++++++++++++--- .../src/tests/samples/overloadCall12.py | 18 ++++++++++++++++++ 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/packages/pyright-internal/src/analyzer/typeEvaluator.ts b/packages/pyright-internal/src/analyzer/typeEvaluator.ts index f5717eee976f..7dd0bd05b760 100644 --- a/packages/pyright-internal/src/analyzer/typeEvaluator.ts +++ b/packages/pyright-internal/src/analyzer/typeEvaluator.ts @@ -9630,6 +9630,10 @@ export function createTypeEvaluator( if (!isDefinitiveMatchFound && possibleMatchResults.length > 0) { possibleMatchResults = filterOverloadMatchesForUnpackedArgs(possibleMatchResults); possibleMatchResults = filterOverloadMatchesForAnyArgs(possibleMatchResults); + + // Keep diagnostic bookkeeping aligned with the candidates that remain possible. + // This applies to both top-level gradual arguments and nested materialization, + // so deprecation diagnostics are reported only for retained overloads. overloadsUsedForCall.splice( overloadsUsedStartIndex, overloadsUsedForCall.length - overloadsUsedStartIndex, @@ -9802,6 +9806,8 @@ export function createTypeEvaluator( return unpackedArgsOverloads; } + // assignType cannot be used for this detection because it accepts Any and Unknown + // without exposing whether acceptance depends on a gradual invariant type argument. function getAnyOrUnknownInInvariantPosition(type: Type, recursionCount = 0): AnyType | UnknownType | undefined { if (recursionCount > maxTypeRecursionCount) { return undefined; @@ -9861,6 +9867,10 @@ export function createTypeEvaluator( function getOverloadArgParamPairs(match: MatchedOverloadInfo): { argType: Type; paramType: Type }[] { const pairs: { argType: Type; paramType: Type }[] = []; + + // argResults and argParams share validation order: supplied arguments in caller + // order, followed by synthesized defaults. Preserve that order so the same index + // across overloads represents the same supplied argument, even for keyword calls. match.argResults.forEach((argResult, index) => { const argParam = index < match.matchResults.argParams.length ? match.matchResults.argParams[index] : undefined; @@ -9882,6 +9892,11 @@ export function createTypeEvaluator( return pairs; } + // assignType tests one gradual source type, whereas overload step 5 asks whether + // every materialization of that source is covered. These helpers therefore use a + // conservative tri-state proof over supported nominal and tuple relationships: + // true means all materializations are covered, false identifies a counterexample, + // and undefined means coverage is unproven. New cases must preserve this invariant. type MaterializationCoverage = boolean | undefined; function combineMaterializationCoverage(results: MaterializationCoverage[]): MaterializationCoverage { @@ -10007,9 +10022,6 @@ export function createTypeEvaluator( } if (isAnyOrUnknown(srcType)) { - if (isTypeVar(destType)) { - return false; - } return assignType(destType, getObjectType()); } diff --git a/packages/pyright-internal/src/tests/samples/overloadCall12.py b/packages/pyright-internal/src/tests/samples/overloadCall12.py index 06e845cc33ad..9370f44a2d24 100644 --- a/packages/pyright-internal/src/tests/samples/overloadCall12.py +++ b/packages/pyright-internal/src/tests/samples/overloadCall12.py @@ -272,6 +272,24 @@ def check_defaults_and_context() -> None: reveal_type(contextual_case([], True), expected_text="str") +@overload +def keyword_default_case(value: list[int], *, scale: int = 0, name: str) -> int: ... + + +@overload +def keyword_default_case(value: list[str], *, name: str, scale: int = 0) -> str: ... + + +def keyword_default_case(value: list[Any], *, name: str, scale: int = 0) -> int | str: + return scale + + +def check_keyword_default(values_any: list[Any], values_unknown: list) -> None: + reveal_type(keyword_default_case(name="value", value=values_any), expected_text="Any") + reveal_type(keyword_default_case(name="value", value=values_unknown), expected_text="Unknown") + reveal_type(keyword_default_case(name="value", value=values_any, scale=1), expected_text="Any") + + _TBound = TypeVar("_TBound", bound=int) _TConstrained = TypeVar("_TConstrained", int, str) From 6906b0921c6fcda2888035ee1790282fdaf7410b Mon Sep 17 00:00:00 2001 From: Rich Chiodo Date: Mon, 10 Aug 2026 13:28:39 -0700 Subject: [PATCH 7/7] Document constructor overload result handoff Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- packages/pyright-internal/src/analyzer/constructors.ts | 4 ++++ .../pyright-internal/src/analyzer/typeEvaluator.ts | 5 +++++ .../src/tests/samples/overloadCall12.py | 10 +++++++++- 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/packages/pyright-internal/src/analyzer/constructors.ts b/packages/pyright-internal/src/analyzer/constructors.ts index 34a58fa83dac..20f5907add57 100644 --- a/packages/pyright-internal/src/analyzer/constructors.ts +++ b/packages/pyright-internal/src/analyzer/constructors.ts @@ -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) && diff --git a/packages/pyright-internal/src/analyzer/typeEvaluator.ts b/packages/pyright-internal/src/analyzer/typeEvaluator.ts index 7dd0bd05b760..f3f592bff1d5 100644 --- a/packages/pyright-internal/src/analyzer/typeEvaluator.ts +++ b/packages/pyright-internal/src/analyzer/typeEvaluator.ts @@ -9740,6 +9740,11 @@ export function createTypeEvaluator( } if (isInitSelfMaterializationAmbiguity) { + // Overloaded __init__ methods normally return None. Preserve that + // ordinary return as a placeholder while union-expanded calls are + // combined, and carry the effective constructed types separately. + // validateInitMethod consumes specializedInitSelfType to reconstruct + // the constructor result after call validation is complete. specializedInitSelfTypes.push(returnType); returnTypes.push(possibleMatchResults[0].returnType); } else { diff --git a/packages/pyright-internal/src/tests/samples/overloadCall12.py b/packages/pyright-internal/src/tests/samples/overloadCall12.py index 9370f44a2d24..3eee9b27fad6 100644 --- a/packages/pyright-internal/src/tests/samples/overloadCall12.py +++ b/packages/pyright-internal/src/tests/samples/overloadCall12.py @@ -154,7 +154,10 @@ def __init__(self: "Table[int]", values: list[int]) -> None: ... @overload def __init__(self: "Table[str]", values: list[str]) -> None: ... - def __init__(self, values: list[Any]) -> None: + @overload + def __init__(self: "Table[bytes]", values: bytes) -> None: ... + + def __init__(self, values: list[Any] | bytes) -> None: pass @@ -168,6 +171,11 @@ def check_constructors(values_any: list[Any], values_unknown: list, values_int: Table[int](["bad"]) +def check_constructor_union(values_any: list[Any] | bytes, values_unknown: list | bytes) -> None: + reveal_type(Table(values_any), expected_text="Any") + reveal_type(Table(values_unknown), expected_text="Unknown") + + @overload def covariant_case(values: Sequence[int]) -> int: ...