Template Sync: Prefer Python Environments extension for interpreter resolution with legacy fallback by edvilme · Pull Request #643 · microsoft/vscode-black-formatter

edvilme · 2026-02-27T23:32:03Z

🔄 Template Sync

This PR syncs changes from the upstream vscode-python-tools-extension-template.

Source PR(s)

Prefer Python Environments extension for interpreter resolution with legacy fallback vscode-python-tools-extension-template#263 — Prefer Python Environments extension for interpreter resolution with legacy fallback

Changes Applied

src/typings/pythonEnvironments.d.ts (new file): Added type definitions for the ms-python.vscode-python-envs extension API (PythonEnvironmentsAPI, PythonEnvironment, DidChangeEnvironmentEventArgs, etc.).
src/common/python.ts: Updated initializePython() and getInterpreterDetails() to prefer the Python Environments extension when available, with a graceful fallback to the legacy ms-python.python extension. Added getEnvironmentsExtensionAPI() helper. The black-formatter-specific helpers (sameInterpreter, checkAndFireEvent, refreshServerPython, checkVersion) are preserved.

⚠️ Review Notes

The Python Environments extension path does not run checkVersion() (unlike the legacy fallback), consistent with the template. If version validation is needed for the new API, it would need to be added separately by parsing the version string field.
Review all changes carefully, especially in files with tool-specific customizations.
Run tests locally before merging.

🤖 This PR was auto-generated by the extension-template-sync workflow.

Copilot

Pull request overview

Syncs upstream template changes to prefer the Python Environments extension (ms-python.vscode-python-envs) for interpreter resolution, with a fallback to the legacy Python extension (ms-python.python).

Changes:

Added typings for the ms-python.vscode-python-envs extension API.
Updated interpreter initialization and resolution to prefer the envs extension, with legacy fallback.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 3 comments.

File	Description
`src/typings/pythonEnvironments.d.ts`	Adds TypeScript typings for the Python Environments extension API used by the client code.
`src/common/python.ts`	Adds envs-extension discovery/activation and uses it for interpreter resolution + change notifications, with legacy fallback.

src/common/python.ts

Copilot

Pull request overview

Copilot reviewed 1 out of 2 changed files in this pull request and generated 2 comments.

src/common/python.ts

rchiodo

Approved via Review Center.

edvilme · 2026-03-02T21:30:18Z

Manual Testing Plan

Setup: Open this repo in VS Code, press F5 to launch the Extension Development Host. Have a Python 3.10+ project open.

All breakpoints are in src/common/python.ts.

Phase 1: Legacy Path (No Envs Extension)

#	Test	Steps	Expected	Breakpoints
1.1	Legacy happy path	Disable/uninstall `ms-python.vscode-python-envs`. Have `ms-python.python` active with a 3.10+ interpreter. Trigger the extension.	Output log: `Waiting for interpreter from Python extension.` Extension works normally.	`python.ts:68` - `getEnvironmentsExtensionAPI` returns `undefined` (envs not found) · `python.ts:142` - `getPythonExtensionAPI()` resolves legacy API · `python.ts:209` - verify `fsPath` is correct interpreter
1.2	Legacy version rejection	Select a Python 3.8 interpreter via `ms-python.python`.	Output log: `Python version 3.8.x is not supported` and `Supported versions are 3.10 and above.`	`python.ts:208` - `checkVersion()` returns `false` · `python.ts:234` - verify version numbers in error
1.3	No Python extension	Disable both `ms-python.python` and `ms-python.vscode-python-envs`.	Extension doesn't crash. No interpreter resolved.	`python.ts:68` - envs returns `undefined` · `python.ts:211` - `{ path: undefined }` returned gracefully

Phase 2: Envs Extension Path

