Don't report abstract instantiation when __new__ returns other classes

[Shubham Padkonde (Shubham-Padkonde)]

Fixes #11255

Problem

A class can define __new__ so that calling it always produces some other concrete class. pathlib.Path is the canonical example — instantiating it yields a PosixPath or a WindowsPath.

pyright already understands the return type: given def __new__(cls) -> "Foo | Bar", Base() evaluates to Foo | Bar. But the abstract check in validateCallForInstantiableClass runs before the constructor is evaluated, so if Base has abstract members the call is still reported:

error: Cannot instantiate abstract class "Base"
    "Base.method" is not implemented

That makes the pattern unusable with an abstract base, even though no abstract instance is ever created.

Fix

Before reporting reportAbstractUsage, check whether the class's __new__ is declared to return only instances of other classes that are themselves concrete. Existing behaviour is kept everywhere else:

• __new__ returning the class itself or Self → still reported;
• a returned class that is itself abstract → still reported;
• overloaded or synthesized __new__ (including the default object.__new__ signature) → still reported, since getBoundNewMethod skips the object base class and the helper bails out on anything that is not a plain function;
• Never and non-class return types → still reported.

Test

abstractClass12.py covers all three cases: a Base whose __new__ returns Concrete1 | Concrete2 (no error, and reveal_type confirms the call still evaluates to that union), a class whose __new__ returns an abstract class, and one whose __new__ returns itself — the last two still error, so the sample expects exactly 2 errors.

On main the sample produces 3 errors:

✕ AbstractClass12
    Expected 2 errors, got 3

With the change:

$ npx jest checker
Tests: 75 passed, 75 total

$ npx jest typeEvaluator
Test Suites: 8 passed, 8 total
Tests:       1223 passed, 1223 total

prettier --check is clean.

---

Disclosure: this change was written by Claude Code (Claude Opus 5) working as my agent, at my direction. The test output quoted above comes from real runs in my local environment; I am accountable for what is submitted here and will follow up on review feedback.

🤖 Generated with Claude Code

[github-actions]

Compared candidate 5719ce2af25588bd37d1867ce9a48d5b09419c4c against its first parent 916d7dc62e063ba6342493e44fc55389d42d5120.

Type checker benchmark

🟢 No performance regressions detected.

Regression threshold: 20.0%
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	15.227s	-29.7%	1231.4 MB	+10.9%	🟢 Pass
click	pyright	17	2.230s	-23.3%	359.1 MB	-0.5%	🟢 Pass
homeassistant	pyright	9850	111.665s	-29.5%	6206.7 MB	+0.2%	🟢 Pass
numpy	pyright	356	27.923s	-35.7%	1637.1 MB	-11.5%	🟢 Pass
pandas	pyright	1459	788.887s	-20.2%	4423.8 MB	-0.2%	🟢 Pass
pytest	pyright	243	10.639s	-15.4%	879.1 MB	-5.6%	🟢 Pass
requests	pyright	19	1.969s	-14.4%	345.6 MB	-0.5%	🟢 Pass
torch	pyright	2400	111.132s	-27.7%	5009.9 MB	+2.4%	🟢 Pass
transformers	pyright	2901	98.934s	-26.5%	5160.0 MB	+0.6%	🟢 Pass

Pyright stats

Package	Parsed/bound	Checked	Find	Read	Tokenize	Parse	Imports	Bind	Check	Cycles
ansible	989	583	0.030s	0.070s	0.310s	0.710s	0.190s	0.830s	12.580s	0.000s
click	111	17	0.000s	0.010s	0.100s	0.160s	0.030s	0.200s	1.500s	0.000s
homeassistant	11147	9850	0.330s	0.610s	2.260s	3.940s	1.840s	5.560s	94.590s	0.000s
numpy	603	356	0.010s	0.070s	0.260s	0.550s	0.200s	0.700s	25.660s	0.000s
pandas	1895	1459	0.050s	0.210s	0.960s	1.760s	0.280s	2.180s	782.310s	0.000s
pytest	542	243	0.010s	0.060s	0.310s	0.460s	0.090s	0.660s	8.650s	0.000s
requests	168	19	0.000s	0.030s	0.110s	0.180s	0.050s	0.230s	1.110s	0.000s
torch	3079	2400	0.110s	0.390s	1.730s	2.960s	0.550s	3.970s	100.200s	0.000s
transformers	3537	2901	0.100s	0.340s	1.950s	3.020s	0.820s	7.670s	87.450s	0.000s

