@vscode/python-environments 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @vscode/python-environments
+
+This package provides type declarations and a helper to access the API exposed by the [Python Environments](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-python-envs) extension for VS Code.
+
+## Usage
+
+1. Install the package and add an `extensionDependencies` entry in your extension's `package.json`:
+
+```jsonc
+// package.json
+{
+    "extensionDependencies": ["ms-python.vscode-python-envs"]
+}
+```
+
+2. Install the npm package:
+
+```
+npm install @vscode/python-environments
+```
+
+3. Import and use the API in your extension:
+
+```typescript
+import { PythonEnvironments } from '@vscode/python-environments';
+
+export async function activate() {
+    const api = await PythonEnvironments.api();
+
+    // Get all discovered environments
+    const envs = await api.getEnvironments('all');
+    for (const env of envs) {
+        console.log(env.displayName, env.version);
+    }
+}
+```
+

package/SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.3 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's [Microsoft's definition of a security vulnerability](<https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)>) of a security vulnerability, please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
+
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+-   Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+-   Full paths of source file(s) related to the manifestation of the issue
+-   The location of the affected source code (tag/branch/commit or direct URL)
+-   Any special configuration required to reproduce the issue
+-   Step-by-step instructions to reproduce the issue
+-   Proof-of-concept or exploit code (if possible)
+-   Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

package/out/main.d.ts