#	Test	Steps	Expected	Breakpoints
2.1	Envs happy path	Install `ms-python.vscode-python-envs` (pre-release). Select a 3.10+ interpreter.	Output log: `Waiting for interpreter from Python environments extension.` Extension works normally.	`python.ts:74` - `extension.exports` has `getEnvironment` method · `python.ts:178` - inspect returned `environment` object · `python.ts:180` - `semver.coerce()` returns valid major/minor/patch · `python.ts:186` - verify `[executable, ...args]` returned
2.2	Envs version rejection	Select a Python 3.8 interpreter via envs extension.	Output log: `Python version 3.8.x is not supported`	`python.ts:180` - inspect `coerced.major`/`coerced.minor` · `python.ts:191` - error logged · `python.ts:194` - `{ path: undefined }` returned
2.3	Envs returns no environment	Open a workspace with no configured environment in the envs extension, but `ms-python.python` has one.	Should fall through to legacy — check logs for no errors, extension still resolves an interpreter.	`python.ts:178` - `getEnvironment()` returns `undefined` · `python.ts:204` - `getPythonExtensionAPI()` called (fallthrough confirmed) · `python.ts:209` - legacy interpreter returned
2.4	Pre-release Python	Select a Python RC/beta (e.g. `3.13.0rc1`) via envs extension.	Accepted if >= 3.10. Not rejected as unparseable.	`python.ts:180` - `semver.coerce("3.13.0rc1")` returns `{ major: 3, minor: 13, patch: 0 }` · `python.ts:186` - valid path returned

Phase 3: Interpreter Switching

#	Test	Steps	Expected	Breakpoints
3.1	Switch interpreters (envs)	With envs extension active, switch from interpreter A to B.	Server restarts. New interpreter used.	`python.ts:131` - `onDidChangeEnvironment` callback fires · `python.ts:112` - `sameInterpreter()` returns `false` · `python.ts:114` - change event fired
3.2	Switch interpreters (legacy)	With only `ms-python.python`, switch interpreters.	Same behavior as before — server restarts with new interpreter.	`python.ts:146` - `onDidChangeActiveEnvironmentPath` callback fires · `python.ts:114` - change event fired

Phase 4: Conda / Wrapper Environments

#	Test	Steps	Expected	Breakpoints
4.1	Conda environment	Create a conda env with Python 3.10+. Select it via envs extension.	Extension resolves correctly. Tool runs.	`python.ts:181` - inspect `activatedRun` (should be populated for conda) · `python.ts:183` - `args` contains conda run args · `python.ts:186` - full `[executable, ...args]` path
4.2	Virtualenv	Select a virtualenv via envs extension.	Extension resolves correctly. Tool runs.	`python.ts:181` - `activatedRun` is `undefined`, falls to `run` · `python.ts:183` - `args` is `[]` · `python.ts:186` - `[executable]` only

Phase 5: Build Verification

#	Test	Steps	Expected	Breakpoints
5.1	Webpack bundle	`npm run compile`	Builds successfully, no errors. `semver` bundles correctly.	N/A
5.2	VSIX package	`npm run vsce-package` (or equivalent)	Produces a valid `.vsix` file.	N/A

Priority: Tests 1.1, 2.1, 2.3, and 5.1 are the most critical.

Quick sanity check: Set breakpoints on just lines 66, 178, 186, 204, and 209 — those 5 lines tell you which path was taken and what was returned.