[Bill Schnurr (bschnurr)]

🔒 Automated review in progress — Bill Schnurr (@bschnurr) is auto-reviewing this PR.

[Bill Schnurr (bschnurr)]

Info · Optional note

The comment describing getAbstractSymbols now precedes instantiatesOnlyOtherConcreteClasses, where it incorrectly describes the following function. Move it immediately above getAbstractSymbols.

[verified]

[Shubham Padkonde (Shubham-Padkonde)]

Moved back in 2235d59 — the getAbstractSymbols comment now sits directly above that function again, and the new function carries its own comment.

[Bill Schnurr (bschnurr)]

Result: ⚠️ needs-more-tests

Verification details

Verification: Isolated verification observed failures whose relationship to this PR could not be determined: Type evaluator tests; this review is not fully verified. Isolated verification observed failures that were not classified as caused by this PR: Dependency and test discovery.

Summary: The targeted abstract-class checker tests passed: all 12 `AbstractClass` cases, including the new `AbstractClass12`, succeeded. The broader type-evaluator run exceeded the 300-second limit without producing a result. Coverage is missing for explicitly preserved cases such as `Self`, `Never`, non-class, and overloaded `__new__` return types, so confidence is limited.

Test runs: 1 passed, 2 failed

• ❌ Failed | relationship unknown | Type evaluator tests | node ./node_modules/jest/bin/jest.js typeEvaluator --runInBand
• ❌ Failed | unrelated to this PR | Dependency and test discovery | printf 'SANDBOX_PROFILE=%s\n' "${AUTOMATION_SANDBOX_PROFILE:-}"; node --version; pnpm --version; if [ -d node_modules ] && [ -d packages/pyright-internal/node_modules ]; then echo 'node_modules=present'; else echo 'node_modules=missing'; fi; test -f pnpm-lock.yaml && echo 'pnpm-lock.yaml=present'; git status --short; git log -1 --oneline; git diff --name-status HEAD^..HEAD; node packages/pyright-internal/node_modules/jest/bin/jest.js --listTests checker typeEvaluator | grep -E '(checker|typeEvaluator).test'
• ✅ Passed | Abstract class checker tests | node ./node_modules/jest/bin/jest.js src/tests/checker.test.ts --runInBand --testNamePattern='AbstractClass'

❌ Type evaluator tests diagnostic output

Command timed out after 300s; the sandbox container was destroyed.

❌ Dependency and test discovery diagnostic output

SANDBOX_PROFILE=typescript
v24.15.0
11.21.0
node_modules=missing
pnpm-lock.yaml=present
fatal: not a git repository
Error: Cannot find module '/workspace/packages/pyright-internal/node_modules/jest/bin/jest.js'

[Bill Schnurr (bschnurr)]

Approved via Review Center.

[Shubham Padkonde (Shubham-Padkonde)]

Both points addressed in 2235d59.

The comment — you were exactly right: the new function landed between the getAbstractSymbols comment and the function it documents. Moved back, so each comment now sits above its own function:

