Skip to content

Fix override checks for overloads, annotated self and return TypeVars - #11839

Open
crypt0lith wants to merge 7 commits into
microsoft:mainfrom
crypt0lith:fix/overload-override-coverage
Open

crypt0lith wants to merge 7 commits into
microsoft:mainfrom
crypt0lith:fix/overload-override-coverage

Conversation

@crypt0lith

@crypt0lith crypt0lith commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #11836
Fixes #10216

Since #6396, an override of an overloaded method is checked only up to its first overload that matches no base overload. An overload added before or between the inherited ones is reported as not handling all base overloads, an order error after it goes unreported, and a base overload dropped before the last match is accepted.

Root cause

In validateOverrideMethod, the loop over the override's overloads breaks at the first one that matches no base overload, and the check after the loop covers only the base overloads after the last match. The break is what reports #6382.

validateOverrideMethodInternal compares the methods unbound, so TypeVars in an annotated self or cls parameter aren't solved against the class. It also leaves an override TypeVar that appears in a parameter only within a union unsolved in the return type, as in Mapping.get-style overrides.

Fix

Check the base overloads in order, matching each applicable one to the first compatible override overload at or after the previous match. Allow additional override overloads anywhere, but reject any override overload ahead of a match that overlaps that base overload and returns an incompatible type.
Before comparing a base method and its override, solve an annotated self or cls parameter against that method's own class, as #10209 already does for Self. When two base classes define the same method, also specialize Self this way and skip base overloads that don't apply to the class, as the check against a single base class already does. In the override's return type, handle unsolved TypeVars of the override in a union as in a call's return type.

Test

Cases added to methodOverride6.py
Case Expected Description
Child6_1 added overload before inherited ones, overlapping none
Child6_2 added overload between inherited ones, overlapping none
Child6_3 error inherited overloads reversed
Child6_4 error first base overload dropped
Child7_1 error middle base overload dropped
Child8_1 later overload repeats a base overload; base overloads still matched in order
Child8_2 error added overload ahead of inherited ones overlaps one with incompatible return
Child9_1 added overload ahead of inherited ones partially overlaps one, but with compatible return
Child9_2 error added overload ahead of inherited ones partially overlaps one with incompatible return
Child10_1 Mapping.get-style with default of any type; value-typed default still returns value type
Child10_2 error Mapping.get-style returning wrong value type
Child10_3 error Mapping.get-style without value type in return
Child11_1 added overload ahead of inherited ones overlaps one, but returns class's type arg like base (via annotated self)
Child11_2 error added overload ahead of inherited ones overlaps one, returning str instead of class's type arg (via annotated self)
Child12_1 error inherited overload widened to overlap a later base overload, with incompatible return
Child13_1 error added overload ahead of inherited ones overlaps one when argument with default is omitted, with incompatible return
Child14_1 error added overload ahead of inherited ones overlaps generic one, with return incompatible with its solved TypeVar
Cases added to methodOverride4.py
Case Expected Description
SubclassD error may return class's type arg (via annotated self), not only int like base
SubclassE returns int or class's type arg (via annotated self), both object like base
SubclassF1 returns int for int argument like base (unbounded TypeVar)
SubclassF2 returns int for int argument like base (TypeVar bound str)
SubclassF3 returns int for int argument like base (TypeVar constraints str, bytes)
SubclassF4 error takes only class's type arg (via annotated self), not every int like base
SubclassF5 error may return str for int argument (TypeVar default), not only int like base
SubclassF6 returns int for int argument like base (TypeVar default int)
SubclassG error classmethod takes only class's type arg (via annotated cls), not every int like base
SubclassH takes and returns int, matching base's type arg (via annotated self) of int
SubclassI error inherited methods disagree: str (via annotated self) vs int
SubclassJ1 error self-typed parameter narrowed via TypeVar bound: rejects base instances, as with Self
SubclassJ2 error self-typed parameter narrowed to child class: rejects base instances
SubclassK1 generic class; inherited methods agree: both take class's type arg, one via annotated self
SubclassK2 error generic class; inherited methods disagree: class's type arg (via annotated self) vs int
SubclassM1 generic class; takes base parameterized with class's type arg, matching base (via annotated self)
SubclassM2 generic class; takes base parameterized with class's type arg via own annotated self, matching base
SubclassM3 error inherited methods disagree: base parameterized with int vs with class's type arg
SubclassO1 inherited overloads agree once the one whose annotated self excludes the class is skipped
SubclassO2 error inherited overloads disagree: the one whose annotated self admits the class is missing from the other
SubclassQ1 Self return implements protocol's self-typed TypeVar return
SubclassQ2 error returns the declaring class, not the protocol's self-typed TypeVar

@heejaechang

Heejae Chang (heejaechang) commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

🔴 Pyright CLI QA — b7fee7ae — verdict: red

Automated CLI checks compared this change with its base revision.
17 focused check(s) completed.

