api.internal.ts

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

import { EventEmitter, Terminal, Uri, Disposable } from 'vscode';
import { getExtension } from '../common/vscodeApis/extensionsApi';
import {
    GetEnvironmentScope,
    PythonBackgroundRunOptions,
    PythonEnvironment,
    PythonEnvironmentApi,
    PythonProcess,
    RefreshEnvironmentsScope,
    DidChangeEnvironmentEventArgs,
} from './types';
import { executeCommand } from '../common/vscodeApis/commandApis';
import { getConfiguration, getWorkspaceFolders } from '../common/vscodeApis/workspaceApis';
import { traceError, traceLog } from '../logging';
import { Interpreters } from '../common/utils/localize';

export const ENVS_EXTENSION_ID = 'ms-python.vscode-python-envs';

export function isEnvExtensionInstalled(): boolean {
    return !!getExtension(ENVS_EXTENSION_ID);
}

/**
 * Returns true if the Python Environments extension is installed and not explicitly
 * disabled by the user. Mirrors the envs extension's own activation logic: it
 * deactivates only when `python.useEnvironmentsExtension` is explicitly set to false
 * at the global, workspace, or workspace-folder level.
 */
export function shouldEnvExtHandleActivation(): boolean {
    if (!isEnvExtensionInstalled()) {
        return false;
    }
    const config = getConfiguration('python');
    const inspection = config.inspect<boolean>('useEnvironmentsExtension');
    if (inspection?.globalValue === false || inspection?.workspaceValue === false) {
        return false;
    }
    // The envs extension also checks folder-scoped settings in multi-root workspaces.
    // Any single folder with the setting set to false causes the envs extension to
    // deactivate entirely (window-wide), so we must mirror that here.
    const workspaceFolders = getWorkspaceFolders();
    if (workspaceFolders) {
        for (const folder of workspaceFolders) {
            const folderConfig = getConfiguration('python', folder.uri);
            const folderInspection = folderConfig.inspect<boolean>('useEnvironmentsExtension');
            if (folderInspection?.workspaceFolderValue === false) {
                return false;
            }
        }
    }
    return true;
}

let _useExt: boolean | undefined;
export function useEnvExtension(): boolean {
    if (_useExt !== undefined) {
        return _useExt;
    }
    const config = getConfiguration('python');
    const inExpSetting = config?.get<boolean>('useEnvironmentsExtension', false) ?? false;
    // If extension is installed and in experiment, then use it.
    _useExt = !!getExtension(ENVS_EXTENSION_ID) && inExpSetting;
    return _useExt;
}

const onDidChangeEnvironmentEnvExtEmitter: EventEmitter<DidChangeEnvironmentEventArgs> = new EventEmitter<
    DidChangeEnvironmentEventArgs
>();
export function onDidChangeEnvironmentEnvExt(
    listener: (e: DidChangeEnvironmentEventArgs) => unknown,
    thisArgs?: unknown,
    disposables?: Disposable[],
): Disposable {
    return onDidChangeEnvironmentEnvExtEmitter.event(listener, thisArgs, disposables);
}

let _extApi: PythonEnvironmentApi | undefined;
export async function getEnvExtApi(): Promise<PythonEnvironmentApi> {
    if (_extApi) {
        return _extApi;
    }
    const extension = getExtension(ENVS_EXTENSION_ID);
    if (!extension) {
        traceError(Interpreters.envExtActivationFailed);
        throw new Error('Python Environments extension not found.');
    }
    if (!extension?.isActive) {
        try {
            await extension.activate();
        } catch (ex) {
            traceError(Interpreters.envExtActivationFailed, ex);
            throw ex;
        }
    }

    traceLog(Interpreters.envExtDiscoveryAttribution);

    _extApi = extension.exports as PythonEnvironmentApi;
    _extApi.onDidChangeEnvironment((e) => {
        onDidChangeEnvironmentEnvExtEmitter.fire(e);
    });

    return _extApi;
}

export async function runInBackground(
    environment: PythonEnvironment,
    options: PythonBackgroundRunOptions,
): Promise<PythonProcess> {
    const envExtApi = await getEnvExtApi();
    return envExtApi.runInBackground(environment, options);
}

export async function getEnvironment(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined> {
    const envExtApi = await getEnvExtApi();
    const env = await envExtApi.getEnvironment(scope);
    if (!env) {
        traceLog(Interpreters.envExtNoActiveEnvironment);
    }
    return env;
}

export async function resolveEnvironment(pythonPath: string): Promise<PythonEnvironment | undefined> {
    const envExtApi = await getEnvExtApi();
    return envExtApi.resolveEnvironment(Uri.file(pythonPath));
}

export async function refreshEnvironments(scope: RefreshEnvironmentsScope): Promise<void> {
    const envExtApi = await getEnvExtApi();
    return envExtApi.refreshEnvironments(scope);
}

export async function runInTerminal(
    resource: Uri | undefined,
    args?: string[],
    cwd?: string | Uri,
    show?: boolean,
): Promise<Terminal> {
    const envExtApi = await getEnvExtApi();
    const env = await getEnvironment(resource);
    const project = resource ? envExtApi.getPythonProject(resource) : undefined;
    if (env && resource) {
        return envExtApi.runInTerminal(env, {
            cwd: cwd ?? project?.uri ?? process.cwd(),
            args,
            show,
        });
    }
    throw new Error('Invalid arguments to run in terminal');
}

export async function runInDedicatedTerminal(
    resource: Uri | undefined,
    args?: string[],
    cwd?: string | Uri,
    show?: boolean,
): Promise<Terminal> {
    const envExtApi = await getEnvExtApi();
    const env = await getEnvironment(resource);
    const project = resource ? envExtApi.getPythonProject(resource) : undefined;
    if (env) {
        return envExtApi.runInDedicatedTerminal(resource ?? 'global', env, {
            cwd: cwd ?? project?.uri ?? process.cwd(),
            args,
            show,
        });
    }
    throw new Error('Invalid arguments to run in dedicated terminal');
}

export async function clearCache(): Promise<void> {
    const envExtApi = await getEnvExtApi();
    if (envExtApi) {
        await executeCommand('python-envs.clearCache');
    }
}