Use exact per-file environments for Python files

Resolve debugger programs and Pylance Python-file configuration against the exact file resource without publishing false workspace interpreter changes. Preserve workspace fallback and activate differing program environments.

Part of microsoft/vscode-python-environments#1602.

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

Author: StellaHuang95

src/client/activation/languageClientMiddlewareBase.ts

@@ -87,7 +87,14 @@ 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';
+                    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,6 +6,7 @@
 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 {
@@ -108,9 +109,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 +136,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 +167,55 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         delete debugConfiguration.pythonPath;
     }
 
+    private async getInterpreterForDebugConfiguration(
+        workspaceFolder: Uri | undefined,
+        debugConfiguration: LaunchRequestArguments,
+    ) {
+        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();
+    });
+});

src/test/debugger/extension/configuration/resolvers/base.unit.test.ts

@@ -7,7 +7,7 @@
 import { expect } from 'chai';
 import * as path from 'path';
 import * as sinon from 'sinon';
-import { anything, instance, mock, when } from 'ts-mockito';
+import { anything, capture, instance, mock, verify, when } from 'ts-mockito';
 import { DebugConfiguration, Uri, WorkspaceFolder } from 'vscode';
 import { CancellationToken } from 'vscode-jsonrpc';
 import { ConfigurationService } from '../../../../../client/common/configuration/service';
@@ -289,6 +289,91 @@ suite('Debugging - Config Resolver', () => {
         expect(config).to.have.property('debugLauncherPython', pythonPath);
     });
 
+    test('uses one exact program lookup for command-valued pythonPath and python', async () => {
+        const workspaceUri = Uri.file(path.resolve('workspace'));
+        const programPath = path.join(workspaceUri.fsPath, 'script.py');
+        const workspacePython = path.resolve('workspace-env', 'python');
+        const programPython = path.resolve('program-env', 'python');
+        const config = {
+            program: path.join('${workspaceFolder}', 'script.py'),
+            pythonPath: '${command:python.interpreterPath}',
+            python: '${command:python.interpreterPath}',
+        };
+        when(interpreterService.getActiveInterpreter(anything(), anything())).thenCall(async (resource) =>
+            resource?.fsPath === Uri.file(programPath).fsPath
+                ? ({ path: programPython } as PythonEnvironment)
+                : ({ path: workspacePython } as PythonEnvironment),
+        );
+
+        await resolver.resolveAndUpdatePythonPath(workspaceUri, config as LaunchRequestArguments);
+
+        expect(config).to.not.have.property('pythonPath');
+        expect(config).to.have.property('python', programPython);
+        expect(config).to.have.property('__pythonIsProgramInterpreter', true);
+        verify(interpreterService.getActiveInterpreter(anything(), anything())).twice();
+        verify(interpreterService.getActiveInterpreter(anything())).never();
+        const [resource, options] = capture(interpreterService.getActiveInterpreter).first();
+        expect(resource?.fsPath).to.equal(Uri.file(programPath).fsPath);
+        expect(options).to.deep.equal({ exactResource: true });
+    });
+
+    test('falls back to the workspace interpreter when exact program lookup has no environment', async () => {
+        const workspaceUri = Uri.file(path.resolve('workspace'));
+        const programPath = path.join(workspaceUri.fsPath, 'script.py');
+        const workspacePython = path.resolve('workspace-env', 'python');
+        const config = { program: programPath };
+        when(interpreterService.getActiveInterpreter(anything(), anything())).thenResolve(undefined);
+        when(interpreterService.getActiveInterpreter(anything())).thenResolve({
+            path: workspacePython,
+        } as PythonEnvironment);
+
+        await resolver.resolveAndUpdatePythonPath(workspaceUri, config as LaunchRequestArguments);
+
+        expect(config).to.have.property('python', workspacePython);
+        expect(config).to.not.have.property('__pythonIsProgramInterpreter');
+        verify(interpreterService.getActiveInterpreter(anything(), anything())).once();
+        verify(interpreterService.getActiveInterpreter(anything())).once();
+    });
+
+    test('resolves a named workspace-folder program before exact interpreter lookup', async () => {
+        const launchWorkspaceUri = Uri.file(path.resolve('workspace-a'));
+        const programWorkspaceUri = Uri.file(path.resolve('workspace-b'));
+        const programPath = path.join(programWorkspaceUri.fsPath, 'script.py');
+        const workspacePython = path.resolve('workspace-env', 'python');
+        const programPython = path.resolve('program-env', 'python');
+        const config = { program: path.join('${workspaceFolder:program-root}', 'script.py') };
+        getWorkspaceFoldersStub.returns([
+            { uri: launchWorkspaceUri, name: 'launch-root', index: 0 },
+            { uri: programWorkspaceUri, name: 'program-root', index: 1 },
+        ]);
+        when(interpreterService.getActiveInterpreter(anything(), anything())).thenCall(async (resource) =>
+            resource?.fsPath === Uri.file(programPath).fsPath
+                ? ({ path: programPython } as PythonEnvironment)
+                : ({ path: workspacePython } as PythonEnvironment),
+        );
+
+        await resolver.resolveAndUpdatePythonPath(launchWorkspaceUri, config as LaunchRequestArguments);
+
+        expect(config).to.have.property('python', programPython);
+        const [resource] = capture(interpreterService.getActiveInterpreter).first();
+        expect(resource?.fsPath).to.equal(Uri.file(programPath).fsPath);
+    });
+
+    test('does not mark a program interpreter that matches the workspace interpreter', async () => {
+        const workspaceUri = Uri.file(path.resolve('workspace'));
+        const programPath = path.join(workspaceUri.fsPath, 'script.py');
+        const pythonPath = path.resolve('env', 'python');
+        const config = { program: programPath };
+        when(interpreterService.getActiveInterpreter(anything(), anything())).thenResolve({
+            path: pythonPath,
+        } as PythonEnvironment);
+
+        await resolver.resolveAndUpdatePythonPath(workspaceUri, config as LaunchRequestArguments);
+
+        expect(config).to.have.property('python', pythonPath);
+        expect(config).to.not.have.property('__pythonIsProgramInterpreter');
+    });
+
     const localHostTestMatrix: Record<string, boolean> = {
         localhost: true,
         '127.0.0.1': true,