Needs review: reportIncompatibleMethodOverride newly reported

The PR reports reportIncompatibleMethodOverride for this example; the base does not. Is this change intended?

Reproduction and observed results

Create these files in an empty directory:

main.py

from __future__ import annotations
from typing import Any, overload, assert_type
reveal_type(0)

class Restricted[T]:
    @overload
    def f(self: Restricted[int], x: int, /) -> int: ...
    @overload
    def f(self, x: str, /) -> str: ...
    @overload
    def f(self, x: bytes, /) -> bytes: ...
    def f(self, x: Any, /) -> Any: return x

class Ordinary:
    @overload
    def f(self, x: str, /) -> str: ...
    @overload
    def f(self, x: bytes, /) -> bytes: ...
    def f(self, x: str | bytes, /) -> str | bytes: return x

class Child(Ordinary, Restricted[str]): pass

def consume(c: Child, b: Restricted[str]) -> None:
    assert_type(c.f('s'), str)
    assert_type(c.f(b's'), bytes)
    assert_type(b.f('s'), str)
    c.f('s').upper()
    c.f(b's').decode()

pyrightconfig.json

{
  "include": [
    "main.py"
  ],
  "pythonVersion": "3.13",
  "typeCheckingMode": "standard",
  "reportIncompatibleMethodOverride": "error"
}

From that directory, run each built Pyright revision:

node <pyright-cli-entrypoint> --outputjson -p .

Base 373ab64710970ab3f9e7f15b56be89d6f542d572

{
  "exit_code": 0,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          2,
          12
        ],
        "end": [
          2,
          13
        ]
      }
    }
  ]
}

PR b7fee7ae098f080124f06e7865c62fe2db51a6a6

{
  "exit_code": 1,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "error",
      "rule": "reportIncompatibleMethodOverride",
      "message": "Base classes for class \"Child\" define method \"f\" in incompatible way\n  Override does not handle all overloads of base method",
      "range": {
        "start": [
          20,
          6
        ],
        "end": [
          20,
          11
        ]
      }
    },
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          2,
          12
        ],
        "end": [
          2,
          13
        ]
      }
    }
  ]
}

Diagnostic ranges use zero-based line and character positions.

Needs review: reportIncompatibleMethodOverride newly reported

The PR reports reportIncompatibleMethodOverride for this example; the base does not. Is this change intended?

Reproduction and observed results

Create these files in an empty directory:

main.py

from typing import Protocol, Self, assert_type
reveal_type(0)

class P(Protocol):
    def clone[T: P](self: T) -> T: return self
class M:
    def clone(self) -> Self: return self
class Child(M, P): pass

def consume(c: Child) -> None:
    assert_type(c.clone(), Child)
    p: P = c
    c.clone().clone()

pyrightconfig.json

{
  "include": [
    "main.py"
  ],
  "pythonVersion": "3.13",
  "typeCheckingMode": "standard",
  "reportIncompatibleMethodOverride": "error"
}

From that directory, run each built Pyright revision:

node <pyright-cli-entrypoint> --outputjson -p .

Base 373ab64710970ab3f9e7f15b56be89d6f542d572

{
  "exit_code": 0,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          1,
          12
        ],
        "end": [
          1,
          13
        ]
      }
    }
  ]
}

PR b7fee7ae098f080124f06e7865c62fe2db51a6a6

{
  "exit_code": 1,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "error",
      "rule": "reportIncompatibleMethodOverride",
      "message": "Base classes for class \"Child\" define method \"clone\" in incompatible way\n  Return type mismatch: base method returns type \"Child\", override returns type \"Self@M\"\n    \"M*\" is not assignable to \"Child\"",
      "range": {
        "start": [
          7,
          6
        ],
        "end": [
          7,
          11
        ]
      }
    },
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          1,
          12
        ],
        "end": [
          1,
          13
        ]
      }
    }
  ]
}

Diagnostic ranges use zero-based line and character positions.

Needs review: reportIncompatibleMethodOverride newly reported

The PR reports reportIncompatibleMethodOverride for this example; the base does not. Is this change intended?

Reproduction and observed results

Create these files in an empty directory:

main.py

from typing import overload, assert_type
reveal_type(0)

class Base:
    @overload
    def f[T](self, x: bool, y: int | T, /) -> T | int: ...
    @overload
    def f(self, x: int, y: int, /) -> int: ...
    def f(self, x: object, y: object, /) -> object: return y

class Child(Base):
    @overload
    def f[T](self, x: bool, y: int | T, /) -> T | int: ...
    @overload
    def f(self, x: int, y: int, /) -> int: ...
    def f(self, x: object, y: object, /) -> object: return y

def consume(b: Base, c: Child) -> None:
    assert_type(b.f(True, 1), int)
    assert_type(c.f(True, 1), int)
    assert_type(b.f(True, 's'), str | int)
    assert_type(c.f(True, 's'), str | int)
    c.f(True, 1).bit_length()

