Skip to content
Merged
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
145 changes: 145 additions & 0 deletions docs/overloadResultExperiment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
# Bounded local overload results

Supported automatic overload results are enabled by default in `ConfigOptions`
and `Program`, including CLI, language-server and background-worker analysis.
There is no new public project, command-line or editor setting. The internal
`ConfigOptions.experimentalOverloadResults = false` escape hatch retains the
ordinary evaluator for baseline comparisons. Omitted options use the default,
including after configuration serialization, service cloning and reload.

Explicit internal `Program` controller injection takes precedence over the
configuration default, including fixed-seed and test-only checking controls.
Injecting both controller kinds remains an error. Automatic activation does
**not** imply checker live-cache handoff: production configuration supplies
`checkerHandoff: false`, and even an injected automatic controller requires
explicit `checkerHandoff: true` to exercise that separate, unadopted experiment.

This is not full general overload conformance. Within the existing bounded
proof and local-use admission domain, an ambiguous `list[Any]` call can retain
`list[int]` and `list[str]` alternatives. Supported assignments and operations
require one complete successful alternative for the entire operation, not a
combination of partial successes. Public queries display these alternatives as
`OverloadResult[list[int], list[str]]`, not `Any`, `Unknown`, or an ordinary union
that would reject invariant assignments. `OverloadResult` is an internal type
representation, not new Python annotation syntax.

The producer restriction remains direct positional Name calls using supported
function parameters. Nested invariant and nominal generic shapes are supported
only within the existing selector proof domain. Constructors, bound-method
producers, unsupported or escaping use graphs, and unsupported gradual argument
shapes remain ordinary. Concrete calls preserve ordinary precision; admission
or resource cutoffs do not grant more permissive fallback types.

## Automatic activation

Ordinary overload matching first evaluates a real argument/parameter match.
For a complete, successful, unexpanded match at a supported direct assignment
call, the controller checks whether its arguments could contain invariant
`Any`. Concrete calls continue through the ordinary evaluator without module
scanning, candidate operations, reservations or private cache restoration.
Evaluator routing and projection hooks stay disconnected until an admitted
activation installs operation roots. Controller initialization and disposal
still occur, and ordinary checking retains the statement restart boundary.

A potentially ambiguous call runs the existing bounded selector. This probe
is additional real matching work, not a claim that all alternatives have
already been solved. A successful probe queues activation; incomplete or
rejected probes do not install a carrier or an ordinary-result owner.

When a request started outside speculation and return inference, a selected
probe immediately unwinds to that request boundary before activation is
flushed. Continuing the provisional ordinary evaluation could otherwise cache
dependent values or publish false member errors. A top-level baseline operation can
discover an independent producer outside its own node set through native code
flow; it likewise unwinds before retaining the interrupted outcome. Candidate
trials do not discover new producers. A request entered from an already-active
external speculative context still leaves activation pending until a safe
ordinary request.

At a non-speculative, non-inference evaluator checkpoint, the controller runs
the existing bounded module admission graph. It considers all syntactic seeds
when establishing the graph, preserving the existing dependency/escape
decisions and whole-module resource limits. Only records depending on activated,
admitted producers receive operation ownership and reservations.

Activation restarts the enclosing evaluator request, or the enclosing checker
statement when checking is in progress. The checker statement boundary is
necessary to publish assignment and checker diagnostics from the newly owned
operation. No partially evaluated `TypeResult` is promoted to a carrier.
The existing private cache transactions, baseline operations, real alternative
validations and diagnostic publication then perform the work.

The candidate/proof/graph/node limits and actual candidate-call accounting are
unchanged. Active producers still perform the existing charged candidate
discovery operation; the earlier native probe is separately reported through
`activationArgumentChecks`, `activationProbes` and `activationProofUnits`.
Rejected concrete calls no longer perform the old charged discovery operation.

## Ownership and invalidation

`EvaluationOperationController` and `EvaluationCacheIsolation` define the production
evaluator/controller boundary. The evaluator installs isolation and eviction together,
bound to its own lifetime. `useNodeCacheIsolation` restores the exact registered
node-ID entries on ordinary exit, error, or cancellation; explicit successful retention
keeps only non-speculative results. Unowned cache writes survive. Speculative isolation
requires disjoint native roots and never replaces the native speculation stack;
eviction requires no active speculation, and both operations forbid return inference.
The controller separately owns private diagnostic capture and complete-witness
publication, while ordinary unowned diagnostics retain their surrounding native sink.
`testOnlyExpression` and `testOnlyMemberAccess` remain test-only injection options,
not names for these required production guarantees.

