From 74cdebfda9c988147150e5901242617e1b765215 Mon Sep 17 00:00:00 2001 From: Vishal Raj <9031842908.vk@gmail.com> Date: Thu, 19 Nov 2026 20:34:14 +0530 Subject: [PATCH 1/3] Fix docstring fallback on hover for matched overload without docstring Signed-off-by: Vishal Raj <9031842908.vk@gmail.com> --- .../src/analyzer/typeDocStringUtils.ts | 13 +++++---- ....overloadedFunction.docstring.fourslash.ts | 29 +++++++++++++++++++ 2 files changed, 37 insertions(+), 5 deletions(-) create mode 100644 packages/pyright-internal/src/tests/fourslash/hover.overloadedFunction.docstring.fourslash.ts diff --git a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts index 1765508a6c26..b8f735134731 100644 --- a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts +++ b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts @@ -133,11 +133,14 @@ function _selectMemberDocInfo( } } - // Tier 3: the remaining overloads, in declaration order. - for (const overload of overloads) { - const info = _functionDocInfo(overload, sourceMapper); - if (info) { - return info; + // Tier 3: the remaining overloads, in declaration order. Only consider other + // overloads when no specific overload was matched (e.g. uncalled function hover). + if (!matchedOverloads || matchedOverloads.length === 0) { + for (const overload of overloads) { + const info = _functionDocInfo(overload, sourceMapper); + if (info) { + return info; + } } } diff --git a/packages/pyright-internal/src/tests/fourslash/hover.overloadedFunction.docstring.fourslash.ts b/packages/pyright-internal/src/tests/fourslash/hover.overloadedFunction.docstring.fourslash.ts new file mode 100644 index 000000000000..b6e4e48ebc96 --- /dev/null +++ b/packages/pyright-internal/src/tests/fourslash/hover.overloadedFunction.docstring.fourslash.ts @@ -0,0 +1,29 @@ +/// + +// @filename: test.py +//// from typing import overload +//// +//// @overload +//// def fun(a: int) -> int: +//// """int overload""" +//// @overload +//// def fun(a: str) -> str: +//// """str overload""" +//// @overload +//// def fun(a: bytes) -> bytes: +//// ... +//// def fun(a: int | bytes | str) -> int | bytes | str: +//// return a +//// +//// [|/*marker1*/fun|](1) +//// [|/*marker2*/fun|]("") +//// [|/*marker3*/fun|](b"") +//// [|/*marker4*/fun|] + +helper.verifyHover('markdown', { + marker1: '```python\n(function) def fun(a: int) -> int\n```\n---\nint overload', + marker2: '```python\n(function) def fun(a: str) -> str\n```\n---\nstr overload', + marker3: '```python\n(function) def fun(a: bytes) -> bytes\n```', + marker4: + '```python\n(function)\ndef fun(a: int) -> int: ...\ndef fun(a: str) -> str: ...\ndef fun(a: bytes) -> bytes: ...\n```\n---\nint overload', +}); From b12aabf031059452a5c66127fcb6199c7c43eaaa Mon Sep 17 00:00:00 2001 From: Vishal Raj <9031842908.vk@gmail.com> Date: Fri, 20 Nov 2026 13:17:47 +0530 Subject: [PATCH 2/3] Fix constructor signature help docstring and avoid borrowing inherited overload - Scope memberName check so hints from a different constructor member do not suppress fallback overloads - Forward matched overload hint in base class resolution to avoid borrowing unrelated inherited sibling overloads - Add focused FourSlash tests for constructor signature help and inherited method hover Signed-off-by: Vishal Raj <9031842908.vk@gmail.com> --- .../src/analyzer/typeDocStringUtils.ts | 17 ++++++-- ...r.inheritedOverload.docstring.fourslash.ts | 27 +++++++++++++ ...uctor.overloadedNew.docstring.fourslash.ts | 40 +++++++++++++++++++ 3 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 packages/pyright-internal/src/tests/fourslash/hover.inheritedOverload.docstring.fourslash.ts create mode 100644 packages/pyright-internal/src/tests/fourslash/signature.constructor.overloadedNew.docstring.fourslash.ts diff --git a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts index b8f735134731..e5ba3f341746 100644 --- a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts +++ b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts @@ -93,6 +93,7 @@ function _selectMemberDocInfo( const overloads = OverloadedType.getOverloads(memberType); const impl = OverloadedType.getImplementation(memberType); + const memberName = overloads.length > 0 ? overloads[0].shared.name : undefined; // Tier 1: the call-matched overload(s). First read the matched overload's OWN docstring // directly; this is robust to declaration-cleared specializations (e.g. a ParamSpec/Callable @@ -105,7 +106,6 @@ function _selectMemberDocInfo( // actually belongs to this member; otherwise another member's matched overload could // short-circuit Rule B here. Name is preserved across binding/specialization, so filtering // by name is a safe scope check. - const memberName = overloads.length > 0 ? overloads[0].shared.name : undefined; for (const matched of matchedOverloads) { if (memberName !== undefined && matched.shared.name !== memberName) { continue; @@ -134,8 +134,13 @@ function _selectMemberDocInfo( } // Tier 3: the remaining overloads, in declaration order. Only consider other - // overloads when no specific overload was matched (e.g. uncalled function hover). - if (!matchedOverloads || matchedOverloads.length === 0) { + // overloads when no specific overload was matched for this member (e.g. uncalled + // function hover, or hints forwarded from a different constructor member). + const hasMatchedOverloadForMember = + matchedOverloads && + matchedOverloads.some((matched) => memberName === undefined || matched.shared.name === memberName); + + if (!hasMatchedOverloadForMember) { for (const overload of overloads) { const info = _functionDocInfo(overload, sourceMapper); if (info) { @@ -255,7 +260,11 @@ export function resolveMethodDocInfo( continue; } - const info = _selectMemberDocInfo(evaluator.getEffectiveTypeOfSymbol(symbol), undefined, sourceMapper); + const info = _selectMemberDocInfo( + evaluator.getEffectiveTypeOfSymbol(symbol), + matchedOverloads, + sourceMapper + ); if (info?.docString) { return info; } diff --git a/packages/pyright-internal/src/tests/fourslash/hover.inheritedOverload.docstring.fourslash.ts b/packages/pyright-internal/src/tests/fourslash/hover.inheritedOverload.docstring.fourslash.ts new file mode 100644 index 000000000000..8ba48a327557 --- /dev/null +++ b/packages/pyright-internal/src/tests/fourslash/hover.inheritedOverload.docstring.fourslash.ts @@ -0,0 +1,27 @@ +/// + +// @filename: test.py +//// from typing import overload +//// +//// class Base: +//// @overload +//// def method(self, x: int) -> int: +//// """integer docs""" +//// @overload +//// def method(self, x: str) -> str: ... +//// def method(self, x: int | str) -> int | str: +//// return x +//// +//// class Derived(Base): +//// @overload +//// def method(self, x: int) -> int: ... +//// @overload +//// def method(self, x: str) -> str: ... +//// def method(self, x: int | str) -> int | str: +//// return x +//// +//// Derived().[|/*marker1*/method|]("") + +helper.verifyHover('markdown', { + marker1: '```python\n(method) def method(x: str) -> str\n```', +}); diff --git a/packages/pyright-internal/src/tests/fourslash/signature.constructor.overloadedNew.docstring.fourslash.ts b/packages/pyright-internal/src/tests/fourslash/signature.constructor.overloadedNew.docstring.fourslash.ts new file mode 100644 index 000000000000..6f58afd8a8ec --- /dev/null +++ b/packages/pyright-internal/src/tests/fourslash/signature.constructor.overloadedNew.docstring.fourslash.ts @@ -0,0 +1,40 @@ +/// + +// @filename: test.py +//// from typing import overload +//// +//// class NewDocs: +//// @overload +//// def __init__(self, x: int) -> None: ... +//// @overload +//// def __init__(self, x: str) -> None: ... +//// def __init__(self, x: int | str) -> None: pass +//// +//// @overload +//// def __new__(cls, x: int) -> "NewDocs": +//// """new integer docs""" +//// @overload +//// def __new__(cls, x: str) -> "NewDocs": +//// """new string docs""" +//// def __new__(cls, x: int | str) -> "NewDocs": +//// return super().__new__(cls) +//// +//// NewDocs([|/*marker1*/|]1) + +helper.verifySignature('markdown', { + marker1: { + signatures: [ + { + label: '(x: int) -> NewDocs', + parameters: ['x: int'], + documentation: 'new integer docs', + }, + { + label: '(x: str) -> NewDocs', + parameters: ['x: str'], + documentation: undefined, + }, + ], + activeParameters: [0, 0], + }, +}); From 1b917077ba9d467ed9cef01c83ab245058d67cad Mon Sep 17 00:00:00 2001 From: Vishal Raj <9031842908.vk@gmail.com> Date: Sat, 21 Nov 2026 09:55:25 +0530 Subject: [PATCH 3/3] Support cross-member and inherited overload signature matching - Correlate corresponding overload signatures across inheritance and between constructor members (__init__ and __new__) using callable parameter matching - Only suppress Tier 3 fallback when matchedOverloads is a narrowed subset and matches a member overload, preserving docstring inheritance on uncalled hover and completion Signed-off-by: Vishal Raj <9031842908.vk@gmail.com> --- .../src/analyzer/typeDocStringUtils.ts | 67 +++++++++++++++++-- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts index e5ba3f341746..5089b9c12e03 100644 --- a/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts +++ b/packages/pyright-internal/src/analyzer/typeDocStringUtils.ts @@ -24,10 +24,12 @@ import * as ParseTreeUtils from '../analyzer/parseTreeUtils'; import { isStubFile, SourceMapper } from '../analyzer/sourceMapper'; import { ClassType, + FunctionParam, FunctionType, isFunction, isInstantiableClass, isOverloaded, + isTypeSame, ModuleType, OverloadedType, Type, @@ -35,7 +37,7 @@ import { } from '../analyzer/types'; import { addIfNotNull, appendArray } from '../common/collectionUtils'; import { Uri } from '../common/uri/uri'; -import { ModuleNode, ParseNodeType } from '../parser/parseNodes'; +import { ModuleNode, ParamCategory, ParseNodeType } from '../parser/parseNodes'; import { TypeEvaluator } from './typeEvaluatorTypes'; import { ClassIteratorFlags, getClassIterator, isMaybeDescriptorInstance, MemberAccessFlags } from './typeUtils'; @@ -138,7 +140,12 @@ function _selectMemberDocInfo( // function hover, or hints forwarded from a different constructor member). const hasMatchedOverloadForMember = matchedOverloads && - matchedOverloads.some((matched) => memberName === undefined || matched.shared.name === memberName); + matchedOverloads.length < overloads.length && + matchedOverloads.some( + (matched) => + (memberName === undefined || matched.shared.name === memberName) && + overloads.some((overload) => _isMatchedOverload(overload, [matched])) + ); if (!hasMatchedOverloadForMember) { for (const overload of overloads) { @@ -152,13 +159,65 @@ function _selectMemberDocInfo( return undefined; } +function _getCallableParameters(type: FunctionType): { param: FunctionParam; type: Type }[] { + const isBound = !!type.priv.boundToType; + const isUnboundMethod = + !isBound && + type.shared.parameters.length > 0 && + type.shared.parameters[0].category === ParamCategory.Simple && + (type.shared.parameters[0].name === 'self' || + type.shared.parameters[0].name === 'cls' || + type.shared.name === '__init__' || + type.shared.name === '__new__' || + (!!type.shared.methodClass && !FunctionType.isStaticMethod(type))); + + const startIndex = isUnboundMethod ? 1 : 0; + const result: { param: FunctionParam; type: Type }[] = []; + for (let i = startIndex; i < type.shared.parameters.length; i++) { + result.push({ + param: type.shared.parameters[i], + type: FunctionType.getParamType(type, i), + }); + } + return result; +} + +function _isMatchingOverloadSignature(overload: FunctionType, candidate: FunctionType): boolean { + const params1 = _getCallableParameters(overload); + const params2 = _getCallableParameters(candidate); + + if (params1.length !== params2.length) { + return false; + } + + for (let i = 0; i < params1.length; i++) { + const p1 = params1[i]; + const p2 = params2[i]; + if (p1.param.category !== p2.param.category) { + return false; + } + if (p1.param.name && p2.param.name && p1.param.name !== p2.param.name) { + return false; + } + if (!isTypeSame(p1.type, p2.type)) { + return false; + } + } + + return true; +} + function _isMatchedOverload(overload: FunctionType, matchedOverloads: FunctionType[]): boolean { // Match by object identity first, then by shared declaration. The latter keeps the // matched-overload tier robust to binding/specialization (e.g. a generic `Box[int]()` // whose matched overload is a specialized clone); `shared.declaration` is preserved - // across those transforms. If it ever were not, this falls through to the impl/other tiers. + // across those transforms. Then fall back to signature matching across class inheritance + // or constructor members (__init__ vs __new__). return matchedOverloads.some( - (m) => m === overload || (!!m.shared.declaration && m.shared.declaration === overload.shared.declaration) + (m) => + m === overload || + (!!m.shared.declaration && m.shared.declaration === overload.shared.declaration) || + _isMatchingOverloadSignature(overload, m) ); }