pyrightconfig.json

{
  "include": [
    "main.py"
  ],
  "pythonVersion": "3.13",
  "typeCheckingMode": "standard",
  "reportIncompatibleMethodOverride": "error",
  "reportOverlappingOverload": "none"
}

From that directory, run each built Pyright revision:

node <pyright-cli-entrypoint> --outputjson -p .

Base 373ab64710970ab3f9e7f15b56be89d6f542d572

{
  "exit_code": 0,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          1,
          12
        ],
        "end": [
          1,
          13
        ]
      }
    }
  ]
}

PR b7fee7ae098f080124f06e7865c62fe2db51a6a6

{
  "exit_code": 1,
  "diagnostics": [
    {
      "file": "main.py",
      "severity": "error",
      "rule": "reportIncompatibleMethodOverride",
      "message": "Method \"f\" overrides class \"Base\" in an incompatible manner\n  Override does not handle all overloads of base method",
      "range": {
        "start": [
          15,
          8
        ],
        "end": [
          15,
          9
        ]
      }
    },
    {
      "file": "main.py",
      "severity": "information",
      "rule": null,
      "message": "Type of \"0\" is \"Literal[0]\"",
      "range": {
        "start": [
          1,
          12
        ],
        "end": [
          1,
          13
        ]
      }
    }
  ]
}

Diagnostic ranges use zero-based line and character positions.

When an overloaded method overrides an overloaded method, the check
stops at the first override overload that matches no base overload,
and requires only the base overloads after the last match to be handled.

Iterate over the base overloads instead, and require each applicable one
to match an override overload at or after the previous match.

Fixes microsoft#11836
@bschnurr

Copy link
Copy Markdown
Member

/benchmark

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Diff from mypy_primer, showing the effect of this PR on open source code:

