Create environment proposed API

src/client/environmentApi.ts

@@ -31,6 +31,7 @@ import {
     ResolvedEnvironment,
     Resource,
 } from './apiTypes';
+import { buildEnvironmentCreationApi } from './pythonEnvironments/creation/createEnvApi';
 
 type ActiveEnvironmentChangeEvent = {
     resource: WorkspaceFolder | undefined;
@@ -253,6 +254,7 @@ export function buildEnvironmentApi(
             sendApiTelemetry('onDidChangeEnvironments');
             return onEnvironmentsChanged.event;
         },
+        ...buildEnvironmentCreationApi(),
     };
     return environmentApi;
 }

src/client/proposedApiTypes.ts

@@ -1,4 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-export interface ProposedExtensionAPI {}
+export interface ProposedExtensionAPI {
+    /**
+     * Top level proposed APIs should go here.
+     */
+}

src/client/pythonEnvironments/creation/createEnvApi.ts

@@ -9,14 +9,15 @@ import { IInterpreterQuickPick } from '../../interpreter/configuration/types';
 import { getCreationEvents, handleCreateEnvironmentCommand } from './createEnvironment';
 import { condaCreationProvider } from './provider/condaCreationProvider';
 import { VenvCreationProvider } from './provider/venvCreationProvider';
+import { showInformationMessage } from '../../common/vscodeApis/windowApis';
+import { CreateEnv } from '../../common/utils/localize';
 import {
-    CreateEnvironmentExitedEventArgs,
-    CreateEnvironmentOptions,
     CreateEnvironmentProvider,
+    CreateEnvironmentOptions,
     CreateEnvironmentResult,
-} from './types';
-import { showInformationMessage } from '../../common/vscodeApis/windowApis';
-import { CreateEnv } from '../../common/utils/localize';
+    ProposedCreateEnvironmentAPI,
+    EnvironmentDidCreateEvent,
+} from './proposed.createEnvApis';
 
 class CreateEnvironmentProviders {
     private _createEnvProviders: CreateEnvironmentProvider[] = [];
@@ -26,6 +27,9 @@ class CreateEnvironmentProviders {
     }
 
     public add(provider: CreateEnvironmentProvider) {
+        if (this._createEnvProviders.filter((p) => p.id === provider.id).length > 0) {
+            throw new Error(`Create Environment provider with id ${provider.id} already registered`);
+        }
         this._createEnvProviders.push(provider);
     }
 
@@ -63,15 +67,36 @@ export function registerCreateEnvironmentFeatures(
                 return handleCreateEnvironmentCommand(providers, options);
             },
         ),
