API for create environment

[karthiknadig]

Propose API for Create Environment and contribution to Create Environment feature.

[karthiknadig]

Proposal

Interfaces

/**
 * 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.
     * Returns: {@link Environment}
     * Exceptions:
     *     CancellationError: Is the user exits creation at any point or cancels creation this should be thrown
     *     Back <TBD>: User clicked on the back button.
     *     CreateEnvironmentError <TBD>:
     */
    createEnvironment(options?: CreateEnvironmentOptions): Promise<Environment | undefined>;

    /**
     * Display name for the creation provider
     */
    name: string;

    /**
     * Description displayed to the user in the QuickPick.
     */
    description: string;
}

/**
 * Options to be used when creating an 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 will be selected as the environment to be used for the workspace.
     */
    selectEnvironment?: boolean;
}

/**
 * Params passed on `onWillCreateEnvironment` event handler.
 */
export interface WillCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;
}

/**
 * Params passed on `onWillCreateEnvironment` event handler.
 */
export interface WillCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;
}

/**
 * Params passed on `onDidCreateEnvironment` event handler.
 */
export interface DidCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;

    /**
     * Reason for event trigger
     */
    reason: 'cancel' | 'back' | 'completed' | 'error';

    /**
     * Created environment
     */
    environment: Environment | undefined;

    /**
     * Error if any occurred during environment creation
     */
    error?: Error;
}

Functions

/**
 * This API should be called to register an environment creation provider. It returns a (@link Disposable} which
 * can be used to remove the registration.
 */
export function registerCreateEnvironmentProvider(provider: CreateEnvironmentProvider): Disposable;

/**
 * This API can be used to detect when environment create starts for any provider.
 */
export onWillCreateEnvironment: Event<WillCreateEnvironmentParams>;

/**
 * This API can be used to detect when environment create completed for any provider.
 */
export onDidCreateEnvironment: Event<DidCreateEnvironmentParams>;

/**
 * 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.
 */
export createEnvironment(options: CreateEnvironmentOptions) : Promise<Environment | undefined>

Alternatives

createEnvironment

/**
 * 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.
     * Returns: {@link Environment}
     */
    createEnvironment(options?: CreateEnvironmentOptions): Promise<Environment | CreateEnvironmentActionOrError>;

    /**
     * Display name for the creation provider
     */
    name: string;

    /**
     * Description displayed to the user in the QuickPick.
     */
    description: string;
}

export interface CreateEnvironmentActionOrError {
    /**
     * User action that resulted in exit from the create environment flow.
     */
    action?: 'cancel' | 'back';

    /**
     * Error if any occurred during environment creation.
     */
    error?: Error;

}

[karrtikr]

@brettcannon Any new labels added currently needs to be added to

vscode-python/.github/workflows/issue-labels.yml

Line 9 in f0253e5

REPO_LABELS: '["area-data science","area-debugging","area-diagnostics","area-editor-*","area-environments","area-formatting","area-intellisense","area-internal","area-linting","area-terminal","area-testing","author-verification-requested","bug","community ask","debt","dependencies","documentation","experimenting","feature-request","good first issue","help wanted","important","info-needed","invalid-testplan-item","investigating","iteration-candidate","iteration-plan","iteration-plan-draft","javascript","linux","macos","meta","needs community feedback","needs PR","needs proposal","needs spike","no-changelog","on-testplan","partner ask","regression","release-plan","reports-wanted","skip package*.json","skip tests","tensorboard","testplan-item","triage-needed","verification-found","verification-needed","verification-steps-needed","verified","windows"]'

otherwise they're removed as unrecognized 😅

Is that workflow still needed? Sorry for the trouble.

[brettcannon]

@karrtikr probably not as we have standardized the labels across VS Code.