pyodide (https://github.com/pyodide/pyodide)
+   .../projects/pyodide/src/py/_pyodide/_core_docs.py:1120:9 - error: Method "get" overrides class "Mapping" in an incompatible manner
+     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/pyodide/src/py/_pyodide/_core_docs.py:1131:7 - error: Base classes for class "JsMutableMap" define method "get" in incompatible way
+   .../projects/pyodide/src/py/_pyodide/_core_docs.py:1158:9 - error: Method "pop" overrides class "MutableMapping" in an incompatible manner
- 850 errors, 24 warnings, 0 informations
+ 851 errors, 24 warnings, 0 informations

werkzeug (https://github.com/pallets/werkzeug)
-   .../projects/werkzeug/src/werkzeug/datastructures/accept.py:61:9 - error: Method "__getitem__" overrides class "Sequence" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 326 errors, 22 warnings, 0 informations
+ 325 errors, 22 warnings, 0 informations

Tanjun (https://github.com/FasterSpeeding/Tanjun)
-   .../projects/Tanjun/tanjun/clients.py:2250:9 - warning: Method "iter_menu_commands" overrides class "Client" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 36 errors, 112 warnings, 0 informations
+ 36 errors, 111 warnings, 0 informations

mypy (https://github.com/python/mypy)
-   .../projects/mypy/mypy/typeshed/stdlib/configparser.pyi:385:9 - error: Method "get" overrides class "Mapping" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/mypy/mypy/typeshed/stdlib/ssl.pyi:411:9 - error: Method "get_ca_certs" overrides class "_SSLContext" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/mypy/mypy/typeshed/stdlib/tempfile.pyi:257:9 - error: Method "write" overrides class "IO" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/mypy/mypy/typeshed/stdlib/tempfile.pyi:264:9 - error: Method "writelines" overrides class "IO" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/mypy/mypy/typeshed/stdlib/tempfile.pyi:390:9 - error: Method "write" overrides class "IO" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
-   .../projects/mypy/mypy/typeshed/stdlib/tempfile.pyi:397:9 - error: Method "writelines" overrides class "IO" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 1065 errors, 79 warnings, 0 informations
+ 1059 errors, 79 warnings, 0 informations

xarray (https://github.com/pydata/xarray)
-   .../projects/xarray/xarray/core/datatree.py:325:9 - error: Method "__getitem__" overrides class "Dataset" in an incompatible manner
+   .../projects/xarray/xarray/core/utils.py:558:9 - error: Method "get" overrides class "Mapping" in an incompatible manner

pandas-stubs (https://github.com/pandas-dev/pandas-stubs)
+ .../projects/pandas-stubs/pandas-stubs/_libs/tslibs/timedeltas.pyi
+   .../projects/pandas-stubs/pandas-stubs/_libs/tslibs/timedeltas.pyi:260:9 - error: Method "__truediv__" overrides class "timedelta" in an incompatible manner
+     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
+ .../projects/pandas-stubs/pandas-stubs/_stubs_only/__init__.pyi
+   .../projects/pandas-stubs/pandas-stubs/_stubs_only/__init__.pyi:477:38 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
+ .../projects/pandas-stubs/pandas-stubs/core/indexes/multi.pyi
+   .../projects/pandas-stubs/pandas-stubs/core/indexes/multi.pyi:173:36 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
+ .../projects/pandas-stubs/pandas-stubs/core/series.pyi
+   .../projects/pandas-stubs/pandas-stubs/core/series.pyi:5012:38 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
+ .../projects/pandas-stubs/pandas-stubs/core/window/ewm.pyi
+   .../projects/pandas-stubs/pandas-stubs/core/window/ewm.pyi:59:39 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
- 208 errors, 3 warnings, 0 informations
+ 213 errors, 3 warnings, 0 informations

pip (https://github.com/pypa/pip)
+ .../projects/pip/src/pip/_vendor/requests/structures.py
+   .../projects/pip/src/pip/_vendor/requests/structures.py:129:9 - error: Method "get" overrides class "dict" in an incompatible manner
+     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 564 errors, 38 warnings, 0 informations
+ 565 errors, 38 warnings, 0 informations

steam.py (https://github.com/Gobot1234/steam.py)
+   .../projects/steam.py/steam/utils.py:565:9 - error: Method "pop" overrides class "ChainMap" in an incompatible manner
+     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 8304 errors, 87 warnings, 0 informations
+ 8305 errors, 87 warnings, 0 informations

scipy-stubs (https://github.com/scipy/scipy-stubs)
+   .../projects/scipy-stubs/scipy-stubs/sparse/_dok.pyi:93:72 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
+   .../projects/scipy-stubs/scipy-stubs/stats/_distribution_infrastructure.pyi:481:35 - error: Unnecessary "# pyright: ignore" rule: "reportIncompatibleMethodOverride" (reportUnnecessaryTypeIgnoreComment)
- 1634 errors, 0 warnings, 0 informations
+ 1636 errors, 0 warnings, 0 informations

bidict (https://github.com/jab/bidict)
- .../projects/bidict/bidict/_bidict.py
-   .../projects/bidict/bidict/_bidict.py:158:9 - error: Method "pop" overrides class "MutableMapping" in an incompatible manner
-     Override does not handle all overloads of base method (reportIncompatibleMethodOverride)
- 12 errors, 1 warning, 0 informations
+ 11 errors, 1 warning, 0 informations

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

mypy_primer analysis

Advisory AI analysis of primer run 37828221797, attempt 1
for commit ae662b427371b03ff238243cf8e77361e5a54986. This is not an approval or proof of correctness.

Regression review required. Potential regressions or recorded warning signals are listed first; causation must be established separately.

Potential regressions

pyodide: Override checking moved from a JsMutableMap base-conflict error to uncovered get/pop overload errors; the new pop finding may be useful, but valid Mapping coverage is not established.

AI assessment: Possible regression (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The recorded baseline reported at _core_docs.py:1131 that JsMutableMap's bases defined get incompatibly. It did not report the individual get override at line 1120 or pop at line 1158. No baseline inferred type or runtime failure is evidenced.

After / PR evidence: The recorded run removes the multiple-inheritance get conflict, but reports that get at _core_docs.py:1120 does not cover every Mapping overload and pop at line 1158 does not cover every MutableMapping overload. This is a checking/localization change, not type erasure.

Why this matters: Users can no longer rely on these protocol-like JS map declarations passing override validation. Conversely, the more local errors may identify calls allowed through Mapping/MutableMapping views that the concrete signatures reject. The net-new pop error can break strict CI even if runtime behavior is unchanged.

Causal analysis:

The PR replaces child-overload iteration with ordered coverage of each base overload. For every base alternative it searches compatible child overloads; earlier unmatched child alternatives are allowed only when they do not overlap incompatibly. That directly explains both the disappearance of a coarse base/base get conflict and the appearance of declaration-local get/pop coverage failures. However, the exact recorded overload sets and tested synthetic merge SHA were not recovered, so it is unresolved whether JsMap intentionally accepts the full Mapping key/default combinations or whether Pyright is mishandling generics/overlap. There are no manifest type-erasure or assertion-failure signals; the risk is stricter protocol substitution checking.

Uncertainty / next check: At the recorded Pyodide revision, compare get/pop against Mapping and MutableMapping overloads. Positive control: calls through the base type for omitted, same-type, and unrelated defaults. Negative control: a deliberately narrowed key/default overload. Confirm which base alternative remains unmatched.

xarray: A DataTree.__getitem__ error is removed while Frozen.get gains a Mapping coverage error; the mixed result may improve one extension case but regress generic default handling.

AI assessment: Possible regression (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline flagged DataTree.__getitem__ at datatree.py:325 and did not flag Frozen.get. The raw diff provides no inferred return types and does not establish whether DataTree's extra key forms overlap Dataset indexing.

After / PR evidence: The DataTree diagnostic disappears, while utils.py:558 now reports Frozen.get does not cover all Mapping overloads. No Any/Unknown transition is recorded; the changed behavior is which inherited call shapes are considered covered.

Why this matters: DataTree extensions may stop producing a false warning, but strict xarray checks now fail on Frozen.get. More importantly, if Frozen's get annotation validly supports omitted and arbitrary defaults, users may lose a trustworthy generic Mapping override check; if it narrows a form, the new error restores useful substitution checking.

Causal analysis:

Both changes follow the PR's base-first ordered matcher. It can accept extra nonoverlapping child overloads (plausibly DataTree indexing) while newly detecting a base overload that no child alternative covers (Frozen.get). That is stronger evidence of the PR mechanism than of correctness. Mapping.get's default-sensitive generic overloads are a known stress case, and the exact recorded Frozen declaration and synthetic merge checkout were not recovered. Because the project has both directions and the added diagnostic may be a generic-matching false positive, a blanket expected classification would be unsafe.

Uncertainty / next check: Compare Frozen.get with all Mapping.get forms at the recorded revision, including omitted default, value-typed default, and unrelated default. For DataTree, verify every Dataset key/slice form plus the added key forms; an overlapping incompatible-return overload should remain rejected.

pandas-stubs: Timedelta.__truediv__ newly fails base coverage while four old override suppressions become stale; the division error may expose a narrowed timedelta operand or a matcher defect.

AI assessment: Possible regression (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline accepted Timedelta.__truediv__ at timedeltas.pyi:260 and consumed override ignores at four other declarations. Inspection of current upstream shows operand-specific division overloads, but that is not proof of the exact recorded revision.

After / PR evidence: The run adds a missing-overload override error for __truediv__ and marks override ignores unnecessary at _stubs_only:477, multi:173, series:5012, and ewm:59. These are separate results; the stale-ignore details must not be assigned to the Timedelta header.

Why this matters: Strict stub validation now fails. The new error could usefully show that Timedelta / datetime.timedelta, supported by the base API, is omitted when an overload accepts only Self/NaT; alternatively, a valid overload family is rejected. Four declarations can drop suppressions only if checks were correctly restored, not silently weakened.

Causal analysis:

The PR requires each applicable base timedelta overload to be covered in order by a child overload. Timedelta adds multiple operand-specialized returns, so an inherited timedelta-divisor alternative can remain unmatched even though some child overloads each match another base form. This is exactly the new branch. The same algorithm can remove false errors for unrelated declarations with additional nonoverlapping overloads, yielding unnecessary-ignore diagnostics. Counterevidence is that a Self operand may intentionally be narrower than datetime.timedelta and thus represent a real stub issue. The precise unmatched overload and exact primer checkout are unavailable, so neither the stub nor checker can be blamed conclusively.

Uncertainty / next check: At the recorded stub revision, test Timedelta divided by int, float, datetime.timedelta, Timedelta, NaT, and ndarray and assert returns. A negative control that narrows datetime.timedelta to Self should fail; a fully contravariant operand overload should pass.

pip: Vendored requests.LookupDict.get newly fails dict.get coverage; default-sensitive generics may reveal a real missing form or a false failure when one child overload covers multiple bases.

AI assessment: Possible regression (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline accepted LookupDict.get at structures.py:129. Current upstream defines omitted/None and generic-default forms, but it was not proven identical to the recorded primer checkout.

After / PR evidence: The recorded run reports that LookupDict.get does not handle every dict.get overload. No type erasure or changed call-site inference is shown.

Why this matters: Pip's strict check gains an error in vendored code. If sound, it warns that a call permitted through dict—especially a default-sensitive form—cannot be substituted safely. If unsound, downstream maintainers must suppress a valid conventional get annotation and lose confidence in override checks.

Causal analysis:

At the exact PR head, validation iterates each base overload and searches ordered child alternatives; a child alternative can be reconsidered, but generic specialization and return compatibility must still prove coverage. dict.get combines omitted-default, same-value-default, and unrelated-default returns, while LookupDict supplies its own overload family. The new error therefore follows the changed coverage decision. The inspected declaration appears intended to model the conventional get API, which is counterevidence against immediately blaming the vendored annotation, but the precise unmatched base alternative was not available. This is a credible checker regression or exposed incompatibility, not an established runtime bug.

Uncertainty / next check: On the recorded revision, assert LookupDict[str, V].get for omitted, None, V, and unrelated D defaults, both concretely and through dict[str, V]. A deliberately missing unrelated-default overload is the negative control; record which base overload the checker cannot match.

Unresolved investigations

Tanjun: iter_menu_commands now passes override validation, but the exact child/base overload ordering was not recovered, so a false positive fix cannot be distinguished from a suppressed check.

AI assessment: Needs human review (low confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The recorded baseline warned at clients.py:2250 that iter_menu_commands did not handle all Client overloads. The raw evidence does not include the signatures or reveal types.

After / PR evidence: That warning disappears. No evidence shows changed call-site inference, Any/Unknown, or assertion failures; only override validation changed.

Why this matters: Strict users no longer receive this inheritance warning. That is beneficial if Tanjun adds a nonoverlapping overload while preserving Client operations, but harmful if a base call shape is actually missing and is now accepted.

Causal analysis:

The exact PR implementation changed overload validation to iterate every base overload and seek ordered child coverage, allowing unmatched child overloads only when they do not incompatibly overlap a base domain. This mechanism directly governs the removed warning. Without the recorded Client and overriding signatures, it is not possible to show that all base call shapes remain accepted or that added menu-command specializations are disjoint. The exact synthetic merge checkout also remains unresolved, so this should not be classified as an expected fix solely because one warning vanished.

Uncertainty / next check: Inspect both iter_menu_commands overload sets at the recorded revision. Test every base call shape through a Client-typed value, then add one earlier child overload with overlapping parameters and an incompatible iterator element type as the negative control.

mypy: Six vendored-typeshed overload coverage errors disappear across unrelated APIs; they may be old algorithm false positives, but preserved base operations were not verified.

AI assessment: Needs human review (low confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline reported missing base-overload coverage for configparser.get (385), ssl.get_ca_certs (411), and tempfile write/writelines pairs (257, 264, 390, 397). These are observed diagnostics, not evidence that calls inferred incorrectly.

After / PR evidence: All six override diagnostics disappear. The concise diff contains no call-site reveals or unchanged context, so it does not establish whether each declaration retains all Mapping, _SSLContext, and IO operations.

Why this matters: Mypy's vendored stubs require fewer suppressions, but users can no longer rely on Pyright flagging a missing base call shape in these six declarations unless the new ordered-coverage proof is sound for their generic and overloaded signatures.

Causal analysis:

The PR reverses the validation perspective: it walks applicable base overloads, finds compatible child overloads in order, and tolerates extra child alternatives when they do not overlap incompatibly. That can correctly remove errors caused merely by specialization overloads, but six unrelated APIs exercise defaults, generic IO element types, and platform/version-sensitive declarations. Their exact recorded overload sets were not inspected, and current typeshed would not prove what the vendored checkout contained. There are no type-erasure/assertion signals, but absence of such signals does not establish sound override checking.

Uncertainty / next check: At the recorded vendored-typeshed commit, map every base overload to a child overload for each location. Positive controls should call all base forms through base-typed values; negative controls should delete one base-compatible child alternative and require the diagnostic to return.

steam.py: steam.utils.pop newly fails ChainMap overload coverage, but the affected class and exact base/child signatures were not recovered, so the new diagnostic's soundness is unresolved.

AI assessment: Needs human review (low confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline did not report an override error at steam/utils.py:565. The concise evidence does not include the class context, overloads, or inferred call-site types.

After / PR evidence: The recorded run reports that pop does not handle every ChainMap overload. No assertion failure or Any/Unknown transition accompanies it.

Why this matters: Strict checking now rejects this utility. A sound result would protect callers using ChainMap's key/default forms; a false result would force a suppression on a valid overloaded pop and reduce confidence in checker diagnostics.

Causal analysis:

The PR changed validation from checking child overloads against some base alternative to proving ordered coverage of every applicable base alternative. ChainMap.pop has default-sensitive overloads similar to MutableMapping.pop, so the new loop can expose an uncovered form that the old direction skipped. However, the exact steam.py declaration could not be inspected at the primer revision, and no raw detail identifies which base alternative failed. The exact tested synthetic merge SHA was also not recovered. The causal mechanism is likely the PR, but whether this is restored checking or a generic/default matching regression remains unknown.

Uncertainty / next check: Inspect line 565 at the recorded revision and enumerate pop(key), pop(key, value-default), and pop(key, unrelated-default) through both concrete and ChainMap-typed references. Remove one default form as a negative control and require a failure.

scipy-stubs: Two override suppressions become unnecessary, indicating removed underlying errors, but the hidden declarations were not inspected enough to show that inherited operations remain covered.

AI assessment: Needs human review (low confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline consumed reportIncompatibleMethodOverride ignores at sparse/_dok.pyi:93 and stats/_distribution_infrastructure.pyi:481. The concise diff omits the suppressed diagnostic headers and signature context.

After / PR evidence: Both comments are reported unnecessary. This establishes only that the new checker no longer emits the suppressed override diagnostics; it does not establish unchanged inference or assign a particular base method to either detail line.

Why this matters: Maintainers can potentially remove stale ignores, but users can no longer rely on the previously suppressed checks unless the added overloads are truly nonoverlapping and all base call forms remain represented.

Causal analysis:

The PR's base-first algorithm permits extra child overloads after finding ordered coverage for each base overload, unless an earlier extra overload overlaps incompatibly. That can remove false override errors and make targeted ignores stale. Because detail-only lines have no diagnostic header in the raw diff, attributing either ignore to a specific method or location beyond its comment would fabricate context. The exact declarations and primer revision were not recovered, so it is unknown whether these are expected cleanup or suppressed legitimate checks. There are no type-erasure/assertion signals, but that does not prove safety.

Uncertainty / next check: Read both annotated declarations at the recorded scipy-stubs revision and reconstruct the diagnostics without ignores. Positive controls must exercise every inherited call shape; an overlapping earlier overload with incompatible return should remain a negative failure.

Other project assessments

werkzeug: Accept.__getitem__ retains Sequence's index/slice cases while adding a nonoverlapping str lookup; removing the old coverage error restores useful overload extension.

AI assessment: Expected improvement (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline flagged Accept.__getitem__ at accept.py:61 as not handling every Sequence overload. The declaration has an added str -> float lookup alongside inherited-compatible integer-index and slice behavior; the old algorithm could stop on the extra first overload rather than establish base coverage.

After / PR evidence: The override diagnostic is removed. Sequence-style indexing and slicing remain statically represented, while Accept's string quality lookup remains available; no inferred type was shown to become Any or Unknown.

Why this matters: Werkzeug can expose both its domain-specific string lookup and the complete Sequence API without a false override failure. Downstream users retain checked return distinctions rather than suppressing the override diagnostic or weakening the declaration.

Causal analysis:

At the exact PR head, Pyright now proves coverage by walking each base overload in order instead of requiring each child overload to map to a base overload. Extra child overloads are permitted unless an earlier one overlaps a base parameter domain with an incompatible return. Accept's str key is separate from Sequence's SupportsIndex/slice domains, while the later alternatives cover those base operations, so the removed diagnostic follows the intended branch. This is consistent with an expected fix rather than erased checking. The ecosystem source inspected was current upstream rather than the exact primer checkout, and the synthetic merge SHA was not exposed, which limits confidence.

Uncertainty / next check: Check the exact recorded Werkzeug revision and assert positive controls for str, SupportsIndex, and slice keys plus a negative control where the added key overlaps SupportsIndex but returns an incompatible type.

bidict: MutableBidict.pop's two overloads cover MutableMapping's no-default/default behavior; removing the old missing-overload error appears to fix matching direction/order.

AI assessment: Expected improvement (medium confidence). PR attribution: Likely caused by the PR.

Before / baseline evidence: The baseline flagged MutableBidict.pop at _bidict.py:158 as failing to handle all MutableMapping overloads. Inspection of current upstream shows separate no-default and default forms, consistent with the base API, though it is not the exact recorded checkout.

After / PR evidence: The override diagnostic is removed. There is no evidence of erased types or reduced call-site checking; the concrete overload distinctions remain declared.

Why this matters: Bidict users retain checked pop return behavior with and without a default, while maintainers no longer need to suppress an apparent false positive. Valid extra specialization is no longer mistaken for missing base coverage.

Causal analysis:

The PR now walks each MutableMapping.pop base overload and finds compatible MutableBidict child overloads in order, rather than requiring each child overload to map cleanly under the old directional logic. The observed two-form declaration provides the inherited no-default/default operations, so the removed diagnostic is consistent with restored overload-extension support. The new algorithm still checks earlier unmatched overlapping overloads for incompatible returns, preserving a negative check rather than accepting all extras. Confidence is limited because current upstream, not the recorded ecosystem revision, was inspected and the synthetic merge SHA was not recovered.

Uncertainty / next check: Verify the recorded revision with pop(key), pop(key, V default), and pop(key, unrelated D default) through MutableMapping and MutableBidict views. A child overload narrowed to one default type should be rejected as the negative control.

Full evidence and limitations: download mypy-primer-analysis-report from this analysis run.
The original raw primer comment is unchanged. Treat uncertainty and possible regressions as requests for human review.

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Compared candidate 6c4c43a30c79c4108984880a5b27827ff34a5aca against its first parent 386cfa1161b63f048a9ea663d84189e69ced33b1.

View the full release history charts with the base and PR results.

Execution time history

Execution time history

Peak memory history

Peak memory history

Download the chart artifact.

Type checker benchmark

🟢 No performance regressions detected.

Regression threshold: 20.0%
Statistic: median
Variance guard: >1.0s time and >100.0 MB memory

Package Checker Files checked Time Time delta Peak memory Memory delta Status
ansible pyright 583 20.204s +1.5% 1079.4 MB -0.5% 🟢 Pass
click pyright 17 3.000s -1.5% 354.9 MB -0.2% 🟢 Pass
homeassistant pyright 9850 131.828s +2.8% 6089.2 MB -0.2% 🟢 Pass
numpy pyright 356 23.565s -1.5% 1352.7 MB -1.7% 🟢 Pass
pandas pyright 1459 141.771s -0.1% 3528.8 MB -0.8% 🟢 Pass
pytest pyright 243 12.028s -0.7% 848.9 MB -0.7% 🟢 Pass
requests pyright 19 2.439s +0.5% 342.7 MB -0.6% 🟢 Pass
torch pyright 2400 80.006s -4.9% 4729.4 MB +0.1% 🟢 Pass
transformers pyright 2901 110.762s -8.3% 5233.0 MB +5.1% 🟢 Pass

Pyright stats

Package Parsed/bound Checked Find Read Tokenize Parse Imports Bind Check Cycles
ansible 988 583 0.043s 0.087s 0.450s 0.780s 0.227s 0.997s 16.740s 0.000s
click 111 17 0.000s 0.013s 0.130s 0.223s 0.033s 0.263s 2.030s 0.000s
homeassistant 11146 9850 0.407s 0.683s 2.770s 4.897s 1.970s 6.383s 109.797s 0.000s
numpy 602 356 0.010s 0.053s 0.237s 0.453s 0.157s 0.580s 21.730s 0.000s
pandas 1894 1459 0.070s 0.247s 1.200s 2.653s 0.333s 2.887s 132.377s 0.000s
pytest 541 243 0.020s 0.060s 0.347s 0.527s 0.107s 0.673s 9.917s 0.000s
requests 167 19 0.000s 0.020s 0.120s 0.227s 0.057s 0.277s 1.427s 0.000s
torch 3078 2400 0.070s 0.267s 1.497s 2.647s 0.443s 3.377s 69.033s 0.000s
transformers 3535 2901 0.130s 0.407s 2.120s 3.790s 0.900s 9.077s 101.203s 0.000s

@crypt0lith
crypt0lith force-pushed the fix/overload-override-coverage branch from 06d8525 to a7c1a8b Compare October 9, 2026 20:26
@crypt0lith crypt0lith changed the title Fix overloaded override check stopping at an added overload Fix override checks for overloads, annotated self and return TypeVars Oct 9, 2026
@crypt0lith

Copy link
Copy Markdown
Contributor Author

Heejae Chang (@heejaechang) The remaining items flagged by the Pyright CLI QA bot run on 52471b7 are from commits merged into main after this PR was created (d057c72 specifically):

$ MERGEBASE=$(git merge-base fix/overload-override-coverage upstream/main); echo $MERGEBASE
fbaf3ddc8b3d8bb9613b06c51db01658f4967c6b
                                                                                                                                                                                                                    
$ git log --pretty=reference $MERGEBASE..a41e22124 | cat
a41e22124 (Fix type inference for TypedDict unpacking in dictionary displays (#11611), 2026-10-09)
2a9c70053 (Add Pyright issue reviewer and fixer agents (#11848), 2026-10-08)
612ff0406 (Preserve exception target types past the declaration limit (#11797), 2026-10-09)
b8d9b94ff (Fix benchmark trigger candidate commit resolution (#11799), 2026-10-08)
d057c7275 (Fix lambda contextual typing with keyword-only callables (#11609), 2026-10-08)
386cfa116 (Fix SymPy in mypy_primer (#11826), 2026-10-07)
6edf06800 (Fix runtime protocol narrowing in class patterns (#11843), 2026-10-07)
c9e503f04 (Skip unavailable workflow runs when publishing PR benchmark charts (#11845), 2026-10-07)
5f7a15ed7 (Run primer and analyzer benchmarks after approved Validation (#11821), 2026-10-07)
e8c4d19d3 (Fix type narrowing for class equality comparisons (#11607), 2026-10-06)
eb175addd (Fix inherited asymmetric descriptor detection (#11605), 2026-10-06)
02c7b9480 (Fix printing of type arguments for specialized recursive type aliases (#11600), 2026-10-06)

@crypt0lith
crypt0lith force-pushed the fix/overload-override-coverage branch 2 times, most recently from 49ec885 to 110a44c Compare October 23, 2026 09:49
@crypt0lith
crypt0lith force-pushed the fix/overload-override-coverage branch from 37808dc to 775b877 Compare November 3, 2026 10:30
@crypt0lith
crypt0lith force-pushed the fix/overload-override-coverage branch from 775b877 to 02c4990 Compare November 3, 2026 10:41
@bschnurr

Copy link
Copy Markdown
Member

Local review: cdeb59d1 integrated with ff00b031.

I replayed the older QA examples on this head. Two clean samples still gain reportIncompatibleMethodOverride: the multiple-inheritance case where the restricted overload is inapplicable to Restricted[str], and the case where M.clone() -> Self implements the protocol's generic-self clone. The identical-overload example also adds an override diagnostic, but it already reports overlapping overloads on main, so it is weaker evidence. All nine focused repository tests passed. Can we add both clean multiple-inheritance cases as controls?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Overloaded override stops being checked at an added overload Inconsistency between override validation and protocol matching

3 participants