@vscode/python-environments 1.3.0 → 1.4.0

package/out/esm/main.d.ts

@@ -1,1316 +0,0 @@
-import type { Pep440Version } from '@renovatebot/pep440';
-import type { Disposable, Event, FileChangeType, LogOutputChannel, MarkdownString, RelativePattern, TaskExecution, Terminal, TerminalOptions, ThemeIcon, Uri } from 'vscode';
-export type { Pep440Version } from '@renovatebot/pep440';
-/**
- * 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;
-}
-/**
- * Options controlling environment removal.
- */
-export interface RemoveEnvironmentOptions {
-    /**
-     * When `true`, removes the environment without prompting for confirmation.
-     * Intended for automated or headless scenarios. Defaults to `false`.
-     */
-    runHeadless?: boolean;
-}
-/**
- * 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, options?: RemoveEnvironmentOptions): 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[];
-    /**
-     * Whether the package is a transitive dependency.
-     */
-    readonly isTransitive?: boolean;
-}
-/**
- * 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.
-     * @param options - Optional settings for package retrieval.
-     * @returns An array of packages, or undefined if the packages could not be retrieved.
-     */
-    getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
-    /**
-     * Returns additional filesystem patterns to watch for package install/uninstall changes.
-     *
-     * These patterns are appended to the default site-packages metadata locations.
-     * Implement this for manager-specific locations (for example, conda-meta).
-     *
-     * @param environment - The Python environment whose package paths should be watched.
-     * @returns Relative patterns to watch for package changes.
-     */
-    getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[];
-    /**
-     * Event that is fired when packages change.
-     */
-    onDidChangePackages?: Event<DidChangePackagesEventArgs>;
-    /**
-     * Fetches the names of direct (non-transitive) packages for the specified Python environment.
-     *
-     * **Caveat:** Most package managers cannot track user install intent. For pip, this uses
-     * `pip list --not-required` which returns packages with no installed dependents (leaf packages),
-     * not necessarily packages the user explicitly installed. For example, if a user runs
-     * `pip install flask werkzeug`, werkzeug will still be reported as transitive because flask
-     * depends on it. This is a best-effort approximation.
-     *
-     * @param environment - The Python environment for which to fetch direct package names.
-     * @returns A promise that resolves to a set of package name strings, or undefined if not supported.
-     */
-    getDirectPackageNames?(environment: PythonEnvironment): Promise<Set<string> | undefined>;
-    /**
-     * Clears the package manager's cache.
-     * @returns A promise that resolves when the cache is cleared.
-     */
-    clearCache?(): Promise<void>;
-    /**
-     * Returns the version of the underlying package management tool (e.g., pip, uv, conda).
-     * @param environment - The Python environment context.
-     * @returns A promise that resolves to a {@link Pep440Version} object, or `undefined` if not available.
-     */
-    getVersion?(environment: PythonEnvironment): Promise<Pep440Version | undefined>;
-    /**
-     * Retrieves the list of available versions for a given package, newest first.
-     *
-     * Implementations should:
-     * - resolve to an array of {@link Pep440Version} objects on success;
-     * - throw a {@link PackageVersionLookupNotSupportedError} when this manager cannot look up
-     *   versions at all (an unsupported capability);
-     * - let operational failures (command, network, or malformed/unparseable output) propagate
-     *   instead of swallowing them into `undefined`.
-     *
-     * Resolving to `undefined` is treated by callers as an unsupported capability, equivalent to
-     * throwing {@link PackageVersionLookupNotSupportedError}.
-     *
-     * @param environment - The Python environment context for the lookup.
-     * @param packageName - The name of the package to look up.
-     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first).
-     * @throws {@link PackageVersionLookupNotSupportedError} when version lookup is unsupported.
-     */
-    getPackageAvailableVersions?(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>;
-    /**
-     * Formats a versioned install specification for this package manager.
-     *
-     * Different package managers use different syntax (e.g. pip uses `name==version`,
-     * conda uses `name=version`). Implement this method to return the correct format.
-     * When absent, callers should default to `name==version`.
-     *
-     * @param packageName - The name of the package.
-     * @param version - The version string.
-     * @returns The install specification string (e.g. `"requests==2.31.0"` or `"requests=2.31.0"`).
-     */
-    formatInstallSpec?(packageName: string, version: string): string;
-}
-/**
- * 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[];
-}
-/**
- * Options for retrieving packages from a package manager.
- */
-export interface GetPackagesOptions {
-    /**
-     * When `true`, bypasses the cache and fetches the latest packages from the underlying tool.
-     * Defaults to `false`.
-     */
-    skipCache?: boolean;
-}
-/**
- * Options controlling user interaction during package management operations.
- */
-export interface PackageManagementInteractionOptions {
-    /**
-     * When `true`, the package management operation runs without any user prompts or
-     * interaction and relies solely on the packages provided in the options. Any step
-     * that would normally require user input — such as selecting packages to install
-     * when none are specified — is skipped instead of prompting the user. Intended for
-     * automated or headless scenarios such as integration tests. Defaults to `false`.
-     */
-    runHeadless?: boolean;
-}
-export type PackageManagementOptions = PackageManagementInteractionOptions & ({
-    /**
-     * 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. When this is not specified,
-     * or when the specified extension cannot be found, the extension ID will be automatically detected.
-     * @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.
-     * @param options Optional parameters controlling environment removal.
-     * @returns A promise that resolves when the environment has been removed.
-     */
-    removeEnvironment(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): 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. When this is not specified,
-     * or when the specified extension cannot be found, the extension ID will be automatically detected.
-     * @returns A disposable that can be used to unregister the package manager.
-     * @see {@link PackageManager}
-     */
-    registerPackageManager(manager: PackageManager, options?: {
-        extensionId?: string;
-    }): Disposable;
-}
-/**
- * Error thrown when a package manager cannot list available package versions.
- *
- * This distinguishes an *unsupported capability* from an *operational failure* (such as a
- * failed command, a network error, or malformed/unparseable output). Consumers of
- * {@link PythonPackageGetterApi.getPackageAvailableVersions} should treat this specific error
- * as a signal to fall back to manual version entry, while letting any other error propagate.
- *
- * The {@link code} property carries a stable, string-literal discriminator so the error can be
- * recognized reliably across extension bundle boundaries, where `instanceof` may fail because
- * each bundle can load its own copy of this class. Prefer {@link isPackageVersionLookupNotSupportedError}
- * over a bare `instanceof` check for that reason.
- */
-export declare class PackageVersionLookupNotSupportedError extends Error {
-    /**
-     * Stable discriminator identifying this error type across bundle boundaries.
-     */
-    readonly code = "PackageVersionLookupNotSupported";
-    constructor(message?: string);
-}
-/**
- * Type guard reporting whether an error represents unsupported package version lookup.
- *
- * Uses the stable {@link PackageVersionLookupNotSupportedError.code} discriminator, so it returns
- * `true` even when the error crossed an extension bundle boundary and `instanceof` would fail.
- *
- * @param error The value to test.
- * @returns `true` if `error` is a {@link PackageVersionLookupNotSupportedError} (or a structurally
- *          equivalent error carrying the same `code`).
- */
-export declare function isPackageVersionLookupNotSupportedError(error: unknown): error is PackageVersionLookupNotSupportedError;
-/**
- * Controls how package version lookup failures are reported.
- */
-export interface GetPackageAvailableVersionsOptions {
-    /**
-     * Determines whether lookup failures preserve the legacy `undefined` result or reject.
-     *
-     * - `legacy` resolves to `undefined` for unsupported lookups and operational failures.
-     *   This remains the default for backward compatibility, but may be removed in a future
-     *   major API version.
-     * - `throw` rejects with {@link PackageVersionLookupNotSupportedError} for unsupported
-     *   lookups and propagates operational failures unchanged.
-     */
-    errorMode?: 'legacy' | 'throw';
-}
-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.
-     * @param options Optional settings for package retrieval.
-     * @returns The list of packages in the Python Environment.
-     */
-    getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
-    /**
-     * Get the list of available versions for a package, newest first.
-     *
-     * By default, this preserves the legacy behavior of resolving to `undefined` for unsupported
-     * lookups and operational failures. Pass `{ errorMode: 'throw' }` to distinguish unsupported
-     * capabilities from operational failures: unsupported lookups reject with
-     * {@link PackageVersionLookupNotSupportedError}, while other failures propagate unchanged.
-     *
-     * @param environment The Python Environment context for the lookup.
-     * @param packageName The name of the package to look up.
-     * @param options Controls how lookup failures are reported.
-     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
-     *          or `undefined` in legacy mode when lookup is unsupported or fails.
-     */
-    getPackageAvailableVersions(environment: PythonEnvironment, packageName: string, options: GetPackageAvailableVersionsOptions & {
-        errorMode: 'throw';
-    }): Promise<Pep440Version[]>;
-    getPackageAvailableVersions(environment: PythonEnvironment, packageName: string, options?: GetPackageAvailableVersionsOptions): Promise<Pep440Version[] | 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>;
-}