Skip to content
Open
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
91 changes: 81 additions & 10 deletions packages/pyright-internal/src/analyzer/typeDocStringUtils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,20 @@ import * as ParseTreeUtils from '../analyzer/parseTreeUtils';
import { isStubFile, SourceMapper } from '../analyzer/sourceMapper';
import {
ClassType,
FunctionParam,
FunctionType,
isFunction,
isInstantiableClass,
isOverloaded,
isTypeSame,
ModuleType,
OverloadedType,
Type,
TypeCategory,
} 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';

Expand Down Expand Up @@ -93,6 +95,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
Expand All @@ -105,7 +108,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;
Expand Down Expand Up @@ -133,24 +135,89 @@ 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 for this member (e.g. uncalled
// function hover, or hints forwarded from a different constructor member).
const hasMatchedOverloadForMember =
matchedOverloads &&
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) {
const info = _functionDocInfo(overload, sourceMapper);
if (info) {
return info;
}
}
}

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)
);
}

Expand Down Expand Up @@ -252,7 +319,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;
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/// <reference path="typings/fourslash.d.ts" />

// @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```',
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
/// <reference path="typings/fourslash.d.ts" />

// @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',
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
/// <reference path="typings/fourslash.d.ts" />

// @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],
},
});