-    );
-    disposables.push(registerCreateEnvironmentProvider(new VenvCreationProvider(interpreterQuickPick)));
-    disposables.push(registerCreateEnvironmentProvider(condaCreationProvider()));
-    disposables.push(
-        onCreateEnvironmentExited(async (e: CreateEnvironmentExitedEventArgs) => {
-            if (e.result?.path && e.options?.selectEnvironment) {
-                await interpreterPathService.update(e.result.uri, ConfigurationTarget.WorkspaceFolder, e.result.path);
-                showInformationMessage(`${CreateEnv.informEnvCreation} ${pathUtils.getDisplayName(e.result.path)}`);
+        registerCreateEnvironmentProvider(new VenvCreationProvider(interpreterQuickPick)),
+        registerCreateEnvironmentProvider(condaCreationProvider()),
+        onCreateEnvironmentExited(async (e: EnvironmentDidCreateEvent) => {
+            if (e.path && e.options?.selectEnvironment) {
+                await interpreterPathService.update(
+                    e.workspaceFolder?.uri,
+                    ConfigurationTarget.WorkspaceFolder,
+                    e.path,
+                );
+                showInformationMessage(`${CreateEnv.informEnvCreation} ${pathUtils.getDisplayName(e.path)}`);
             }
         }),
     );
 }
+
+export function buildEnvironmentCreationApi(): ProposedCreateEnvironmentAPI {
+    return {
+        onWillCreateEnvironment: onCreateEnvironmentStarted,
+        onDidCreateEnvironment: onCreateEnvironmentExited,
+        createEnvironment: async (
+            options?: CreateEnvironmentOptions | undefined,
+        ): Promise<CreateEnvironmentResult | undefined> => {
+            const providers = _createEnvironmentProviders.getAll();
+            try {
+                return await handleCreateEnvironmentCommand(providers, options);
+            } catch (err) {
+                return { path: undefined, workspaceFolder: undefined, action: undefined, error: err as Error };
+            }
+        },
+        registerCreateEnvironmentProvider: (provider: CreateEnvironmentProvider) =>
+            registerCreateEnvironmentProvider(provider),
+    };
+}

src/client/pythonEnvironments/creation/createEnvironment.ts

@@ -11,15 +11,15 @@ import {
 } from '../../common/vscodeApis/windowApis';
 import { traceError, traceVerbose } from '../../logging';
 import {
-    CreateEnvironmentExitedEventArgs,
     CreateEnvironmentOptions,
-    CreateEnvironmentProvider,
     CreateEnvironmentResult,
-    CreateEnvironmentStartedEventArgs,
-} from './types';
+    CreateEnvironmentProvider,
+    EnvironmentWillCreateEvent,
+    EnvironmentDidCreateEvent,
+} from './proposed.createEnvApis';
 
-const onCreateEnvironmentStartedEvent = new EventEmitter<CreateEnvironmentStartedEventArgs>();
-const onCreateEnvironmentExitedEvent = new EventEmitter<CreateEnvironmentExitedEventArgs>();
+const onCreateEnvironmentStartedEvent = new EventEmitter<EnvironmentWillCreateEvent>();
+const onCreateEnvironmentExitedEvent = new EventEmitter<EnvironmentDidCreateEvent>();
 
 let startedEventCount = 0;
 
@@ -32,14 +32,20 @@ function fireStartedEvent(options?: CreateEnvironmentOptions): void {
     startedEventCount += 1;
 }
 
-function fireExitedEvent(result?: CreateEnvironmentResult, options?: CreateEnvironmentOptions, error?: unknown): void {
-    onCreateEnvironmentExitedEvent.fire({ result, options, error });
+function fireExitedEvent(result?: CreateEnvironmentResult, options?: CreateEnvironmentOptions, error?: Error): void {
+    onCreateEnvironmentExitedEvent.fire({
+        options,
+        workspaceFolder: result?.workspaceFolder,
+        path: result?.path,
+        action: result?.action,
+        error: error || result?.error,
+    });
     startedEventCount -= 1;
 }
 
 export function getCreationEvents(): {
-    onCreateEnvironmentStarted: Event<CreateEnvironmentStartedEventArgs>;
-    onCreateEnvironmentExited: Event<CreateEnvironmentExitedEventArgs>;
+    onCreateEnvironmentStarted: Event<EnvironmentWillCreateEvent>;
+    onCreateEnvironmentExited: Event<EnvironmentDidCreateEvent>;
     isCreatingEnvironment: () => boolean;
 } {
     return {
@@ -54,7 +60,7 @@ async function createEnvironment(
     options: CreateEnvironmentOptions,
 ): Promise<CreateEnvironmentResult | undefined> {
     let result: CreateEnvironmentResult | undefined;
-    let err: unknown | undefined;
+    let err: Error | undefined;
     try {
         fireStartedEvent(options);
         result = await provider.createEnvironment(options);
@@ -65,7 +71,7 @@ async function createEnvironment(
                 return undefined;
             }
         }
-        err = ex;
+        err = ex as Error;
         throw err;
     } finally {
         fireExitedEvent(result, options, err);
@@ -185,11 +191,7 @@ export async function handleCreateEnvironmentCommand(
     const action = await MultiStepNode.run(envTypeStep);
     if (options?.showBackButton) {
         if (action === MultiStepAction.Back || action === MultiStepAction.Cancel) {
-            result = {
-                path: result?.path,
-                uri: result?.uri,
-                action: action === MultiStepAction.Back ? 'Back' : 'Cancel',
-            };
+            result = { action, workspaceFolder: undefined, path: undefined, error: undefined };
         }
     }
 

src/client/pythonEnvironments/creation/proposed.createEnvApis.ts

@@ -0,0 +1,143 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License
+
+import { Event, Disposable, WorkspaceFolder } from 'vscode';
+import { EnvironmentTools } from '../../apiTypes';
+
+export type CreateEnvironmentUserActions = 'Back' | 'Cancel';
+export type EnvironmentProviderId = string;
+
+/**
+ * Options used when creating a Python environment.
+ */
+export interface CreateEnvironmentOptions {
+    /**
+     * Default `true`. If `true`, the environment creation handler is expected to install packages.
+     */
+    installPackages?: boolean;
+
+    /**
+     * Default `true`. If `true`, the environment creation provider is expected to add the environment to ignore list
+     * for the source control.
+     */
+    ignoreSourceControl?: boolean;
+
+    /**
+     * Default `false`. If `true` the creation provider should show back button when showing QuickPick or QuickInput.
+     */
+    showBackButton?: boolean;
+
+    /**
+     * Default `true`. If `true`, the environment after creation will be selected.
+     */
+    selectEnvironment?: boolean;
+}
+
+/**
+ * Params passed on `onWillCreateEnvironment` event handler.
+ */
+export interface EnvironmentWillCreateEvent {
+    /**
+     * Options used to create a Python environment.
+     */
+    options: CreateEnvironmentOptions | undefined;
+}
+
+/**
+ * Params passed on `onDidCreateEnvironment` event handler.
+ */
+export interface EnvironmentDidCreateEvent extends CreateEnvironmentResult {
+    /**
+     * Options used to create the Python environment.
+     */
+    options: CreateEnvironmentOptions | undefined;
+}
+
+export interface CreateEnvironmentResult {
+    /**
+     * Workspace folder associated with the environment.
+     */
+    workspaceFolder: WorkspaceFolder | undefined;
+
+    /**
+     * Path to the executable python in the environment
+     */
+    path: string | undefined;
+
+    /**
+     * User action that resulted in exit from the create environment flow.
+     */
+    action: CreateEnvironmentUserActions | undefined;
+
+    /**
+     * Error if any occurred during environment creation.
+     */
+    error: Error | undefined;
+}
+
+/**
+ * Extensions that want to contribute their own environment creation can do that by registering an object
+ * that implements this interface.
+ */
+export interface CreateEnvironmentProvider {
+    /**
+     * This API is called when user selects this provider from a QuickPick to select the type of environment
+     * user wants. This API is expected to show a QuickPick or QuickInput to get the user input and return
+     * the path to the Python executable in the environment.
+     *
+     * @param {CreateEnvironmentOptions} [options] Options used to create a Python environment.
+     *
+     * @returns a promise that resolves to the path to the
+     * Python executable in the environment. Or any action taken by the user, such as back or cancel.
+     */
+    createEnvironment(options?: CreateEnvironmentOptions): Promise<CreateEnvironmentResult | undefined>;
+
+    /**
+     * Unique ID for the creation provider, typically <ExtensionId>:<environment-type | guid>
+     */
+    id: EnvironmentProviderId;
+
+    /**
+     * Display name for the creation provider.
+     */
+    name: string;
+
+    /**
+     * Description displayed to the user in the QuickPick to select environment provider.
+     */
+    description: string;
+
+    /**
+     * Tools used to manage this environment. e.g., ['conda']. In the most to least priority order
+     * for resolving and working with the environment.
+     */
+    tools: EnvironmentTools[];
+}
+
+export interface ProposedCreateEnvironmentAPI {
+    /**
+     * This API can be used to detect when the environment creation starts for any registered
+     * provider (including internal providers). This will also receive any options passed in
+     * or defaults used to create environment.
+     */
+    onWillCreateEnvironment: Event<EnvironmentWillCreateEvent>;
+
+    /**
+     * This API can be used to detect when the environment provider exits for any registered
+     * provider (including internal providers). This will also receive created environment path,
+     * any errors, or user actions taken from the provider.
+     */
+    onDidCreateEnvironment: Event<EnvironmentDidCreateEvent>;
+
+    /**
+     * This API will show a QuickPick to select an environment provider from available list of
+     * providers. Based on the selection the `createEnvironment` will be called on the provider.
+     */
+    createEnvironment(options?: CreateEnvironmentOptions): Promise<CreateEnvironmentResult | undefined>;
+
+    /**
+     * This API should be called to register an environment creation provider. It returns
+     * a (@link Disposable} which can be used to remove the registration.
+     */
+    registerCreateEnvironmentProvider(provider: CreateEnvironmentProvider): Disposable;
+}

src/client/pythonEnvironments/creation/provider/condaCreationProvider.ts

@@ -5,12 +5,7 @@ import { CancellationToken, ProgressLocation, WorkspaceFolder } from 'vscode';
 import * as path from 'path';
 import { Commands, PVSC_EXTENSION_ID } from '../../../common/constants';
 import { traceError, traceLog } from '../../../logging';
-import {
-    CreateEnvironmentOptions,
-    CreateEnvironmentProgress,
-    CreateEnvironmentProvider,
-    CreateEnvironmentResult,
-} from '../types';
+import { CreateEnvironmentProgress } from '../types';
 import { pickWorkspaceFolder } from '../common/workspaceSelection';
 import { execObservable } from '../../../common/process/rawProcessApis';
 import { createDeferred } from '../../../common/utils/async';
@@ -28,6 +23,11 @@ import {
     CONDA_ENV_EXISTING_MARKER,
 } from './condaProgressAndTelemetry';
 import { splitLines } from '../../../common/stringUtils';
+import {
+    CreateEnvironmentOptions,
+    CreateEnvironmentResult,
+    CreateEnvironmentProvider,
+} from '../proposed.createEnvApis';
 
 function generateCommandArgs(version?: string, options?: CreateEnvironmentOptions): string[] {
     let addGitIgnore = true;
@@ -247,7 +247,7 @@ async function createEnvironment(options?: CreateEnvironmentOptions): Promise<Cr
                     showErrorMessageWithLogs(CreateEnv.Conda.errorCreatingEnvironment);
                 }
             }
-            return { path: envPath, uri: workspace?.uri };
+            return { path: envPath, workspaceFolder: workspace, action: undefined, error: undefined };
         },
     );
 }
@@ -260,5 +260,7 @@ export function condaCreationProvider(): CreateEnvironmentProvider {
         description: CreateEnv.Conda.providerDescription,
 
         id: `${PVSC_EXTENSION_ID}:conda`,
+
+        tools: ['Conda'],
     };
 }