@@ -0,0 +1,1152 @@
+import { Disposable, Event, FileChangeType, LogOutputChannel, MarkdownString, TaskExecution, Terminal, TerminalOptions, ThemeIcon, Uri } from 'vscode';
+/**
+ * The path to an icon, or a theme-specific configuration of icons.
+ */
+export type IconPath = Uri | {
+    /**
+     * The icon path for the light theme.
+     */
+    light: Uri;
+    /**
+     * The icon path for the dark theme.
+     */
+    dark: Uri;
+} | ThemeIcon;
+/**
+ * Options for executing a Python executable.
+ */
+export interface PythonCommandRunConfiguration {
+    /**
+     * Path to the binary like `python.exe` or `python3` to execute. This should be an absolute path
+     * to an executable that can be spawned.
+     */
+    executable: string;
+    /**
+     * Arguments to pass to the python executable. These arguments will be passed on all execute calls.
+     * This is intended for cases where you might want to do interpreter specific flags.
+     */
+    args?: string[];
+}
+/**
+ * Contains details on how to use a particular python environment
+ *
+ * Running In Terminal:
+ * 1. If {@link PythonEnvironmentExecutionInfo.activatedRun} is provided, then that will be used.
+ * 2. If {@link PythonEnvironmentExecutionInfo.activatedRun} is not provided, then:
+ *   - If {@link PythonEnvironmentExecutionInfo.shellActivation} is provided and shell type is known, then that will be used.
+ *   - If {@link PythonEnvironmentExecutionInfo.shellActivation} is provided and shell type is not known, then:
+ *     - 'unknown' will be used if provided.
+ *     - {@link PythonEnvironmentExecutionInfo.activation} will be used otherwise.
+ *   - If {@link PythonEnvironmentExecutionInfo.shellActivation} is not provided, then {@link PythonEnvironmentExecutionInfo.activation} will be used.
+ *   - If {@link PythonEnvironmentExecutionInfo.activation} is not provided, then {@link PythonEnvironmentExecutionInfo.run} will be used.
+ *
+ * Creating a Terminal:
+ * 1. If {@link PythonEnvironmentExecutionInfo.shellActivation} is provided and shell type is known, then that will be used.
+ * 2. If {@link PythonEnvironmentExecutionInfo.shellActivation} is provided and shell type is not known, then {@link PythonEnvironmentExecutionInfo.activation} will be used.
+ * 3. If {@link PythonEnvironmentExecutionInfo.shellActivation} is not provided, then:
+ *     - 'unknown' will be used if provided.
+ *     - {@link PythonEnvironmentExecutionInfo.activation} will be used otherwise.
+ * 4. If {@link PythonEnvironmentExecutionInfo.activation} is not provided, then {@link PythonEnvironmentExecutionInfo.run} will be used.
+ *
+ */
+export interface PythonEnvironmentExecutionInfo {
+    /**
+     * Details on how to run the python executable.
+     */
+    run: PythonCommandRunConfiguration;
+    /**
+     * Details on how to run the python executable after activating the environment.
+     * If set this will overrides the {@link PythonEnvironmentExecutionInfo.run} command.
+     */
+    activatedRun?: PythonCommandRunConfiguration;
+    /**
+     * Details on how to activate an environment.
+     */
+    activation?: PythonCommandRunConfiguration[];
+    /**
+     * Details on how to activate an environment using a shell specific command.
+     * If set this will override the {@link PythonEnvironmentExecutionInfo.activation}.
+     * 'unknown' is used if shell type is not known.
+     * If 'unknown' is not provided and shell type is not known then
+     * {@link PythonEnvironmentExecutionInfo.activation} if set.
+     */
+    shellActivation?: Map<string, PythonCommandRunConfiguration[]>;
+    /**
+     * Details on how to deactivate an environment.
+     */
+    deactivation?: PythonCommandRunConfiguration[];
+    /**
+     * Details on how to deactivate an environment using a shell specific command.
+     * If set this will override the {@link PythonEnvironmentExecutionInfo.deactivation} property.
+     * 'unknown' is used if shell type is not known.
+     * If 'unknown' is not provided and shell type is not known then
+     * {@link PythonEnvironmentExecutionInfo.deactivation} if set.
+     */
+    shellDeactivation?: Map<string, PythonCommandRunConfiguration[]>;
+}
+/**
+ * Interface representing the ID of a Python environment.
+ */
+export interface PythonEnvironmentId {
+    /**
+     * The unique identifier of the Python environment.
+     */
+    id: string;
+    /**
+     * The ID of the manager responsible for the Python environment.
+     */
+    managerId: string;
+}
+/**
+ * Display information for an environment group.
+ */
+export interface EnvironmentGroupInfo {
+    /**
+     * The name of the environment group. This is used as an identifier for the group.
+     *
+     * Note: The first instance of the group with the given name will be used in the UI.
+     */
+    readonly name: string;
+    /**
+     * The description of the environment group.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the environment group, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString;
+    /**
+     * The icon path for the environment group, which can be a string, Uri, or an object with light and dark theme paths.
+     */
+    readonly iconPath?: IconPath;
+}
+/**
+ * Interface representing information about a Python environment.
+ */
+export interface PythonEnvironmentInfo {
+    /**
+     * The name of the Python environment.
+     */
+    readonly name: string;
+    /**
+     * The display name of the Python environment.
+     */
+    readonly displayName: string;
+    /**
+     * The short display name of the Python environment.
+     */
+    readonly shortDisplayName?: string;
+    /**
+     * The display path of the Python environment.
+     */
+    readonly displayPath: string;
+    /**
+     * The version of the Python environment.
+     */
+    readonly version: string;
+    /**
+     * Path to the python binary or environment folder.
+     */
+    readonly environmentPath: Uri;
+    /**
+     * The description of the Python environment.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the Python environment, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString;
+    /**
+     * The icon path for the Python environment, which can be a string, Uri, or an object with light and dark theme paths.
+     */
+    readonly iconPath?: IconPath;
+    /**
+     * Information on how to execute the Python environment. This is required for executing Python code in the environment.
+     */
+    readonly execInfo: PythonEnvironmentExecutionInfo;
+    /**
+     * `sys.prefix` is the path to the base directory of the Python installation. Typically obtained by executing `sys.prefix` in the Python interpreter.
+     * This is required by extension like Jupyter, Pylance, and other extensions to provide better experience with python.
+     */
+    readonly sysPrefix: string;
+    /**
+     * Optional `group` for this environment. This is used to group environments in the Environment Manager UI.
+     */
+    readonly group?: string | EnvironmentGroupInfo;
+    /**
+     * Error message if the environment is broken or invalid.
+     * When set, indicates this environment has issues (e.g., broken symlinks, missing Python executable).
+     * The UI should display a warning indicator and show this message to help users diagnose and fix the issue.
+     */
+    readonly error?: string;
+}
+/**
+ * Interface representing a Python environment.
+ */
+export interface PythonEnvironment extends PythonEnvironmentInfo {
+    /**
+     * The ID of the Python environment.
+     */
+    readonly envId: PythonEnvironmentId;
+}
+/**
+ * Type representing the scope for setting a Python environment.
+ * Can be undefined or a URI.
+ */
+export type SetEnvironmentScope = undefined | Uri | Uri[];
+/**
+ * Type representing the scope for getting a Python environment.
+ * Can be undefined or a URI.
+ */
+export type GetEnvironmentScope = undefined | Uri;
+/**
+ * Type representing the scope for creating a Python environment.
+ * Can be a Python project or 'global'.
+ */
+export type CreateEnvironmentScope = Uri | Uri[] | 'global';
+/**
+ * The scope for which environments are to be refreshed.
+ * - `undefined`: Search for environments globally and workspaces.
+ * - {@link Uri}: Environments in the workspace/folder or associated with the Uri.
+ */
+export type RefreshEnvironmentsScope = Uri | undefined;
+/**
+ * The scope for which environments are required.
+ * - `"all"`: All environments.
+ * - `"global"`: Python installations that are usually a base for creating virtual environments.
+ * - {@link Uri}: Environments for the workspace/folder/file pointed to by the Uri.
+ */
+export type GetEnvironmentsScope = Uri | 'all' | 'global';
+/**
+ * Event arguments for when the current Python environment changes.
+ */
+export type DidChangeEnvironmentEventArgs = {
+    /**
+     * The URI of the environment that changed.
+     */
+    readonly uri: Uri | undefined;
+    /**
+     * The old Python environment before the change.
+     */
+    readonly old: PythonEnvironment | undefined;
+    /**
+     * The new Python environment after the change.
+     */
+    readonly new: PythonEnvironment | undefined;
+};
+/**
+ * Enum representing the kinds of environment changes.
+ */
+export declare enum EnvironmentChangeKind {
+    /**
+     * Indicates that an environment was added.
+     */
+    add = "add",
+    /**
+     * Indicates that an environment was removed.
+     */
+    remove = "remove"
+}
+/**
+ * Event arguments for when the list of Python environments changes.
+ */
+export type DidChangeEnvironmentsEventArgs = {
+    /**
+     * The kind of change that occurred (add or remove).
+     */
+    kind: EnvironmentChangeKind;
+    /**
+     * The Python environment that was added or removed.
+     */
+    environment: PythonEnvironment;
+}[];
+/**
+ * Type representing the context for resolving a Python environment.
+ */
+export type ResolveEnvironmentContext = Uri;
+export interface QuickCreateConfig {
+    /**
+     * The description of the quick create step.
+     */
+    readonly description: string;
+    /**
+     * The detail of the quick create step.
+     */
+    readonly detail?: string;
+}
+/**
+ * Interface representing an environment manager.
+ *
+ * @remarks
+ * Methods on this interface are invoked both by the Python Environments extension itself
+ * (in response to UI actions, startup, terminal activation, script execution, and so on)
+ * and directly by other extensions that consume the published API. Any "called when…"
+ * notes on individual methods list representative triggers only — they are not
+ * exhaustive, and the precise set of call sites may evolve over time. Implementations
+ * should focus on the documented contract rather than any specific caller.
+ */
+export interface EnvironmentManager {
+    /**
+     * The name of the environment manager. Allowed characters (a-z, A-Z, 0-9, -, _).
+     */
+    readonly name: string;
+    /**
+     * The display name of the environment manager.
+     */
+    readonly displayName?: string;
+    /**
+     * The preferred package manager ID for the environment manager. This is a combination
+     * of publisher id, extension id, and {@link EnvironmentManager.name package manager name}.
+     * `<publisher-id>.<extension-id>:<package-manager-name>`
+     *
+     * @example
+     * 'ms-python.python:pip'
+     */
+    readonly preferredPackageManagerId: string;
+    /**
+     * The description of the environment manager.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the environment manager, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString | undefined;
+    /**
+     * The icon path for the environment manager, which can be a string, Uri, or an object with light and dark theme paths.
+     */
+    readonly iconPath?: IconPath;
+    /**
+     * The log output channel for the environment manager.
+     */
+    readonly log?: LogOutputChannel;
+    /**
+     * The quick create details for the environment manager. Having this method also enables the quick create feature
+     * for the environment manager. Should Implement {@link EnvironmentManager.create} to support quick create.
+     */
+    quickCreateConfig?(): QuickCreateConfig | undefined;
+    /**
+     * Creates a new Python environment within the specified scope. Create should support adding a .gitignore file if it creates a folder within the workspace. If a manager does not support environment creation, do not implement this method; the UI disables "create" options when `this.manager.create === undefined`.
+     * @param scope - The scope within which to create the environment.
+     * @param options - Optional parameters for creating the Python environment.
+     * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
+     *
+     * @remarks
+     * Invoked when an environment of this manager's type should be created for the given
+     * scope. Typical triggers include user-initiated environment-creation flows and
+     * programmatic creation via the API.
+     */
+    create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
+    /**
+     * Removes the specified Python environment.
+     * @param environment - The Python environment to remove.
+     * @returns A promise that resolves when the environment is removed.
+     *
+     * @remarks
+     * Invoked to delete the given environment. Typical triggers include an explicit user
+     * action (such as a "Delete Environment" command) and programmatic removal via the API.
+     */
+    remove?(environment: PythonEnvironment): Promise<void>;
+    /**
+     * Refreshes the list of Python environments within the specified scope.
+     * @param scope - The scope within which to refresh environments.
+     * @returns A promise that resolves when the refresh is complete.
+     *
+     * @remarks
+     * Forces the manager to re-discover environments for the given scope. Typically
+     * triggered by an explicit user "refresh" action.
+     */
+    refresh(scope: RefreshEnvironmentsScope): Promise<void>;
+    /**
+     * Retrieves a list of Python environments within the specified scope.
+     * @param scope - The scope within which to retrieve environments.
+     * @returns A promise that resolves to an array of Python environments.
+     *
+     * @remarks
+     * Returns the environments known to this manager for the given scope. Called
+     * frequently by UI surfaces (tree views, pickers) and by other consumers of the API.
+     */
+    getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
+    /**
+     * Event that is fired when the list of Python environments changes.
+     */
+    onDidChangeEnvironments?: Event<DidChangeEnvironmentsEventArgs>;
+    /**
+     * Sets the current Python environment within the specified scope.
+     * @param scope - The scope within which to set the environment.
+     * @param environment - The Python environment to set. If undefined, the environment is unset.
+     * @returns A promise that resolves when the environment is set.
+     *
+     * @remarks
+     * Invoked when the active environment for the given scope should change — for example
+     * after the user selects an environment in a picker, after a newly created environment
+     * is auto-selected, or programmatically via the API.
+     *
+     * Also invoked at extension startup to rehydrate the active environment from
+     * persisted state.
+     */
+    set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
+    /**
+     * Retrieves the current Python environment within the specified scope.
+     * @param scope - The scope within which to retrieve the environment.
+     * @returns A promise that resolves to the current Python environment, or undefined if none is set.
+     *
+     * @remarks
+     * Returns the currently active environment for the given scope, or `undefined` if
+     * none is selected. Called very frequently — at startup, after {@link set}, when a
+     * terminal is opened, before running Python, by UI surfaces that display the active
+     * interpreter, and by other extensions consuming the API.
+     */
+    get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
+    /**
+     * Event that is fired when the current Python environment changes.
+     */
+    onDidChangeEnvironment?: Event<DidChangeEnvironmentEventArgs>;
+    /**
+     * Resolves the specified Python environment. The environment can be either a {@link PythonEnvironment} or a {@link Uri} context.
+     *
+     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input can be:
+     * - A {@link PythonEnvironment} object, which might be missing key details such as {@link PythonEnvironment.execInfo}.
+     * - A {@link Uri} object, which typically represents either:
+     *   - A folder that contains the Python environment.
+     *   - The path to a Python executable.
+     *
+     * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
+     * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
+     *
+     * @remarks
+     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
+     * pointing at an interpreter or environment folder into a fully-populated
+     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
+     * triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before
+     * launching Python.
+     */
+    resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
+    /**
+     * Clears the environment manager's cache.
+     *
+     * @returns A promise that resolves when the cache is cleared.
+     *
+     * @remarks
+     * Drops any cached environment data held by the manager so that subsequent calls to
+     * {@link EnvironmentManager.getEnvironments} or {@link EnvironmentManager.get}
+     * re-discover state from disk. Typically triggered by an explicit user "clear cache"
+     * action.
+     */
+    clearCache?(): Promise<void>;
+}
+/**
+ * Interface representing a package ID.
+ */
+export interface PackageId {
+    /**
+     * The ID of the package.
+     */
+    id: string;
+    /**
+     * The ID of the package manager.
+     */
+    managerId: string;
+    /**
+     * The ID of the environment in which the package is installed.
+     */
+    environmentId: string;
+}
+/**
+ * Interface representing package information.
+ */
+export interface PackageInfo {
+    /**
+     * The name of the package.
+     */
+    readonly name: string;
+    /**
+     * The display name of the package.
+     */
+    readonly displayName: string;
+    /**
+     * The version of the package.
+     */
+    readonly version?: string;
+    /**
+     * The description of the package.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the package, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString | undefined;
+    /**
+     * The icon path for the package, which can be a string, Uri, or an object with light and dark theme paths.
+     */
+    readonly iconPath?: IconPath;
+    /**
+     * The URIs associated with the package.
+     */
+    readonly uris?: readonly Uri[];
+}
+/**
+ * Interface representing a package.
+ */
+export interface Package extends PackageInfo {
+    /**
+     * The ID of the package.
+     */
+    readonly pkgId: PackageId;
+}
+/**
+ * Enum representing the kinds of package changes.
+ */
+export declare enum PackageChangeKind {
+    /**
+     * Indicates that a package was added.
+     */
+    add = "add",
+    /**
+     * Indicates that a package was removed.
+     */
+    remove = "remove"
+}
+/**
+ * Event arguments for when packages change.
+ */
+export interface DidChangePackagesEventArgs {
+    /**
+     * The Python environment in which the packages changed.
+     */
+    environment: PythonEnvironment;
+    /**
+     * The package manager responsible for the changes.
+     */
+    manager: PackageManager;
+    /**
+     * The list of changes, each containing the kind of change and the package affected.
+     */
+    changes: {
+        kind: PackageChangeKind;
+        pkg: Package;
+    }[];
+}
+/**
+ * Interface representing a package manager.
+ */
+export interface PackageManager {
+    /**
+     * The name of the package manager. Allowed characters (a-z, A-Z, 0-9, -, _).
+     */
+    name: string;
+    /**
+     * The display name of the package manager.
+     */
+    displayName?: string;
+    /**
+     * The description of the package manager.
+     */
+    description?: string;
+    /**
+     * The tooltip for the package manager, which can be a string or a Markdown string.
+     */
+    tooltip?: string | MarkdownString | undefined;
+    /**
+     * The icon path for the package manager, which can be a string, Uri, or an object with light and dark theme paths.
+     */
+    iconPath?: IconPath;
+    /**
+     * The log output channel for the package manager.
+     */
+    log?: LogOutputChannel;
+    /**
+     * Installs/Uninstall packages in the specified Python environment.
+     * @param environment - The Python environment in which to install packages.
+     * @param options - Options for managing packages.
+     * @returns A promise that resolves when the installation is complete.
+     */
+    manage(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
+    /**
+     * Refreshes the package list for the specified Python environment.
+     * @param environment - The Python environment for which to refresh the package list.
+     * @returns A promise that resolves when the refresh is complete.
+     */
+    refresh(environment: PythonEnvironment): Promise<void>;
+    /**
+     * Retrieves the list of packages for the specified Python environment.
+     * @param environment - The Python environment for which to retrieve packages.
+     * @returns An array of packages, or undefined if the packages could not be retrieved.
+     */
+    getPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
+    /**
+     * Event that is fired when packages change.
+     */
+    onDidChangePackages?: Event<DidChangePackagesEventArgs>;
+    /**
+     * Clears the package manager's cache.
+     * @returns A promise that resolves when the cache is cleared.
+     */
+    clearCache?(): Promise<void>;
+}
+/**
+ * Interface representing a Python project.
+ */
+export interface PythonProject {
+    /**
+     * The name of the Python project.
+     */
+    readonly name: string;
+    /**
+     * The URI of the Python project.
+     */
+    readonly uri: Uri;
+    /**
+     * The description of the Python project.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the Python project, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString;
+}
+/**
+ * Options for creating a Python project.
+ */
+export interface PythonProjectCreatorOptions {
+    /**
+     * The name of the Python project.
+     */
+    name: string;
+    /**
+     * Path provided as the root for the project.
+     */
+    rootUri: Uri;
+    /**
+     * Boolean indicating whether the project should be created without any user input.
+     */
+    quickCreate?: boolean;
+}
+/**
+ * Interface representing a creator for Python projects.
+ */
+export interface PythonProjectCreator {
+    /**
+     * The name of the Python project creator.
+     */
+    readonly name: string;
+    /**
+     * The display name of the Python project creator.
+     */
+    readonly displayName?: string;
+    /**
+     * The description of the Python project creator.
+     */
+    readonly description?: string;
+    /**
+     * The tooltip for the Python project creator, which can be a string or a Markdown string.
+     */
+    readonly tooltip?: string | MarkdownString;
+    /**
+     * Creates a new Python project(s) or, if files are not a project, returns Uri(s) to the created files.
+     * Anything that needs its own python environment constitutes a project.
+     * @param options Optional parameters for creating the Python project.
+     * @returns A promise that resolves to one of the following:
+     *   - PythonProject or PythonProject[]: when a single or multiple projects are created.
+     *   - Uri or Uri[]: when files are created that do not constitute a project.
+     *   - undefined: if project creation fails.
+     */
+    create(options?: PythonProjectCreatorOptions): Promise<PythonProject | PythonProject[] | Uri | Uri[] | undefined>;
+    /**
+     * A flag indicating whether the project creator supports quick create where no user input is required.
+     */
+    readonly supportsQuickCreate?: boolean;
+}
+/**
+ * Event arguments for when Python projects change.
+ */
+export interface DidChangePythonProjectsEventArgs {
+    /**
+     * The list of Python projects that were added.
+     */
+    added: PythonProject[];
+    /**
+     * The list of Python projects that were removed.
+     */
+    removed: PythonProject[];
+}
+export type PackageManagementOptions = {
+    /**
+     * Upgrade the packages if they are already installed.
+     */
+    upgrade?: boolean;
+    /**
+     * Show option to skip package installation or uninstallation.
+     */
+    showSkipOption?: boolean;
+    /**
+     * The list of packages to install.
+     */
+    install: string[];
+    /**
+     * The list of packages to uninstall.
+     */
+    uninstall?: string[];
+} | {
+    /**
+     * Upgrade the packages if they are already installed.
+     */
+    upgrade?: boolean;
+    /**
+     * Show option to skip package installation or uninstallation.
+     */
+    showSkipOption?: boolean;
+    /**
+     * The list of packages to install.
+     */
+    install?: string[];
+    /**
+     * The list of packages to uninstall.
+     */
+    uninstall: string[];
+};
+/**
+ * Options for creating a Python environment.
+ */
+export interface CreateEnvironmentOptions {
+    /**
+     * Provides some context about quick create based on user input.
+     *   - if true, the environment should be created without any user input or prompts.
+     *   - if false, the environment creation can show user input or prompts.
+     *     This also means user explicitly skipped the quick create option.
+     *   - if undefined, the environment creation can show user input or prompts.
+     *     You can show quick create option to the user if you support it.
+     */
+    quickCreate?: boolean;
+    /**
+     * Packages to install in addition to the automatically picked packages as a part of creating environment.
+     */
+    additionalPackages?: string[];
+}
+/**
+ * Object representing the process started using run in background API.
+ */
+export interface PythonProcess {
+    /**
+     * The process ID of the Python process.
+     */
+    readonly pid?: number;
+    /**
+     * The standard input of the Python process.
+     */
+    readonly stdin: NodeJS.WritableStream;
+    /**
+     * The standard output of the Python process.
+     */
+    readonly stdout: NodeJS.ReadableStream;
+    /**
+     * The standard error of the Python process.
+     */
+    readonly stderr: NodeJS.ReadableStream;
+    /**
+     * Kills the Python process.
+     */
+    kill(): void;
+    /**
+     * Event that is fired when the Python process exits.
+     */
+    onExit(listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+}
+export interface PythonEnvironmentManagerRegistrationApi {
+    /**
+     * Register an environment manager implementation.
+     *
+     * @param manager Environment Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @returns A disposable that can be used to unregister the environment manager.
+     * @see {@link EnvironmentManager}
+     */
+    registerEnvironmentManager(manager: EnvironmentManager, options?: {
+        extensionId?: string;
+    }): Disposable;
+}
+export interface PythonEnvironmentItemApi {
+    /**
+     * Create a Python environment item from the provided environment info. This item is used to interact
+     * with the environment.
+     *
+     * @param info Some details about the environment like name, version, etc. needed to interact with the environment.
+     * @param manager The environment manager to associate with the environment.
+     * @returns The Python environment.
+     */
+    createPythonEnvironmentItem(info: PythonEnvironmentInfo, manager: EnvironmentManager): PythonEnvironment;
+}
+export interface PythonEnvironmentManagementApi {
+    /**
+     * Create a Python environment using environment manager associated with the scope.
+     *
+     * @param scope Where the environment is to be created.
+     * @param options Optional parameters for creating the Python environment.
+     * @returns The Python environment created. `undefined` if not created.
+     */
+    createEnvironment(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
+    /**
+     * Remove a Python environment.
+     *
+     * @param environment The Python environment to remove.
+     * @returns A promise that resolves when the environment has been removed.
+     */
+    removeEnvironment(environment: PythonEnvironment): Promise<void>;
+}
+export interface PythonEnvironmentsApi {
+    /**
+     * Initiates a refresh of Python environments within the specified scope.
+     * @param scope - The scope within which to search for environments.
+     * @returns A promise that resolves when the search is complete.
+     */
+    refreshEnvironments(scope: RefreshEnvironmentsScope): Promise<void>;
+    /**
+     * Retrieves a list of Python environments within the specified scope.
+     * @param scope - The scope within which to retrieve environments.
+     * @returns A promise that resolves to an array of Python environments.
+     */
+    getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
+    /**
+     * Event that is fired when the list of Python environments changes.
+     * @see {@link DidChangeEnvironmentsEventArgs}
+     */
+    onDidChangeEnvironments: Event<DidChangeEnvironmentsEventArgs>;
+    /**
+     * This method is used to get the details missing from a PythonEnvironment. Like
+     * {@link PythonEnvironment.execInfo} and other details.
+     *
+     * @param context : The PythonEnvironment or Uri for which details are required.
+     */
+    resolveEnvironment(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
+}
+export interface PythonProjectEnvironmentApi {
+    /**
+     * Sets the current Python environment within the specified scope.
+     * @param scope - The scope within which to set the environment.
+     * @param environment - The Python environment to set. If undefined, the environment is unset.
+     */
+    setEnvironment(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
+    /**
+     * Retrieves the current Python environment within the specified scope.
+     * @param scope - The scope within which to retrieve the environment.
+     * @returns A promise that resolves to the current Python environment, or undefined if none is set.
+     */
+    getEnvironment(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
+    /**
+     * Event that is fired when the selected Python environment changes for Project, Folder or File.
+     * @see {@link DidChangeEnvironmentEventArgs}
+     */
+    onDidChangeEnvironment: Event<DidChangeEnvironmentEventArgs>;
+}
+export interface PythonEnvironmentManagerApi extends PythonEnvironmentManagerRegistrationApi, PythonEnvironmentItemApi, PythonEnvironmentManagementApi, PythonEnvironmentsApi, PythonProjectEnvironmentApi {
+}
+export interface PythonPackageManagerRegistrationApi {
+    /**
+     * Register a package manager implementation.
+     *
+     * @param manager Package Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @returns A disposable that can be used to unregister the package manager.
+     * @see {@link PackageManager}
+     */
+    registerPackageManager(manager: PackageManager, options?: {
+        extensionId?: string;
+    }): Disposable;
+}
+export interface PythonPackageGetterApi {
+    /**
+     * Refresh the list of packages in a Python Environment.
+     *
+     * @param environment The Python Environment for which the list of packages is to be refreshed.
+     * @returns A promise that resolves when the list of packages has been refreshed.
+     */
+    refreshPackages(environment: PythonEnvironment): Promise<void>;
+    /**
+     * Get the list of packages in a Python Environment.
+     *
+     * @param environment The Python Environment for which the list of packages is required.
+     * @returns The list of packages in the Python Environment.
+     */
+    getPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
+    /**
+     * Event raised when the list of packages in a Python Environment changes.
+     * @see {@link DidChangePackagesEventArgs}
+     */
+    onDidChangePackages: Event<DidChangePackagesEventArgs>;
+}
+export interface PythonPackageItemApi {
+    /**
+     * Create a package item from the provided package info.
+     *
+     * @param info The package info.
+     * @param environment The Python Environment in which the package is installed.
+     * @param manager The package manager that installed the package.
+     * @returns The package item.
+     */
+    createPackageItem(info: PackageInfo, environment: PythonEnvironment, manager: PackageManager): Package;
+}
+export interface PythonPackageManagementApi {
+    /**
+     * Install/Uninstall packages into a Python Environment.
+     *
+     * @param environment The Python Environment into which packages are to be installed.
+     * @param packages The packages to install.
+     * @param options Options for installing packages.
+     */
+    managePackages(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
+}
+export interface PythonPackageManagerApi extends PythonPackageManagerRegistrationApi, PythonPackageGetterApi, PythonPackageManagementApi, PythonPackageItemApi {
+}
+export interface PythonProjectCreationApi {
+    /**
+     * Register a Python project creator.
+     *
+     * @param creator The project creator to register.
+     * @returns A disposable that can be used to unregister the project creator.
+     * @see {@link PythonProjectCreator}
+     */
+    registerPythonProjectCreator(creator: PythonProjectCreator): Disposable;
+}
+export interface PythonProjectGetterApi {
+    /**
+     * Get all python projects.
+     */
+    getPythonProjects(): readonly PythonProject[];
+    /**
+     * Get the python project for a given URI.
+     *
+     * @param uri The URI of the project
+     * @returns The project or `undefined` if not found.
+     */
+    getPythonProject(uri: Uri): PythonProject | undefined;
+}
+export interface PythonProjectModifyApi {
+    /**
+     * Add a python project or projects to the list of projects.
+     *
+     * @param projects The project or projects to add.
+     */
+    addPythonProject(projects: PythonProject | PythonProject[]): void;
+    /**
+     * Remove a python project from the list of projects.
+     *
+     * @param project The project to remove.
+     */
+    removePythonProject(project: PythonProject): void;
+    /**
+     * Event raised when python projects are added or removed.
+     * @see {@link DidChangePythonProjectsEventArgs}
+     */
+    onDidChangePythonProjects: Event<DidChangePythonProjectsEventArgs>;
+}
+/**
+ * The API for interacting with Python projects. A project in python is any folder or file that is a contained
+ * in some manner. For example, a PEP-723 compliant file can be treated as a project. A folder with a `pyproject.toml`,
+ * or just python files can be treated as a project. All this allows you to do is set a python environment for that project.
+ *
+ * By default all `vscode.workspace.workspaceFolders` are treated as projects.
+ */
+export interface PythonProjectApi extends PythonProjectCreationApi, PythonProjectGetterApi, PythonProjectModifyApi {
+}
+export interface PythonTerminalCreateOptions extends TerminalOptions {
+    /**
+     * Whether to disable activation on create.
+     */
+    disableActivation?: boolean;
+}
+export interface PythonTerminalCreateApi {
+    /**
+     * Creates a terminal and activates any (activatable) environment for the terminal.
+     *
+     * @param environment The Python environment to activate.
+     * @param options Options for creating the terminal.
+     *
+     * Note: Non-activatable environments have no effect on the terminal.
+     */
+    createTerminal(environment: PythonEnvironment, options: PythonTerminalCreateOptions): Promise<Terminal>;
+}
+/**
+ * Options for running a Python script or module in a terminal.
+ *
+ * Example:
+ *  * Running Script: `python myscript.py --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["myscript.py", "--arg1"]
+ *    }
+ *  ```
+ *  * Running a module: `python -m my_module --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["-m", "my_module", "--arg1"]
+ *    }
+ *  ```
+ */
+export interface PythonTerminalExecutionOptions {
+    /**
+     * Current working directory for the terminal. This in only used to create the terminal.
+     */
+    cwd: string | Uri;
+    /**
+     * Arguments to pass to the python executable.
+     */
+    args?: string[];
+    /**
+     * Set `true` to show the terminal.
+     */
+    show?: boolean;
+}
+export interface PythonTerminalRunApi {
+    /**
+     * Runs a Python script or module in a terminal. This API will create a terminal if one is not available to use.
+     * If a terminal is available, it will be used to run the script or module.
+     *
+     * Note:
+     *  - If you restart VS Code, this will create a new terminal, this is a limitation of VS Code.
+     *  - If you close the terminal, this will create a new terminal.
+     *  - In cases of multi-root/project scenario, it will create a separate terminal for each project.
+     */
+    runInTerminal(environment: PythonEnvironment, options: PythonTerminalExecutionOptions): Promise<Terminal>;
+    /**
+     * Runs a Python script or module in a dedicated terminal. This API will create a terminal if one is not available to use.
+     * If a terminal is available, it will be used to run the script or module. This terminal will be dedicated to the script,
+     * and selected based on the `terminalKey`.
+     *
+     * @param terminalKey A unique key to identify the terminal. For scripts you can use the Uri of the script file.
+     */
+    runInDedicatedTerminal(terminalKey: Uri | string, environment: PythonEnvironment, options: PythonTerminalExecutionOptions): Promise<Terminal>;
+}
+/**
+ * Options for running a Python task.
+ *
+ * Example:
+ *  * Running Script: `python myscript.py --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["myscript.py", "--arg1"]
+ *    }
+ *  ```
+ *  * Running a module: `python -m my_module --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["-m", "my_module", "--arg1"]
+ *    }
+ *  ```
+ */
+export interface PythonTaskExecutionOptions {
+    /**
+     * Name of the task to run.
+     */
+    name: string;
+    /**
+     * Arguments to pass to the python executable.
+     */
+    args: string[];
+    /**
+     * The Python project to use for the task.
+     */
+    project?: PythonProject;
+    /**
+     * Current working directory for the task. Default is the project directory for the script being run.
+     */
+    cwd?: string;
+    /**
+     * Environment variables to set for the task.
+     */
+    env?: {
+        [key: string]: string;
+    };
+}
+export interface PythonTaskRunApi {
+    /**
+     * Run a Python script or module as a task.
+     *
+     */
+    runAsTask(environment: PythonEnvironment, options: PythonTaskExecutionOptions): Promise<TaskExecution>;
+}
+/**
+ * Options for running a Python script or module in the background.
+ */
+export interface PythonBackgroundRunOptions {
+    /**
+     * The Python environment to use for running the script or module.
+     */
+    args: string[];
+    /**
+     * Current working directory for the script or module. Default is the project directory for the script being run.
+     */
+    cwd?: string;
+    /**
+     * Environment variables to set for the script or module.
+     */
+    env?: {
+        [key: string]: string | undefined;
+    };
+}
+export interface PythonBackgroundRunApi {
+    /**
+     * Run a Python script or module in the background. This API will create a new process to run the script or module.
+     */
+    runInBackground(environment: PythonEnvironment, options: PythonBackgroundRunOptions): Promise<PythonProcess>;
+}
+export interface PythonExecutionApi extends PythonTerminalCreateApi, PythonTerminalRunApi, PythonTaskRunApi, PythonBackgroundRunApi {
+}
+/**
+ * Event arguments for when the monitored `.env` files or any other sources change.
+ */
+export interface DidChangeEnvironmentVariablesEventArgs {
+    /**
+     * The URI of the file that changed. No `Uri` means a non-file source of environment variables changed.
+     */
+    uri?: Uri;
+    /**
+     * The type of change that occurred.
+     */
+    changeType: FileChangeType;
+}
+export interface PythonEnvironmentVariablesApi {
+    /**
+     * Get environment variables for a workspace. This picks up `.env` file from the root of the
+     * workspace.
+     *
+     * Order of overrides:
+     * 1. `baseEnvVar` if given or `process.env`
+     * 2. `.env` file from the "python.envFile" setting in the workspace.
+     * 3. `.env` file at the root of the python project.
+     * 4. `overrides` in the order provided.
+     *
+     * @param uri The URI of the project, workspace or a file in a for which environment variables are required.If not provided,
+     * it fetches the environment variables for the global scope.
+     * @param overrides Additional environment variables to override the defaults.
+     * @param baseEnvVar The base environment variables that should be used as a starting point.
+     */
+    getEnvironmentVariables(uri: Uri | undefined, overrides?: ({
+        [key: string]: string | undefined;
+    } | Uri)[], baseEnvVar?: {
+        [key: string]: string | undefined;
+    }): Promise<{
+        [key: string]: string | undefined;
+    }>;
+    /**
+     * Event raised when `.env` file changes or any other monitored source of env variable changes.
+     */
+    onDidChangeEnvironmentVariables: Event<DidChangeEnvironmentVariablesEventArgs>;
+}
+/**
+ * The API for interacting with Python environments, package managers, and projects.
+ */
+export interface PythonEnvironmentApi extends PythonEnvironmentManagerApi, PythonPackageManagerApi, PythonProjectApi, PythonExecutionApi, PythonEnvironmentVariablesApi {
+}
+export declare const EXTENSION_ID = "ms-python.vscode-python-envs";
+export declare namespace PythonEnvironments {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    function api(): Promise<PythonEnvironmentApi>;
+}

package/out/main.js

@@ -0,0 +1,54 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonEnvironments = exports.EXTENSION_ID = exports.PackageChangeKind = exports.EnvironmentChangeKind = void 0;
+const vscode_1 = require("vscode");
+/**
+ * Enum representing the kinds of environment changes.
+ */
+var EnvironmentChangeKind;
+(function (EnvironmentChangeKind) {
+    /**
+     * Indicates that an environment was added.
+     */
+    EnvironmentChangeKind["add"] = "add";
+    /**
+     * Indicates that an environment was removed.
+     */
+    EnvironmentChangeKind["remove"] = "remove";
+})(EnvironmentChangeKind || (exports.EnvironmentChangeKind = EnvironmentChangeKind = {}));
+/**
+ * Enum representing the kinds of package changes.
+ */
+var PackageChangeKind;
+(function (PackageChangeKind) {
+    /**
+     * Indicates that a package was added.
+     */
+    PackageChangeKind["add"] = "add";
+    /**
+     * Indicates that a package was removed.
+     */
+    PackageChangeKind["remove"] = "remove";
+})(PackageChangeKind || (exports.PackageChangeKind = PackageChangeKind = {}));
+exports.EXTENSION_ID = 'ms-python.vscode-python-envs';
+// eslint-disable-next-line @typescript-eslint/no-namespace
+var PythonEnvironments;
+(function (PythonEnvironments) {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    async function api() {
+        const extension = vscode_1.extensions.getExtension(exports.EXTENSION_ID);
+        if (extension === undefined) {
+            throw new Error(`Python Environments extension is not installed or is disabled`);
+        }
+        if (!extension.isActive) {
+            await extension.activate();
+        }
+        const pythonEnvsApi = extension.exports;
+        return pythonEnvsApi;
+    }
+    PythonEnvironments.api = api;
+})(PythonEnvironments || (exports.PythonEnvironments = PythonEnvironments = {}));

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@vscode/python-environments",
+    "description": "An API facade for the Python Environments extension in VS Code",
+    "version": "1.0.0",
+    "author": {
+        "name": "Microsoft Corporation"
+    },
+    "keywords": [
+        "Python",
+        "VSCode",
+        "API",
+        "Environments"
+    ],
+    "main": "./out/main.js",
+    "types": "./out/main.d.ts",
+    "engines": {
+        "node": ">=22.21.1",
+        "vscode": "^1.110.0"
+    },
+    "license": "MIT",
+    "homepage": "https://github.com/microsoft/vscode-python-environments/tree/main/api",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/microsoft/vscode-python-environments"
+    },
+    "bugs": {
+        "url": "https://github.com/microsoft/vscode-python-environments/issues"
+    },
+    "scripts": {
+        "prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node -e \"process.exitCode = 1\"",
+        "prepack": "npm run all:publish",
+        "all:publish": "git clean -xfd . && npm install && npm run compile",
+        "compile": "tsc -b ./tsconfig.json",
+        "clean": "node -e \"const fs = require('fs'); fs.rmSync('./out', { recursive: true, force: true });\""
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "@types/vscode": "^1.99.0",
+        "typescript": "^5.1.3"
+    }
+}