Add support for deprecated API types

Author: Kartik Raj

src/client/deprecatedProposedApi.ts

@@ -0,0 +1,124 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ConfigurationTarget, EventEmitter } from 'vscode';
+import { arePathsSame } from './common/platform/fs-paths';
+import { IInterpreterPathService, Resource } from './common/types';
+import {
+    EnvironmentsChangedParams,
+    ActiveEnvironmentChangedParams,
+    EnvironmentDetailsOptions,
+    EnvironmentDetails,
+    DeprecatedProposedAPI,
+} from './deprecatedProposedApiTypes';
+import { IInterpreterService } from './interpreter/contracts';
+import { IServiceContainer } from './ioc/types';
+import { PythonEnvInfo } from './pythonEnvironments/base/info';
+import { getEnvPath } from './pythonEnvironments/base/info/env';
+import { GetRefreshEnvironmentsOptions, IDiscoveryAPI } from './pythonEnvironments/base/locator';
+
+const onDidInterpretersChangedEvent = new EventEmitter<EnvironmentsChangedParams[]>();
+/**
+ * @deprecated Will be removed soon.
+ */
+export function reportInterpretersChanged(e: EnvironmentsChangedParams[]): void {
+    onDidInterpretersChangedEvent.fire(e);
+}
+
+const onDidActiveInterpreterChangedEvent = new EventEmitter<ActiveEnvironmentChangedParams>();
+/**
+ * @deprecated Will be removed soon.
+ */
+export function reportActiveInterpreterChangedDeprecated(e: ActiveEnvironmentChangedParams): void {
+    onDidActiveInterpreterChangedEvent.fire(e);
+}
+
+function getVersionString(env: PythonEnvInfo): string[] {
+    const ver = [`${env.version.major}`, `${env.version.minor}`, `${env.version.micro}`];
+    if (env.version.release) {
+        ver.push(`${env.version.release}`);
+        if (env.version.sysVersion) {
+            ver.push(`${env.version.release}`);
+        }
+    }
+    return ver;
+}
+
+/**
+ * Returns whether the path provided matches the environment.
+ * @param path Path to environment folder or path to interpreter that uniquely identifies an environment.
+ * @param env Environment to match with.
+ */
+function isEnvSame(path: string, env: PythonEnvInfo) {
+    return arePathsSame(path, env.location) || arePathsSame(path, env.executable.filename);
+}
+
+export function buildDeprecatedProposedApi(
+    discoveryApi: IDiscoveryAPI,
+    serviceContainer: IServiceContainer,
+): DeprecatedProposedAPI {
+    const interpreterPathService = serviceContainer.get<IInterpreterPathService>(IInterpreterPathService);
+    const interpreterService = serviceContainer.get<IInterpreterService>(IInterpreterService);
+
+    const proposed: DeprecatedProposedAPI = {
+        environment: {
+            async getExecutionDetails(resource?: Resource) {
+                const env = await interpreterService.getActiveInterpreter(resource);
+                return env ? { execCommand: [env.path] } : { execCommand: undefined };
+            },
+            async getActiveEnvironmentPath(resource?: Resource) {
+                const env = await interpreterService.getActiveInterpreter(resource);
+                if (!env) {
+                    return undefined;
+                }
+                return getEnvPath(env.path, env.envPath);
+            },
+            async getEnvironmentDetails(
+                path: string,
+                options?: EnvironmentDetailsOptions,
+            ): Promise<EnvironmentDetails | undefined> {
+                let env: PythonEnvInfo | undefined;
+                if (options?.useCache) {
+                    env = discoveryApi.getEnvs().find((v) => isEnvSame(path, v));
+                }
+                if (!env) {
+                    env = await discoveryApi.resolveEnv(path);
+                    if (!env) {
+                        return undefined;
+                    }
+                }
+                return {
+                    interpreterPath: env.executable.filename,
+                    envFolderPath: env.location.length ? env.location : undefined,
+                    version: getVersionString(env),
+                    environmentType: [env.kind],
+                    metadata: {
+                        sysPrefix: env.executable.sysPrefix,
+                        bitness: env.arch,
+                        project: env.searchLocation,
+                    },
+                };
+            },
+            getEnvironmentPaths() {
+                const paths = discoveryApi.getEnvs().map((e) => getEnvPath(e.executable.filename, e.location));
+                return Promise.resolve(paths);
+            },
+            setActiveEnvironment(path: string, resource?: Resource): Promise<void> {
+                return interpreterPathService.update(resource, ConfigurationTarget.WorkspaceFolder, path);
+            },
+            async refreshEnvironment() {
+                await discoveryApi.triggerRefresh();
+                const paths = discoveryApi.getEnvs().map((e) => getEnvPath(e.executable.filename, e.location));
+                return Promise.resolve(paths);
+            },
+            getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined {
+                return discoveryApi.getRefreshPromise(options);
+            },
+            onDidChangeExecutionDetails: interpreterService.onDidChangeInterpreterConfiguration,
+            onDidEnvironmentsChanged: onDidInterpretersChangedEvent.event,
+            onDidActiveEnvironmentChanged: onDidActiveInterpreterChangedEvent.event,
+            onRefreshProgress: discoveryApi.onProgress,
+        },
+    };
+    return proposed;
+}

