Update

Author: Kartik Raj

src/client/apiTypes.ts

@@ -1,11 +1,17 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 import { Event, Uri } from 'vscode';
 import { Resource } from './common/types';
+import { Architecture } from './common/utils/platform';
 import { IDataViewerDataProvider, IJupyterUriProvider } from './jupyter/types';
-import { EnvPathType, PythonEnvKind } from './pythonEnvironments/base/info';
-import { GetRefreshEnvironmentsOptions, ProgressNotificationEvent } from './pythonEnvironments/base/locator';
+import { EnvPathType } from './pythonEnvironments/base/info';
+import {
+    GetRefreshEnvironmentsOptions,
+    IPythonEnvsIterator,
+    ProgressNotificationEvent,
+} from './pythonEnvironments/base/locator';
 
 /*
  * Do not introduce any breaking changes to this API.
@@ -91,21 +97,55 @@ export interface IExtensionApi {
 
 export interface EnvironmentDetailsOptions {
     useCache: boolean;
+    // noShell?: boolean; // For execution without shell
 }
 
 export interface EnvironmentDetails {
-    interpreterPath: string;
-    envFolderPath?: string;
-    version: string[];
-    environmentType: PythonEnvKind[];
-    metadata: Record<string, unknown>;
+    executable: {
+        path: string;
+        run: string[];
+        env?: any;
+        shell?: boolean;
+        shellCommand?: Record<'cmd' | 'fish' | 'bash' | 'string', { run: string[] }>;
+        bitness?: Architecture;
+        cwd?: string;
+        sysPrefix: string;
+    };
+    environment?: {
+        type: EnvType;
+        name?: string;
+        path: string;
+        project?: string; // Any specific project environment is created for.
+    };
+    version: {
+        major: number;
+        minor: number;
+        micro: number;
+        releaselevel: 'alpha' | 'beta' | 'candidate' | 'final';
+        serial: number;
+        sysVersion?: string;
+    };
+    implementation?: {
+        // `sys.implementation`
+        name: string;
+        version: {
+            major: number;
+            minor: number;
+            micro: number;
+            releaselevel: 'alpha' | 'beta' | 'candidate' | 'final';
+            serial: number;
+        };
+    };
+    environmentSource: EnvSource[];
+    // Are the results specific to the environment (variables, working directory, etc.)?
+    contextSensitive: boolean;
 }
 
 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.
+     * Environments lacking an interpreter are identified by environment folder paths,
+     * whereas other envs can be identified using executable path.
      */
     path?: string;
     type: 'add' | 'remove' | 'update' | 'clear-all';
@@ -114,8 +154,8 @@ export interface EnvironmentsChangedParams {
 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.
+     * Environments lacking an interpreter are identified by environment folder paths,
+     * whereas other envs can be identified using executable path.
      */
     path: string;
     resource?: Uri;
@@ -128,33 +168,13 @@ export interface RefreshEnvironmentsOptions {
 export interface IProposedExtensionAPI {
     environment: {
         /**
-         * An event that is emitted when execution details (for a resource) change. For instance, when interpreter configuration changes.
+         * This event is triggered when the active environment changes.
          */
-        readonly onDidChangeExecutionDetails: Event<Uri | undefined>;
+        onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
         /**
-         * 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 })}
+         * An event that is emitted when execution details (for a resource) change. For instance, when interpreter configuration changes.
          */
-        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;
-        }>;
+        readonly onDidChangeExecutionDetails: Event<Uri | undefined>;
         /**
          * Returns the path to the python binary selected by the user or as in the settings.
          * This is just the path to the python binary, this does not provide activation or any
@@ -177,16 +197,6 @@ export interface IProposedExtensionAPI {
             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.
@@ -195,34 +205,100 @@ export interface IProposedExtensionAPI {
          *                   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(options?: RefreshEnvironmentsOptions): 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[]>;
-        /**
-         * This event is triggered when the active environment changes.
-         */
-        onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
+        locator: {
+            /**
+             * 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()`.
+             *
+             * Environments lacking an interpreter are identified by environment folder paths,
+             * whereas other envs can be identified using executable path.
+             */
+            getEnvironmentPaths(): Promise<EnvPathType[] | 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[]>;
+            /**
+             * 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(options?: RefreshEnvironmentsOptions): Promise<EnvPathType[] | undefined>;
+            /**
+             * Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
+             * refreshes going on.
+             */
+            getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | 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>;
+        };
+        registerEnvironmentProvider(
+            environmentProvider: IEnvironmentProvider,
+            metadata: EnvironmentProviderMetadata,
+        ): Promise<void>;
     };
 }
+
+export type EnvInfo = {
+    envSources: EnvSource;
+    executablePath: string;
+    envPath?: string;
+};
+
+interface IEnvironmentProvider {
+    locator: ILocatorAPI;
+    getEnvironmentDetails: (env: EnvInfo) => Promise<EnvironmentDetails | undefined>;
+}
+
+export interface ILocatorAPI {
+    iterEnvs?(): IPythonEnvsIterator<EnvInfo>;
+    readonly onChanged?: Event<LocatorEnvsChangedEvent>;
+}
+
+/**
+ * These can be used when querying for a particular env.
+ */
+interface EnvironmentProviderMetadata {
+    readonly envType: EnvType;
+    readonly searchLocation?: string;
+    readonly envSources: EnvSource[];
+}
+
+export interface LocatorEnvsChangedEvent {
+    /**
+     * Any details known about the environment which can be used for query.
+     */
+    env?: EnvironmentProviderMetadata;
+    type: EnvChangeType;
+}
+
+export type EnvChangeType = 'add' | 'remove' | 'update';
+
+export enum EnvType {
+    VirtualEnv = 'VirtualEnv',
+    Conda = 'Conda',
+    Unknown = 'Unknown',
+    Global = 'GlobalInterpreter',
+}
+
+export enum EnvSource {
+    Conda = 'Conda',
+    Pipenv = 'PipEnv',
+    Poetry = 'Poetry',
+    VirtualEnv = 'VirtualEnv',
+    Venv = 'Venv',
+    VirtualEnvWrapper = 'VirtualEnvWrapper',
+    WindowsStore = 'WindowsStore',
+    Pyenv = 'Pyenv',
+    Custom = 'Custom',
+}