Register PEP 723 scripts as exact projects (PEP 723 PR 10/16) by StellaHuang95 · Pull Request #1744 · microsoft/vscode-python-environments

Stella Huang (StellaHuang95) · 2026-08-28T19:03:48Z

Part of #1602 (PEP 723 inline script env support). Design doc: #1601.

Roadmap context

This is PR 10 of 16 in the PEP 723 inline-script roadmap. PRs 7-9 persist, discover, validate, and route per-script environments; this PR gives each configured script an exact project identity that survives restart and can be consumed by per-file integrations.

Phase 3 / integration	PR	Status
	PR 7: per-script persistence	merged (#1697)
	PR 8: activation-time discovery	merged (#1722)
	PR 9: automatic per-script routing	merged (#1729)
	PR 10: exact script project registration	this PR
	PRs 11-12: CodeLens and bulk setup UX	follow-up
	PR 17: Pylance per-file Python path	microsoft/pyrx#9265
	PR 19: Python extension per-file lookup	microsoft/vscode-python#26129

Why this PR

PR 9 can route a saved script to a validated inline environment, but the project manager still identifies the script through its containing workspace project. That prevents the per-file identity from surviving restart consistently and leaves downstream configuration and environment-change consumers without an exact script scope.

The registration also needs an ownership boundary: clearing inline environments must remove entries created by the extension without deleting user-authored project settings.

What this PR does

Registers an exact pythonProjects entry before binding an inline environment.
Stores the normal environment and package manager as the script's fallback rather than replacing them with the inline manager.
Marks extension-managed entries as either:
- created: remove the entry during inline cleanup;
- adopted: remove only the marker and preserve the user's entry.
Ignores the managed fallback entry while a validated inline association is routeable.
Uses that entry normally when the feature is disabled or the association becomes stale.
Rolls back a newly prepared registration if inline association binding fails.
Supports single and batch script selection.
Converts a managed entry into an ordinary user-owned entry when the user explicitly selects a non-inline manager.
Coordinates explicit managed selections with the dedicated clear-cache operation.
Resolves and updates same-named scripts correctly in multi-root workspaces.

Registration and cleanup semantics

Condition	Behavior
No exact project entry exists	Create a marked entry containing the ordinary fallback managers
An exact user entry exists	Temporarily mark it without changing its manager choices
Inline binding fails	Roll back the marker/created entry and any newly added in-memory project
Validated association exists	Route through the inline manager
Association is stale or unavailable	Use the stored fallback manager
User selects a non-inline manager	Update the owning setting and remove the managed marker
Clear Script Environment Cache	Remove created entries; restore adopted entries
Two roots contain the same relative script path	Match using the `workspace` discriminator

Performance and safety

No workspace scan is introduced.
Configuration writes occur only during explicit persisted selection, rollback, manager changes, or dedicated cache cleanup.
Serialization is limited to managed inline-script project mutations; unrelated environment routing and refresh operations are not queued.
User-owned project settings are never deleted by inline cleanup.

User impact

The feature remains behind python-envs.inlineScripts.enabled. Existing users and projects without a managed inline-script entry retain their current manager-selection behavior. After setup, a script has a stable exact project scope across reloads; when inline routing is unavailable, its previous project/workspace environment remains the fallback.

Tests

npm run compile-tests
npm run compile
npm run lint
Focused command, environment-manager, and settings tests: 92 passing
The full unit suite was also run. Six unchanged timing-sensitive inline-manager tests failed only under full-suite load and passed together in an isolated rerun.

Scope and follow-up

This PR does not add the setup CodeLens, bulk setup command, TTL eviction, or public feature enablement. Those remain in PRs 11, 12, and 14. Per-file language-service and debugger integration are handled by the companion cross-repository PRs above.

Rich Chiodo (rchiodo) · 2026-08-28T20:23:43Z

🔒 Automated review in progress — Rich Chiodo (@rchiodo) is auto-reviewing this PR.

Rich Chiodo (rchiodo) · 2026-08-28T21:41:42Z

        if (!project || normalizePath(project.uri.fsPath) !== normalizePath(scope.fsPath)) {
            return undefined;
        }
+        const exactSetting = getExactPythonProjectSetting(this.pm, scope);


Warning · Non-blocking recommendation

This ignores the managed exact-project setting unconditionally, so once inline routing becomes stale or disabled, manager resolution falls through to the workspace default rather than the stored fallback. Only bypass this setting while inline routing is active, and cover a case where the fallback and workspace-default manager IDs differ.

Rich Chiodo (rchiodo) · 2026-08-28T21:41:45Z

+    return workspaceApis.getWorkspaceFile()
+        ? ConfigurationTarget.WorkspaceFolder
+        : ConfigurationTarget.Workspace;
+}


Warning · Non-blocking recommendation

Selecting a target based on whether it contains any entries can miss a matching user project at another target; for example, an unrelated workspace-folder entry causes a matching workspace entry to be shadowed by a new created entry. Search defined targets for the matching project first, then choose a target only when creating a genuinely new entry; cover this mixed-scope case with a stateful test.

Rich Chiodo (rchiodo) · 2026-08-28T21:41:49Z

+        return scopes.some((uri) =>
+            getManagedInlineScriptProjectRegistration(getExactPythonProjectSetting(this.pm, uri)),
+        );
+    }


Warning · Non-blocking recommendation

A non-inline selection issued immediately after an inline selection can bypass this queue because the managed marker is installed asynchronously, allowing invocation order to be lost. Track pending inline scopes synchronously or serialize all persisted exact-script selections, and test by pausing registration before issuing the ordinary selection.

Rich Chiodo (rchiodo) · 2026-08-28T21:41:54Z

Verification: The relevant tests could not be fully run in the isolated environment; this review is not fully verified.

Result: could-not-verify

Summary: Verification could not run because no trusted sandbox image is configured for this repository, and local execution was not authorized. The three focused unit suites were therefore not run. I identified 12 tests added by the PR covering registration, rollback, fallback routing, cleanup, and multi-root behavior. Runtime confidence remains low until the sandbox configuration is available.

Test runs: 4 not run

⚠️ Not run | Clear Script Environment Cache Command Tests | npm run unittest -- --grep "Clear Script Environment Cache Command Tests"
⚠️ Not run | PythonEnvironmentManagers getLastKnownEnvironment | npm run unittest -- --grep "PythonEnvironmentManagers getLastKnownEnvironment"
⚠️ Not run | Setting Helpers - Project Removal | npm run unittest -- --grep "Setting Helpers - Project Removal"
⚠️ Not run | Verification environment preflight | git diff --name-status upstream/main...HEAD && printf '\nnode_modules: ' && if [ -d node_modules ]; then echo present; else echo missing; fi && printf 'compiled tests: ' && if [ -f out/test/features/envManagers.lastKnown.unit.test.js ]; then echo present; else echo missing; fi && printf '\nAdded test declarations:\n' && git diff --unified=0 upstream/main...HEAD -- 'src/test/**/*.ts' | grep '^+.*test(' | sed 's/^+//'

⚠️

Clear Script Environment Cache Command Tests diagnostic output

Container verification could not start: no trusted sandbox image is configured for microsoft/vscode-python-environments.

⚠️

PythonEnvironmentManagers getLastKnownEnvironment diagnostic output

Container verification could not start: no trusted sandbox image is configured for microsoft/vscode-python-environments.

⚠️

Setting Helpers - Project Removal diagnostic output

Container verification could not start: no trusted sandbox image is configured for microsoft/vscode-python-environments.

⚠️

Verification environment preflight diagnostic output

Container verification could not start and local execution was not authorized. No trusted sandbox image is configured for microsoft/vscode-python-environments.

Rich Chiodo (rchiodo)

Approved via Review Center.

Persist extension-managed per-script project entries while preserving ordinary fallback settings and user-owned entries. Coordinate registration, rollback, explicit manager changes, and cache cleanup. Part of microsoft#1602. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update sections 6, 7, 9, and 10 to reflect what was actually built and the in-flight PRs (vscode-python-environments microsoft#1744/microsoft#1745, pyrx #9265, vscode-python #26129): - Q6: dedicated InlineScriptAssociationStore + metadata-identity binding (pending/matched) instead of reusing VenvManager persistence; clarify pythonProjects[] is user-visible registration, not routing. - Q7: TTL runs once per session (runTtlEvictionOnce) and protects entries referenced by a live association (PR microsoft#1745). - Q9: Pylance re-routes via the existing didChangeConfiguration signal (_revalidateOpenRegularFiles / revalidateWorkspaceForFile), so PR 18's dedicated notification is optional; fix persistence/event-source bullets. - Q10: correct the '~10 LOC' estimate to the real exactResource + __pythonIsProgramInterpreter + middleware change; add useEnvExtension gating caveat for Run and Debug. Add a status banner noting the doc was revised post-implementation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

) > Part of [microsoft/vscode-python-environments#1602](microsoft/vscode-python-environments#1602). Design doc: [microsoft/vscode-python-environments#1601](microsoft/vscode-python-environments#1601). ### Roadmap context This is **cross-repository PR 19** in the PEP 723 roadmap. It closes the Python extension's per-file lookup gaps for debugging and Pylance configuration. | Cross-repository integration | PR | Status | |---|---|---| | | Environments PR 7: persisted script associations | merged ([#1697](microsoft/vscode-python-environments#1697)) | | | Environments PR 10: exact script projects | [microsoft/vscode-python-environments#1744](microsoft/vscode-python-environments#1744) | | | PR 17: Pylance per-file Python path lookup | [microsoft/pyrx#9265](microsoft/pyrx#9265) | | | **PR 19: exact Python-file lookup and debugger resolution** | **this PR** | ### Why this PR `IInterpreterService.getActiveInterpreter(resource)` normally shares in-flight, timeout, and last-known state by workspace folder. A file URI can therefore receive the workspace interpreter when a workspace lookup is already running or when exact environment resolution exceeds the timeout. That breaks two per-file consumers: - debugger launch resolution can select the workspace interpreter instead of the launch program's interpreter; - Pylance's file-scoped `workspace/configuration` request can receive a cached workspace interpreter. The exact lookup must also avoid publishing a file interpreter as a workspace-wide interpreter change. ### What this PR does - Adds an internal `exactResource` option to `IInterpreterService`. - Bypasses workspace-keyed in-flight, timeout, and last-known state for exact environment-extension lookups. - Suppresses workspace-level interpreter-change reporting for those silent exact reads. - Resolves debugger programs from: - absolute paths; - `${file}`; - `${workspaceFolder}`; - `${workspaceFolder:name}`. - Prefers the program interpreter and falls back to the normal workspace interpreter only when no exact environment is available. - Reuses the selected interpreter for both legacy `pythonPath` and command-valued `python`. - Applies activation variables when the program interpreter differs from the workspace interpreter. - Uses exact lookup only for `.py`-scoped Pylance configuration requests; workspace-level requests retain the existing cached fast path. ### Lookup semantics | Condition | Behavior | |---|---| | No concrete launch program | Preserve workspace lookup | | Exact program environment exists | Use it for debugger resolution | | Exact program lookup returns no environment | Fall back to workspace interpreter | | Program and workspace interpreters match | Preserve existing terminal activation behavior | | Program interpreter differs | Apply its activation variables | | Pylance requests `python` config for a `.py` URI | Resolve the exact file environment | | Pylance requests workspace-level config | Preserve normal workspace caching | | Exact lookup resolves an environment | Do not publish a false workspace interpreter-change event | ### Performance and safety - The existing fast workspace cache remains unchanged for normal consumers. - Exact lookup is opt-in and used only by debugger program selection and `.py` configuration scopes. - The environments extension's own URI-scoped timeout/last-known behavior remains in effect. - No public Python or environments API is changed. ### User impact Users without a per-file environment retain the same interpreter and debugger behavior. When a Python file has a distinct environment, Pylance configuration and debugger launch consistently use that file's interpreter rather than a workspace-cached value. ### Tests - Prettier check for all changed files - ESLint for all changed files - Focused middleware, resolver, launch, environment-adapter, and interpreter-service tests: **181 passing**, 3 pending - Repository-wide TypeScript compilation currently also reports two existing `TelemetryReporter` import errors in untouched files. - The full unit command was run; its failures were confined to untouched platform/path, terminal activation, activated-environment, and native-finder tests. ### Scope and follow-up This PR does not implement Pylance's open-file rerouting notification. Live movement and reanalysis after a per-file environment change remain in PR 18. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Stella Huang (StellaHuang95) mentioned this pull request Aug 28, 2026

Use exact per-file environments for Python files (PEP 723 PR 19) microsoft/vscode-python#26129

Merged

Stella Huang (StellaHuang95) force-pushed the copilot/pep723-pr10-wave1a branch from 0201157 to 5784941 Compare August 28, 2026 19:09

Stella Huang (StellaHuang95) added the feature-request Request for new features or functionality label Aug 28, 2026

Rich Chiodo (rchiodo) reviewed Aug 28, 2026

View reviewed changes

Rich Chiodo (rchiodo) approved these changes Aug 28, 2026

View reviewed changes

Rich Chiodo (rchiodo) added the review-auto:approved Automated review: no blocking findings (approval posted). label Aug 28, 2026

Stella Huang (StellaHuang95) force-pushed the copilot/pep723-pr10-wave1a branch from 5784941 to d85e383 Compare August 28, 2026 21:43

Stella Huang (StellaHuang95) force-pushed the copilot/pep723-pr10-wave1a branch from d85e383 to ee5d7f0 Compare August 28, 2026 22:15

Stella Huang (StellaHuang95) merged commit 26c78f6 into microsoft:main Aug 31, 2026
44 checks passed

Navigation Menu

Uh oh!

Register PEP 723 scripts as exact projects (PEP 723 PR 10/16) - #1744

Register PEP 723 scripts as exact projects (PEP 723 PR 10/16)#1744
Stella Huang (StellaHuang95) merged 1 commit into
microsoft:mainfrom
StellaHuang95:copilot/pep723-pr10-wave1a

Stella Huang (StellaHuang95) commented Aug 28, 2026 •

edited

Loading

Uh oh!

Rich Chiodo (rchiodo) commented Aug 28, 2026 •

edited

Loading

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Uh oh!

Rich Chiodo (rchiodo) commented Aug 28, 2026

Uh oh!

Rich Chiodo (rchiodo) left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Stella Huang (StellaHuang95) commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Roadmap context

Why this PR

What this PR does

Registration and cleanup semantics

Performance and safety

User impact

Tests

Scope and follow-up

Uh oh!

Rich Chiodo (rchiodo) commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Rich Chiodo (rchiodo) Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Rich Chiodo (rchiodo) commented Aug 28, 2026

Uh oh!

Rich Chiodo (rchiodo) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Stella Huang (StellaHuang95) commented Aug 28, 2026 •

edited

Loading

Rich Chiodo (rchiodo) commented Aug 28, 2026 •

edited

Loading