src/client/deprecatedProposedApiTypes.ts

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Uri, Event } from 'vscode';
+import { ProposedExtensionAPI, Resource } from './proposedApiTypes';
+import { PythonEnvKind, EnvPathType } from './pythonEnvironments/base/info';
+import { ProgressNotificationEvent, GetRefreshEnvironmentsOptions } from './pythonEnvironments/base/locator';
+
+export interface EnvironmentDetailsOptions {
+    useCache: boolean;
+}
+
+export interface EnvironmentDetails {
+    interpreterPath: string;
+    envFolderPath?: string;
+    version: string[];
+    environmentType: PythonEnvKind[];
+    metadata: Record<string, unknown>;
+}
+
+export interface EnvironmentsChangedParams {
+    /**
+     * Path to environment folder or path to interpreter that uniquely identifies an environment.
+     * Virtual environments lacking an interpreter are identified by environment folder paths,
+     * whereas other envs can be identified using interpreter path.
+     */
+    path?: string;
+    type: 'add' | 'remove' | 'update' | 'clear-all';
+}
+
+export interface ActiveEnvironmentChangedParams {
+    /**
+     * Path to environment folder or path to interpreter that uniquely identifies an environment.
+     * Virtual environments lacking an interpreter are identified by environment folder paths,
+     * whereas other envs can be identified using interpreter path.
+     */
+    path: string;
+    resource?: Uri;
+}
+
+/**
+ * @deprecated Use {@link ProposedExtensionAPI} instead.
+ */
+export interface DeprecatedProposedAPI {
+    /**
+     * @deprecated Use {@link ProposedExtensionAPI.environment} instead. This will soon be removed.
+     */
+    environment: {
+        /**
+         * An event that is emitted when execution details (for a resource) change. For instance, when interpreter configuration changes.
+         */
+        readonly onDidChangeExecutionDetails: Event<Uri | undefined>;
+        /**
+         * Returns all the details the consumer needs to execute code within the selected environment,
+         * corresponding to the specified resource taking into account any workspace-specific settings
+         * for the workspace to which this resource belongs.
+         * @param {Resource} [resource] A resource for which the setting is asked for.
+         * * When no resource is provided, the setting scoped to the first workspace folder is returned.
+         * * If no folder is present, it returns the global setting.
+         * @returns {({ execCommand: string[] | undefined })}
+         */
+        getExecutionDetails(
+            resource?: Resource,
+        ): Promise<{
+            /**
+             * E.g of execution commands returned could be,
+             * * `['<path to the interpreter set in settings>']`
+             * * `['<path to the interpreter selected by the extension when setting is not set>']`
+             * * `['conda', 'run', 'python']` which is used to run from within Conda environments.
+             * or something similar for some other Python environments.
+             *
+             * @type {(string[] | undefined)} When return value is `undefined`, it means no interpreter is set.
+             * Otherwise, join the items returned using space to construct the full execution command.
+             */
+            execCommand: string[] | undefined;
+        }>;
+        /**
+         * @deprecated Use {@link getActiveEnvironmentId} instead. This will soon be removed.
+         */
+        getActiveEnvironmentPath(resource?: Resource): Promise<EnvPathType | undefined>;
+        /**
+         * Returns details for the given interpreter. Details such as absolute interpreter path,
+         * version, type (conda, pyenv, etc). Metadata such as `sysPrefix` can be found under
+         * metadata field.
+         * @param path : Full path to environment folder or interpreter whose details you need.
+         * @param options : [optional]
+         *     * useCache : When true, cache is checked first for any data, returns even if there
+         *                  is partial data.
+         */
+        getEnvironmentDetails(
+            path: string,
+            options?: EnvironmentDetailsOptions,
+        ): Promise<EnvironmentDetails | undefined>;
+        /**
+         * Returns paths to environments that uniquely identifies an environment found by the extension
+         * at the time of calling. This API will *not* trigger a refresh. If a refresh is going on it
+         * will *not* wait for the refresh to finish. This will return what is known so far. To get
+         * complete list `await` on promise returned by `getRefreshPromise()`.
+         *
+         * Virtual environments lacking an interpreter are identified by environment folder paths,
+         * whereas other envs can be identified using interpreter path.
+         */
+        getEnvironmentPaths(): Promise<EnvPathType[] | undefined>;
+        /**
+         * Sets the active environment path for the python extension for the resource. Configuration target
+         * will always be the workspace folder.
+         * @param path : Full path to environment folder or interpreter to set.
+         * @param resource : [optional] Uri of a file ro workspace to scope to a particular workspace
+         *                   folder.
+         */
+        setActiveEnvironment(path: string, resource?: Resource): Promise<void>;
+        /**
+         * This API will re-trigger environment discovery. Extensions can wait on the returned
+         * promise to get the updated environment list. If there is a refresh already going on
+         * then it returns the promise for that refresh.
+         * @param options : [optional]
+         *     * clearCache : When true, this will clear the cache before environment refresh
+         *                    is triggered.
+         */
+        refreshEnvironment(): Promise<EnvPathType[] | undefined>;
+        /**
+         * Tracks discovery progress for current list of known environments, i.e when it starts, finishes or any other relevant
+         * stage. Note the progress for a particular query is currently not tracked or reported, this only indicates progress of
+         * the entire collection.
+         */
+        readonly onRefreshProgress: Event<ProgressNotificationEvent>;
+        /**
+         * Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
+         * refreshes going on.
+         */
+        getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined;
+        /**
+         * This event is triggered when the known environment list changes, like when a environment
+         * is found, existing environment is removed, or some details changed on an environment.
+         */
+        onDidEnvironmentsChanged: Event<EnvironmentsChangedParams[]>;
+        /**
+         * @deprecated Use {@link ProposedExtensionAPI.environment} `onDidChangeActiveEnvironmentId` instead. This will soon be removed.
+         */
+        onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
+    };
+}