Update proposed types

Author: Kartik Raj

src/client/proposedApiTypes.ts

@@ -1,12 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-/* eslint-disable @typescript-eslint/ban-types */
-/* 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 { Event, Uri, WorkspaceFolder } from 'vscode';
 
 // https://github.com/microsoft/vscode-python/wiki/Proposed-Environment-APIs
 
@@ -15,7 +10,7 @@ export interface IProposedExtensionAPI {
         /**
          * This event is triggered when the active environment changes.
          */
-        onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
+        onDidChangeActiveEnvironment: Event<ActiveEnvironmentChangedParams>;
         /**
          * 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
@@ -24,44 +19,41 @@ export interface IProposedExtensionAPI {
          * returns what ever is set for the workspace.
          * @param resource : Uri of a file or workspace
          */
-        getActiveEnvironmentPath(resource?: Resource): Promise<EnvPathType | undefined>;
+        getActiveEnvironmentPath(resource?: Resource): Promise<EnvironmentPath | undefined>;
         /**
-         * Returns details for the given interpreter. Details such as absolute interpreter path,
+         * Returns details for the given python executable. Details such as absolute python executable 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 path : Full path to environment folder or python executable 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,
+            path: EnvironmentPath | UniquePathType,
             options?: EnvironmentDetailsOptions,
         ): Promise<EnvironmentDetails | 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 path : Full path to environment folder or python executable 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>;
+        setActiveEnvironment(path: EnvironmentPath | UniquePathType, resource?: Resource): Promise<void>;
         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>;
+            getEnvironmentPaths(): Promise<EnvironmentPath[] | 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[]>;
+            onDidChangeEnvironments: 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
@@ -70,12 +62,12 @@ export interface IProposedExtensionAPI {
              *     * clearCache : When true, this will clear the cache before environment refresh
              *                    is triggered.
              */
-            refreshEnvironments(options?: RefreshEnvironmentsOptions): Promise<EnvPathType[] | undefined>;
+            refreshEnvironments(options?: RefreshEnvironmentsOptions): Promise<EnvironmentPath[] | undefined>;
             /**
              * Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
              * refreshes going on.
              */
-            getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined;
+            getRefreshPromise(options?: GetRefreshPromiseOptions): 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
@@ -92,26 +84,11 @@ export enum Architecture {
     x64 = 3,
 }
 
-export type EnvSource = KnownEnvSourceTypes | string;
-
-export enum KnownEnvSourceTypes {
-    Conda = 'Conda',
-    Pipenv = 'PipEnv',
-    Poetry = 'Poetry',
-    VirtualEnv = 'VirtualEnv',
-    Venv = 'Venv',
-    VirtualEnvWrapper = 'VirtualEnvWrapper',
-    Pyenv = 'Pyenv',
-}
+export type EnvSource = KnownEnvSources | string;
+export type KnownEnvSources = 'Conda' | 'Pipenv' | 'Poetry' | 'VirtualEnv' | 'Venv' | 'VirtualEnvWrapper' | 'Pyenv';
 
 export type EnvType = KnownEnvTypes | string;