…esolution Syncs changes from microsoft/vscode-python-tools-extension-template#263. - Add src/typings/pythonEnvironments.d.ts with PythonEnvironmentsAPI type definitions - Update src/common/python.ts to prefer the ms-python.vscode-python-envs extension when available, falling back to the legacy ms-python.python extension The legacy ms-python.python extension API returns incorrect interpreter paths for uv-managed (and other modern) virtual environments. The new Python Environments extension provides a more comprehensive view of available environments. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Use import type for PythonEnvironmentsAPI - Standardize getEnvironmentsExtensionAPI with try/catch and null-exports check - Add version validation for envs API path - Add defensive null checks on execInfo.run.executable - Align comments and log messages across repos - Add TODO comments for unused and unimplemented code Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… helper - Add parsePythonVersion() for robust version string parsing with NaN validation - Add convertToResolvedEnvironment() to convert PythonEnvironment to ResolvedEnvironment - resolveInterpreter now calls envsApi.resolveEnvironment() with type conversion - getInterpreterDetails uses parsePythonVersion instead of inline split/map Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Prefer activatedRun over run in getInterpreterDetails and convertToResolvedEnvironment - Include args array in interpreter path for conda/pyenv shim support - Fall through to legacy ms-python.python when envs API returns no environment - Wrap envs API getEnvironment call in try/catch for resilience Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Versions like '3.13.0rc1' caused Number('0rc1') to return NaN, rejecting valid interpreters. parseInt extracts the leading numeric prefix correctly (e.g. parseInt('0rc1', 10) = 0). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace hand-rolled parseInt parsing with semver.coerce() which robustly handles pre-release versions (e.g. 3.13.0rc1, 3.12.0a4) and edge cases. Added semver as direct dependency and @types/semver as devDependency. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

edvilme requested a review from Copilot February 27, 2026 23:34

Copilot AI reviewed Feb 27, 2026

View reviewed changes

src/common/python.ts Outdated Show resolved Hide resolved

src/common/python.ts Outdated Show resolved Hide resolved

src/common/python.ts Outdated Show resolved Hide resolved

edvilme requested a review from Copilot February 28, 2026 00:24

Copilot started reviewing on behalf of edvilme February 28, 2026 00:24 View session

Copilot AI reviewed Feb 28, 2026

View reviewed changes

src/common/python.ts Outdated Show resolved Hide resolved

src/common/python.ts Show resolved Hide resolved

edvilme added bug Issue identified by VS Code Team member as probable bug debt Technical debt or repo cleanup and removed bug Issue identified by VS Code Team member as probable bug labels Feb 28, 2026

rchiodo approved these changes Mar 2, 2026

View reviewed changes

edvilme mentioned this pull request Mar 2, 2026

Add Python Environments extension support with legacy fallback microsoft/vscode-flake8#414

Merged

GitHub Copilot and others added 9 commits March 2, 2026 13:32

Update src/common/python.ts

b4e2ebf

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update TODO comments for debug API and unused code

dac4db2

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Inline semver.coerce() and remove parsePythonVersion wrapper

c258896

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions bot mentioned this pull request Mar 2, 2026

[agentics] No-Op Runs #638

Closed

edvilme force-pushed the template-sync/pr-263-786c7b39fb6d3348 branch from b21e663 to c258896 Compare March 2, 2026 21:37

bschnurr approved these changes Mar 2, 2026

View reviewed changes

edvilme merged commit 501b182 into main Mar 2, 2026
20 checks passed

edvilme deleted the template-sync/pr-263-786c7b39fb6d3348 branch March 2, 2026 22:30

edvilme mentioned this pull request Mar 4, 2026

Publish API as npm package microsoft/vscode-python-environments#967

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Template Sync: Prefer Python Environments extension for interpreter resolution with legacy fallback#643

Template Sync: Prefer Python Environments extension for interpreter resolution with legacy fallback#643
edvilme merged 9 commits intomainfrom
template-sync/pr-263-786c7b39fb6d3348

edvilme commented Feb 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

rchiodo left a comment

Uh oh!

edvilme commented Mar 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

edvilme commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔄 Template Sync

Source PR(s)

Changes Applied

⚠️ Review Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

rchiodo left a comment

Choose a reason for hiding this comment

Uh oh!

edvilme commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Manual Testing Plan

Phase 1: Legacy Path (No Envs Extension)

Phase 2: Envs Extension Path

Phase 3: Interpreter Switching

Phase 4: Conda / Wrapper Environments

Phase 5: Build Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

edvilme commented Feb 27, 2026 •

edited

Loading

edvilme commented Mar 2, 2026 •

edited

Loading