types.ts

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

/*
 * Do not introduce any breaking changes to these public API contracts.
 * This module is the canonical home for the TypeScript contracts (interfaces, types, enums)
 * that make up the public API for other extensions to interact with the Python Environments
 * extension. It intentionally contains no runtime helpers, concrete error classes, or
 * implementation imports — see `./api.ts` (public runtime facade) and `./publicErrors.ts`
 * (concrete error + guard) for those.
 */

import type { Pep440Version } from '@renovatebot/pep440';
import type {
    Capabilities,
    CapabilityContext,
    EnvironmentManagerCapability,
    PackageManagerCapability,
    Support,
} from './capabilities.js';
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 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 {
    /**
     * Optional for legacy providers. When present, advertises every environment capability key.
     * An omitted map uses legacy method inference. Missing keys in a supplied map resolve unsupported.
     * Use instance-field arrow functions to retain manager state; checks must not prompt or mutate.
     */
    readonly capabilities?: Capabilities<EnvironmentManagerCapability>;

    /**
     * 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;

    /**
     * Returns the version of the underlying environment management tool.
     * @returns A promise that resolves to a {@link Pep440Version} object, or `undefined` if not available.
     */
    getVersion?(): Promise<Pep440Version | undefined>;

    /**
     * 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 Python environment associated with the specified URI context.
     *
     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input
     * URI typically represents either a folder that contains the Python environment or the path to
     * a Python executable.
     *
     * @param context - The URI context for resolving the environment.
     * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
     *
     * @remarks
     * Called to turn 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 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 {
    /**
     * Optional for legacy providers. When present, advertises every package capability key.
     * An omitted map uses legacy method inference. Missing keys in a supplied map resolve unsupported.
     * Use instance-field arrow functions to retain manager state; checks must not prompt or mutate.
     */
    readonly capabilities?: Capabilities<PackageManagerCapability>;

    /**
     * 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.
     *
     * A manager returned by createForProject must report that exact manager instance in
     * DidChangePackagesEventArgs.manager, even when root and scoped managers share an emitter.
     */
    onDidChangePackages?: Event<DidChangePackagesEventArgs>;

    /**
     * Creates a package manager bound to a Python project.
     *
     * The extension uses the explicit project supplied by project-based callers. When a caller
     * provides only an environment, the extension uses a project-bound manager only if exactly
     * one tracked project uses that environment. It does not invoke project-sensitive operations
     * on the registered root manager when no project can be selected safely.
     *
     * Project-independent package managers can omit this method. Implementations should keep
     * project-specific caches and mutable state on the returned manager rather than the root.
     *
     * @param project - The project to bind to the package manager.
     * @returns A package manager that uses the project for project-sensitive operations.
     */
    createForProject?(project: PythonProject): PackageManager;

    /**
     * Releases resources owned by this package manager.
     *
     * The extension invokes this method for managers returned by createForProject when their
     * project is removed or replaced, their provider is unregistered, or the extension shuts down.
     */
    dispose?(): void;

    /**
     * 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 {
    /**
     * Queries one explicitly identified manager without picking or aggregating managers.
     * Only currently registered managers are queried; no activation or registration wait occurs.
     * @param managerId Registered environment-manager ID.
     * @param capability Feature to query; general support does not validate operation arguments.
     * @param context Optional scope/environment/project. An environment must belong to managerId.
     * @returns Support, or a reason when the manager is missing or the feature unsupported.
     * Unavailable managers can be queried again after registration.
     * Unexpected lookup/probe errors and contradictory manager arguments reject.
     * Feature-detect this method when supporting older installed extension runtimes.
     */
    getEnvironmentManagerCapability(
        managerId: string,
        capability: EnvironmentManagerCapability,
        context?: CapabilityContext,
    ): Promise<Support>;

    /**
     * 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 for the Python environment associated with a URI
     * context, such as an interpreter path or environment folder.
     *
     * @param context - The URI context for which environment 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;
}


/**
 * 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 {
    /**
     * Queries the package manager selected for an environment or explicit project, without prompting.
     * Only currently registered managers are queried; no activation or registration wait occurs.
     * @param environment Environment used for the support check and default manager routing.
     * @param capability Feature to query; support does not guarantee a particular request succeeds.
     * @param project Explicit registered project for project-specific manager selection.
     * Unregistered projects return unavailable instead of using a containing project's provider.
     * If omitted, existing routing must identify a unique project when the selected manager requires one.
     * @returns Support, or a reason when routing is unresolved/ambiguous or the feature unsupported.
     * Unavailable managers can be queried again after registration.
     * Unexpected lookup/probe errors reject. Feature-detect on older extension runtimes.
     */
    getPackageManagerCapability(
        environment: PythonEnvironment,
        capability: PackageManagerCapability,
        project?: PythonProject,
    ): Promise<Support>;

    /**
     * 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.
     * @throws {@link PackageManagerRequiresProjectError} if a project-aware manager cannot identify
     * a unique project for the environment.
     */
    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, or `undefined` if no package manager
     * can be resolved for the 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 options Options for installing packages.
     * @throws {@link PackageManagerRequiresProjectError} if a project-aware manager cannot identify
     * a unique project for the environment.
     */
    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. This is passed directly to the spawned
     * process; when it is omitted the process inherits the extension host's working directory,
     * which is not the project directory. Supply this when the script resolves relative paths.
     */
    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 {}