-
-export enum KnownEnvTypes {
-    VirtualEnv = 'VirtualEnv',
-    Conda = 'Conda',
-    Unknown = 'Unknown',
-    Global = 'Global',
-}
+export type KnownEnvTypes = 'VirtualEnv' | 'Conda' | 'Unknown';
 
 export type BasicVersionInfo = {
     major: number;
@@ -141,27 +118,35 @@ export type StandardVersionInfo = BasicVersionInfo & {
     release?: PythonVersionRelease;
 };
 
+// To be added later:
+// run: {
+//     exec: Function;
+//     shellExec: Function;
+//     execObservable: Function;
+//     terminalExec: () => void;
+//     env?: { [key: string]: string | null | undefined };
+// };
+
 export interface EnvironmentDetails {
     executable: {
         path: string;
         bitness?: Architecture;
         sysPrefix: string;
-        // To be added later:
-        // run: {
-        //     exec: Function;
-        //     shellExec: Function;
-        //     execObservable: Function;
-        //     terminalExec: () => void;
-        //     env?: { [key: string]: string | null | undefined };
-        // };
-    };
-    environment?: {
-        type: EnvType;
-        name?: string;
-        path: string;
-        project?: string; // Any specific project environment is created for.
-        source: EnvSource[];
     };
+    environment:
+        | {
+              type: EnvType;
+              name?: string;
+              path: string;
+              /**
+               * Any specific workspace folder this environment is created for.
+               * What if that workspace folder is not opened yet? We should still provide a workspace folder so it can be filtered out.
+               * WorkspaceFolder type won't work as it assumes the workspace is opened, hence using URI.
+               */
+              workspaceFolder?: Uri;
+              source: EnvSource[];
+          }
+        | undefined;
     version: StandardVersionInfo & {
         sysVersion?: string;
     };
@@ -173,10 +158,13 @@ export interface EnvironmentDetails {
 }
 
 export interface EnvironmentDetailsOptions {
+    /**
+     * When true, cache is checked first for any data, returns even if there is partial data.
+     */
     useCache: boolean;
 }
 
-export interface GetRefreshEnvironmentsOptions {
+export interface GetRefreshPromiseOptions {
     /**
      * Get refresh promise which resolves once the following stage has been reached for the list of known environments.
      */
@@ -193,30 +181,55 @@ export type ProgressNotificationEvent = {
     stage: ProgressReportStage;
 };
 
-export type Resource = Uri | undefined;
+/**
+ * Uri of a file inside a workspace or workspace folder itself.
+ */
+export type Resource = Uri | WorkspaceFolder;
 
 /**
- * Path to environment folder or path to interpreter that uniquely identifies an environment.
- * Environments lacking an interpreter are identified by environment folder paths,
- * whereas other envs can be identified using interpreter path.
+ * Path to environment folder or path to python executable that uniquely identifies an environment.
+ * Environments lacking a python executable are identified by environment folder paths,
+ * whereas other envs can be identified using python executable path.
  */
 export type UniquePathType = string;
 
-export interface EnvPathType {
-    path: UniquePathType;
-    pathType: 'envFolderPath' | 'interpreterPath';
+export interface EnvironmentPath {
+    pathID: UniquePathType;
+    /**
+     * Path to python executable that uniquely identifies an environment.
+     * Carries `undefined` if an executable cannot uniquely identify an
+     * environment or does not exist within the env.
+     */
+    executablePath: string | undefined;
 }
 
 export interface EnvironmentsChangedParams {
-    path?: UniquePathType;
+    pathID?: UniquePathType;
+    /**
+     * Types:
+     * * "add": New environment is added.
+     * * "remove": Existing environment in the list is removed.
+     * * "update": New information found about existing environment.
+     * * "clear-all": Remove all of the items in the list. (This is fired when a hard refresh is triggered)
+     */
     type: 'add' | 'remove' | 'update' | 'clear-all';
 }
 
 export interface ActiveEnvironmentChangedParams {
-    path: UniquePathType;
-    resource?: Uri;
+    pathID: UniquePathType;
+    /**
+     * Uri of a file inside a workspace or workspace folder the environment changed for.
+     */
+    resource?: Resource;
 }
 
 export interface RefreshEnvironmentsOptions {
+    /**
+     * When `true`, this will clear the cache before environment refresh is triggered.
+     */
     clearCache?: boolean;
+    /**
+     * Only trigger a refresh if it hasn't already been triggered for this session.
+     */
+    ifNotTriggerredAlready?: boolean;
 }

src/client/pythonEnvironments/base/locator.ts

@@ -146,14 +146,18 @@ interface EnvironmentMetaData {
 }
 
 export interface LocatorEnvsChangedEvent {
-    /**
-     * Any details known about the environment which can be used for query.
-     */
-    env?: EnvironmentMetaData;
     /**
      * Details about how the environment was modified.
      * */
     type: EnvChangeType;
+    /**
+     * The unique ID for the environment affected.
+     */
+    pathId: UniquePathType;
+    /**
+     * Any other details known about the environment which can be used for query.
+     */
+    env?: EnvironmentMetaData;
 }
 
 export type EnvChangeType = 'add' | 'remove' | 'update';

src/client/pythonEnvironments/converter.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-import { EventEmitter, Event } from 'vscode';
+import { EventEmitter, Event, Uri } from 'vscode';
 import { FileChangeType } from '../common/platform/fileSystemWatcher';
 import { traceVerbose } from '../logging';
 import { PythonEnvInfo, PythonEnvKind } from './base/info';
@@ -97,8 +97,11 @@ export class ConvertLocator implements ILocator<BasicEnvInfo> {
     ) {
         if (parentLocator.onChanged) {
             parentLocator.onChanged((e: LocatorEnvsChangedEvent) => {
-                const event: PythonEnvsChangedEvent = { type: this.eventKeys[`${e.type}`] };
-                // TODO: Add translation for other events.
+                const event: PythonEnvsChangedEvent = {
+                    type: this.eventKeys[`${e.type}`],
+                    kind: e.env?.envSources ? convertKind(e.env?.envSources[0]) : undefined,
+                    searchLocation: Uri.file(e.pathId),
+                };
                 this.didChange.fire(event);
             });
         }