29472     // Determines whether the class's `__new__` method is declared to return
...
29476     function instantiatesOnlyOtherConcreteClasses(...)
...
29512     // Returns a list of unimplemented abstract symbols (methods or variables) for
29513     // the specified class.
29514     function getAbstractSymbols(classType: ClassType): AbstractSymbol[] {

The missing coverage — added all four cases. Two behave as the check intends, and two turned out differently from what I first assumed, so I checked them against main rather than writing the sample to match my expectation:

__new__ return type	error reported?	same on main?
Self	yes	yes
Never	yes	yes
Any (non-class)	no	yes — also no error on main
overloaded __new__	no	yes — also no error on main

Self and Never are the ones this check actively preserves, and they do still report. For the Any and overloaded cases the function returns false as designed, but no diagnostic appears — because the abstract check already tolerated those before this PR. I confirmed by reverting only typeEvaluator.ts to main: that run reports 5 errors on the extended sample (the 4 above plus Base(), which is the bug this PR fixes), and ReturnsNonClass() and OverloadedNew(1) are absent from both lists.

So I've written those two into the sample as not generating an error, with a comment saying the behavior predates this change, rather than asserting errors that never fire. Expected count moved 2 → 4.

The sample still pins the fix: reverting typeEvaluator.ts gives Expected 4 errors, got 5.

On the run that timed out in your sandbox — I ran it here without the 300s cap:

node ./node_modules/jest/bin/jest.js src/tests/typeEvaluator --runInBand

Test Suites: 8 passed, 8 total
Tests:       1223 passed, 1223 total

Also checker.test.ts: 75 passed, 75 total (all 12 AbstractClass cases), npx tsc --noEmit -p . clean, and ESLINT_USE_FLAT_CONFIG=false npx eslint src/analyzer/typeEvaluator.ts clean.

---

Disclosure: this change was written by Claude Code (Claude Opus 5) working as my agent, at my direction. The test output quoted above comes from real runs in my local environment; I am accountable for this PR.

[github-actions]

Compared candidate 08737407d831b83314bce5a0f7c14b9a14e31c6a against its first parent 916d7dc62e063ba6342493e44fc55389d42d5120.

Type checker benchmark

🟢 No performance regressions detected.

Regression threshold: 20.0%
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	19.598s	-9.5%	1093.1 MB	-1.6%	🟢 Pass
click	pyright	17	2.962s	+1.9%	357.8 MB	-0.9%	🟢 Pass
homeassistant	pyright	9850	136.429s	-13.8%	6156.3 MB	-0.6%	🟢 Pass
numpy	pyright	356	37.898s	-12.7%	1624.5 MB	-12.2%	🟢 Pass
pandas	pyright	1459	939.813s	-5.0%	4515.0 MB	+1.8%	🟢 Pass
pytest	pyright	243	13.057s	+3.8%	879.7 MB	-5.5%	🟢 Pass
requests	pyright	19	2.346s	+2.0%	342.0 MB	-1.5%	🟢 Pass
torch	pyright	2400	145.250s	-5.5%	4783.9 MB	-2.2%	🟢 Pass
transformers	pyright	2901	120.376s	-10.5%	5040.0 MB	-1.8%	🟢 Pass

Pyright stats

Package	Parsed/bound	Checked	Find	Read	Tokenize	Parse	Imports	Bind	Check	Cycles
ansible	989	583	0.040s	0.090s	0.380s	0.740s	0.220s	0.960s	16.600s	0.000s
click	111	17	0.000s	0.010s	0.120s	0.230s	0.030s	0.260s	2.020s	0.000s
homeassistant	11147	9850	0.430s	0.690s	2.790s	4.890s	2.020s	6.560s	116.190s	0.000s
numpy	603	356	0.010s	0.060s	0.380s	0.740s	0.280s	0.810s	35.050s	0.000s
pandas	1895	1459	0.070s	0.230s	1.100s	2.160s	0.300s	2.620s	932.030s	0.000s
pytest	542	243	0.020s	0.070s	0.360s	0.560s	0.110s	0.760s	10.740s	0.000s
requests	168	19	0.000s	0.010s	0.120s	0.220s	0.070s	0.260s	1.350s	0.000s
torch	3079	2400	0.150s	0.410s	2.110s	3.640s	0.610s	4.530s	129.560s	0.000s
transformers	3537	2901	0.140s	0.440s	2.360s	3.700s	0.890s	9.060s	106.650s	0.000s

[Bill Schnurr (bschnurr)]

Info · Optional note

📍 packages/pyright-internal/src/tests/samples/abstractClass12.py:103

This characterization confirms that overloaded __new__ remains tolerated, while the PR description says it remains reported. Update the PR description to match the verified behavior.

[verified]