Activation state is local to an evaluator/controller and keyed by parse-node
identity. Replacement parse generations do not inherit activations or pending
probes. Disposal clears pending work and retires owned outcomes.

Memory-pressure eviction requested by lazy import lookup is deferred until the
owning Program invocation unwinds. A checker retains one evaluator/controller
for the complete file; analysis releases that ownership between files, not at
the end of the entire project. Language-service requests retain ownership across
nested and asynchronous work. Pending eviction runs when the outermost invocation
finishes, including cancellation or failure, without changing the memory threshold.
Program disposal cancels pending eviction; a late async completion or rejection
must not recreate an evaluator after shutdown or replace the request's outcome.
Each controller's discovery callback is bound to its own evaluator, never a
replacement evaluator's caches. Direct use of a retired controller remains an error.

Ordinary public queries do not become experimental operations merely because
another function in the module activated a producer. Records that already own
ordinary or failed outcomes still require their private restoration and
cache-validity guards; automatic activation does not bypass those guards.

Native overload matching may speculatively query an earlier operation to
determine whether a call returns. Exact-node cache isolation permits this only
when the operation root is disjoint from every active speculative root.
Overlapping roots in either direction remain forbidden, as does isolation in
return inference. The native speculative stack and its undo entries are not
disabled or replaced.

An earlier, unowned statement in the same function can also be evaluated as
a native flow prerequisite of a private operation. Its cache entries survive
exact-node isolation, so its node-associated diagnostics are sent to the
surrounding native sink rather than being discarded with the private trial.
Existing native suppression, reachability and diagnostic deduplication still
apply. Diagnostics within an owned operation remain private until its complete
witness or ordinary fallback is checked.

The regression tests cover analysis-first and cold queries, same-file ordinary
functions, annotated producer diagnostics, cancellation/reentry and resource
cutoffs. The activation-order matrix distinguishes independent `int`/`str` and
`bytes`/`float` producers, their aliases and generic projections, repeated public
queries, and original/edited/restored parse generations. It compares complete
native diagnostics and TypeResult metadata, proves actual carrier selection,
and requires a single complete witness for mixed-element `extend` operations.
Separate tests preserve pending activation across external call speculation and
exercise disjoint/overlapping cache roots under completion, error and cancellation.
Type-server tests request a normally activated carrier over the real in-process
JSON-RPC connection, checking both candidates, nested generic arguments, baseline
references, uncertainty and ordinary concrete-type compatibility. A separate factory
case covers nested Unknown-origin carriers without broadening automatic admission.

Timing is measured separately from observer instrumentation; no timing threshold
is asserted in CI. Earlier V3 residual measurements are historical evidence,
not measurements of subsequent correctness or default-wiring changes. Enabling
the default is not zero-overhead certification; current comparisons must keep
analysis, public-query work and observation counters separate.
3 changes: 2 additions & 1 deletion docs/type-concepts-advanced.md
Original file line number Diff line number Diff line change
Expand Up @@ -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”. The following exceptions apply.
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 3: For supported local assignments with nested invariant `Any` arguments, such as `list[Any]`, Pyright can retain multiple fully known return alternatives. For example, `list[int]` and `list[str]` are displayed as `OverloadResult[list[int], list[str]]`. Each supported operation must succeed for one complete alternative; this is not an ordinary union or `Any`. This behavior is enabled by default within a [bounded local-use and proof domain](overloadResultExperiment.md); unsupported cases retain ordinary behavior.

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.

Expand Down
15 changes: 14 additions & 1 deletion packages/pyright-internal/src/analyzer/checker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,8 @@ export class Checker extends ParseTreeWalker {
private _evaluator: TypeEvaluator,
parseResults: ParserOutput,
private _dependentFiles: ParserOutput[] | undefined,
nodeInfoReader: AnalyzerNodeInfo.AnalyzerNodeInfoReader
nodeInfoReader: AnalyzerNodeInfo.AnalyzerNodeInfoReader,
private _walkOperation?: (node: ParseNode, callback: () => void) => void
) {
// Forward the reader to the base walker so the structural walk expands both tier-1
// (parser-derived) and tier-2 (evaluator-discovered, e.g. `cast("Foo", v)`) string
Expand Down Expand Up @@ -293,6 +294,18 @@ export class Checker extends ParseTreeWalker {
}

override walk(node: ParseNode) {
if (this._walkOperation) {
this._walkOperation(node, () => {
if (!this._nodeInfo.isCodeUnreachable(node)) {
super.walk(node);
} else {
this._evaluator.suppressDiagnostics(node, () => {
super.walk(node);
});
}
});
return;
}
if (!this._nodeInfo.isCodeUnreachable(node)) {
super.walk(node);
} else {
Expand Down
Loading
Loading