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

> 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>

Author: StellaHuang95

src/client/activation/languageClientMiddlewareBase.ts

@@ -87,7 +87,19 @@ export class LanguageClientMiddlewareBase implements Middleware {
                     const settingDict: LSPObject & { pythonPath: string; _envPYTHONPATH: string } = settings[
                         i
                     ] as LSPObject & { pythonPath: string; _envPYTHONPATH: string };
-                    settingDict.pythonPath = (await interpreterService.getActiveInterpreter(uri))?.path ?? 'python';
+                    // For a .py file resource, resolve the interpreter for that exact file rather than its
+                    // containing workspace folder, so a per-file environment (such as a PEP 723 inline-script
+                    // environment created for a single script) is honored for the language client hosted by
+                    // this extension. This only diverges from workspace-folder resolution when the Python
+                    // Environments extension is in use; otherwise getActiveInterpreter ignores exactResource.
+                    const exactResource = uri && path.extname(uri.fsPath).toLowerCase() === '.py';
+                    settingDict.pythonPath =
+                        (
+                            await interpreterService.getActiveInterpreter(
+                                uri,
+                                exactResource ? { exactResource: true } : undefined,
+                            )
+                        )?.path ?? 'python';
 
                     const env = await envService.getEnvironmentVariables(uri);
                     const envPYTHONPATH = env.PYTHONPATH;

src/client/debugger/extension/configuration/resolvers/base.ts

@@ -6,12 +6,14 @@
 import { injectable } from 'inversify';
 import * as path from 'path';
 import { CancellationToken, DebugConfiguration, Uri, WorkspaceFolder } from 'vscode';
+import { arePathsSame } from '../../../../common/platform/fs-paths';
 import { IConfigurationService } from '../../../../common/types';
 import { getOSType, OSType } from '../../../../common/utils/platform';
 import {
     getWorkspaceFolder as getVSCodeWorkspaceFolder,
     getWorkspaceFolders,
 } from '../../../../common/vscodeApis/workspaceApis';
+import { useEnvExtension } from '../../../../envExt/api.internal';
 import { IInterpreterService } from '../../../../interpreter/contracts';
 import { AttachRequestArguments, DebugOptions, LaunchRequestArguments, PathMapping } from '../../../types';
 import { PythonPathSource } from '../../types';
@@ -108,9 +110,20 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         if (!debugConfiguration) {
             return;
         }
+        delete debugConfiguration.__pythonIsProgramInterpreter;
+        let selectedInterpreterPromise: ReturnType<IInterpreterService['getActiveInterpreter']> | undefined;
+        const getSelectedInterpreter = () => {
+            if (!selectedInterpreterPromise) {
+                selectedInterpreterPromise = this.getInterpreterForDebugConfiguration(
+                    workspaceFolder,
+                    debugConfiguration,
+                );
+            }
+            return selectedInterpreterPromise;
+        };
         if (debugConfiguration.pythonPath === '${command:python.interpreterPath}' || !debugConfiguration.pythonPath) {
             const interpreterPath =
-                (await this.interpreterService.getActiveInterpreter(workspaceFolder))?.path ??
+                (await getSelectedInterpreter())?.path ??
                 this.configurationService.getSettings(workspaceFolder).pythonPath;
             debugConfiguration.pythonPath = interpreterPath;
         } else {
@@ -124,7 +137,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         if (debugConfiguration.python === '${command:python.interpreterPath}') {
             this.pythonPathSource = PythonPathSource.settingsJson;
             const interpreterPath =
-                (await this.interpreterService.getActiveInterpreter(workspaceFolder))?.path ??
+                (await getSelectedInterpreter())?.path ??
                 this.configurationService.getSettings(workspaceFolder).pythonPath;
             debugConfiguration.python = interpreterPath;
         } else if (debugConfiguration.python === undefined) {
@@ -155,6 +168,63 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         delete debugConfiguration.pythonPath;
     }
 
+    private async getInterpreterForDebugConfiguration(
+        workspaceFolder: Uri | undefined,
+        debugConfiguration: LaunchRequestArguments,
+    ) {
+        // Program-scoped (per-file) interpreter resolution only applies when the environments
+        // extension owns interpreter resolution. Without it, preserve the historical behavior of
+        // resolving the interpreter from the launch workspace folder, so users who are not using
+        // the environments extension (e.g. multi-root debugging of another folder's file) see no
+        // change.
+        if (!useEnvExtension()) {
+            return this.interpreterService.getActiveInterpreter(workspaceFolder);
+        }
+        let configuredProgram = debugConfiguration.program === '${file}' ? getProgram() : debugConfiguration.program;
+        let programWorkspaceFolder = workspaceFolder;
+        if (configuredProgram) {
+            configuredProgram = configuredProgram.replace(/\$\{workspaceFolder:([^}]+)\}/g, (match, name) => {
+                const folder = getWorkspaceFolders()?.find((candidate) => candidate.name === name);
+                if (!folder) {
+                    return match;
+                }
+                programWorkspaceFolder = folder.uri;
+                return folder.uri.fsPath;
+            });
+        }
+        if (configuredProgram && workspaceFolder) {
+            configuredProgram = configuredProgram.replace(/\$\{workspaceFolder\}/g, workspaceFolder.fsPath);
+        }
+        const programUri =
+            typeof configuredProgram === 'string' &&
+            !configuredProgram.includes('${') &&
+            path.isAbsolute(configuredProgram)
+                ? this.getProgramUri(configuredProgram, programWorkspaceFolder)
+                : undefined;
+        if (programUri) {
+            const programInterpreter = await this.interpreterService.getActiveInterpreter(programUri, {
+                exactResource: true,
+            });
+            if (programInterpreter) {
+                const workspaceInterpreter = await this.interpreterService.getActiveInterpreter(workspaceFolder, {
+                    exactResource: true,
+                });
+                if (!workspaceInterpreter || !arePathsSame(programInterpreter.path, workspaceInterpreter.path)) {
+                    debugConfiguration.__pythonIsProgramInterpreter = true;
+                }
+                return programInterpreter;
+            }
+        }
+        return this.interpreterService.getActiveInterpreter(workspaceFolder);
+    }
+
+    private getProgramUri(program: string, workspaceFolder: Uri | undefined): Uri {
+        const fileUri = Uri.file(program);
+        return workspaceFolder && workspaceFolder.scheme !== 'file'
+            ? workspaceFolder.with({ path: fileUri.path })
+            : fileUri;
+    }
+
     protected static debugOption(debugOptions: DebugOptions[], debugOption: DebugOptions): void {
         if (debugOptions.indexOf(debugOption) >= 0) {
             return;

src/client/debugger/extension/configuration/resolvers/launch.ts

@@ -118,7 +118,12 @@ export class LaunchConfigurationResolver extends BaseConfigurationResolver<Launc
             debugConfiguration.envFile = settings.envFile;
         }
         let baseEnvVars: EnvironmentVariables | undefined;
-        if (this.isCustomPythonSet || debugConfiguration.console !== 'integratedTerminal') {
+        const shouldActivateEnvironment =
+            this.isCustomPythonSet ||
+            debugConfiguration.__pythonIsProgramInterpreter ||
+            debugConfiguration.console !== 'integratedTerminal';
+        delete debugConfiguration.__pythonIsProgramInterpreter;
+        if (shouldActivateEnvironment) {
             // We only have the right activated environment present in integrated terminal if no custom Python path
             // is specified. Otherwise, we need to explicitly set the variables.
             baseEnvVars = await this.environmentActivationService.getActivatedEnvironmentVariables(

src/client/debugger/types.ts

@@ -111,6 +111,9 @@ interface IKnownLaunchRequestArguments extends ICommonDebugArguments {
     // and "debugLauncherPython" all at once.
     pythonPath?: string;
 
+    // Whether the selected interpreter came from the program resource rather than the workspace.
+    __pythonIsProgramInterpreter?: boolean;
+
     // Configures automatic code reloading.
     autoReload?: IAutomaticCodeReload;
 

src/client/envExt/api.legacy.ts

@@ -125,7 +125,15 @@ async function resolveActiveInterpreterLegacy(resource?: Uri): Promise<PythonEnv
     return newEnv;
 }
 
-export async function getActiveInterpreterLegacy(resource?: Uri): Promise<PythonEnvironmentLegacy | undefined> {
+export async function getActiveInterpreterLegacy(
+    resource?: Uri,
+    options?: { reportActiveInterpreterChanged?: boolean },
+): Promise<PythonEnvironmentLegacy | undefined> {
+    if (options?.reportActiveInterpreterChanged === false) {
+        const pythonEnv = await getEnvironment(resource);
+        return pythonEnv ? toLegacyType(pythonEnv) : undefined;
+    }
+
     // De-duplicate concurrent resolutions for the same resource. The underlying
     // `getEnvironment` call can block while the environments extension is performing a
     // refresh, so multiple startup callers (e.g. the language server watcher and the

src/client/interpreter/contracts.ts

@@ -72,6 +72,13 @@ export interface ICondaService {
 }
 
 export const IInterpreterService = Symbol('IInterpreterService');
+export interface GetActiveInterpreterOptions {
+    /**
+     * Resolve the exact resource without using workspace-scoped in-flight or last-known state.
+     */
+    exactResource?: boolean;
+}
+
 export interface IInterpreterService {
     triggerRefresh(query?: PythonLocatorQuery, options?: TriggerRefreshOptions): Promise<void>;
     readonly refreshPromise: Promise<void> | undefined;
@@ -90,7 +97,7 @@ export interface IInterpreterService {
      * @deprecated Only exists for old Jupyter integration.
      */
     getAllInterpreters(resource?: Uri): Promise<PythonEnvironment[]>;
-    getActiveInterpreter(resource?: Uri): Promise<PythonEnvironment | undefined>;
+    getActiveInterpreter(resource?: Uri, options?: GetActiveInterpreterOptions): Promise<PythonEnvironment | undefined>;
     getInterpreterDetails(pythonPath: string, resoure?: Uri): Promise<undefined | PythonEnvironment>;
     refresh(resource: Resource): Promise<void>;
     initialize(): void;

src/client/interpreter/interpreterService.ts

@@ -27,6 +27,7 @@ import { PythonEnvironment } from '../pythonEnvironments/info';
 import {
     IActivatedEnvironmentLaunch,
     IComponentAdapter,
+    GetActiveInterpreterOptions,
     IInterpreterDisplay,
     IInterpreterService,
     IInterpreterStatusbarVisibilityFilter,
@@ -253,7 +254,17 @@ export class InterpreterService implements Disposable, IInterpreterService {
         this.didChangeInterpreterInformation.dispose();
     }
 
-    public async getActiveInterpreter(resource?: Uri): Promise<PythonEnvironment | undefined> {
+    public async getActiveInterpreter(
+        resource?: Uri,
+        options?: GetActiveInterpreterOptions,
+    ): Promise<PythonEnvironment | undefined> {
+        if (options?.exactResource && useEnvExtension()) {
+            return getActiveInterpreterLegacy(resource, { reportActiveInterpreterChanged: false }).catch((ex) => {
+                traceError('Failed to get active interpreter', ex);
+                return undefined;
+            });
+        }
+
         const workspaceService = this.serviceContainer.get<IWorkspaceService>(IWorkspaceService);
         const key = workspaceService.getWorkspaceFolderIdentifier(resource);
 

src/test/activation/languageClientMiddlewareBase.unit.test.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+'use strict';
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { CancellationTokenSource, Uri } from 'vscode';
+import { ConfigurationRequest } from 'vscode-languageclient';
+import { LanguageClientMiddlewareBase } from '../../client/activation/languageClientMiddlewareBase';
+import { LanguageServerType } from '../../client/activation/types';
+import { IEnvironmentVariablesProvider } from '../../client/common/variables/types';
+import { IInterpreterService } from '../../client/interpreter/contracts';
+import { IServiceContainer } from '../../client/ioc/types';
+
+suite('LanguageClientMiddlewareBase', () => {
+    test('uses exact interpreter lookup only for Python file configuration scopes', async () => {
+        const getActiveInterpreter = sinon.stub().resolves({ path: '/env/python' });
+        const getEnvironmentVariables = sinon.stub().resolves({});
+        const serviceContainer = ({
+            get: (service: symbol) => {
+                if (service === IInterpreterService) {
+                    return { getActiveInterpreter };
+                }
+                if (service === IEnvironmentVariablesProvider) {
+                    return { getEnvironmentVariables };
+                }
+                throw new Error(`Unexpected service: ${service.toString()}`);
+            },
+        } as unknown) as IServiceContainer;
+        const middleware = new LanguageClientMiddlewareBase(serviceContainer, LanguageServerType.Node, sinon.stub());
+        const next = sinon.stub().resolves([{}, {}]) as ConfigurationRequest.HandlerSignature;
+        const script = Uri.file('/workspace/script.py');
+        const workspace = Uri.file('/workspace');
+        const tokenSource = new CancellationTokenSource();
+
+        const result = await middleware.workspace.configuration(
+            {
+                items: [
+                    { section: 'python', scopeUri: script.toString() },
+                    { section: 'python', scopeUri: workspace.toString() },
+                ],
+            },
+            tokenSource.token,
+            next,
+        );
+
+        expect(result).to.deep.equal([{ pythonPath: '/env/python' }, { pythonPath: '/env/python' }]);
+        expect(getActiveInterpreter.firstCall.args[0].toString()).to.equal(script.toString());
+        expect(getActiveInterpreter.firstCall.args[1]).to.deep.equal({ exactResource: true });
+        expect(getActiveInterpreter.secondCall.args[0].toString()).to.equal(workspace.toString());
+        expect(getActiveInterpreter.secondCall.args[1]).to.equal(undefined);
+        tokenSource.dispose();
+    });
+});