@vscode/python-environments 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to the `@vscode/python-environments` API package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0]
+
+### Added
+
+- Added `PackageVersionLookupNotSupportedError`, thrown when a package manager cannot list a package's available versions (an unsupported capability, as distinct from an operational failure). The error exposes a stable `code` (`'PackageVersionLookupNotSupported'`) discriminator.
+- Added the `isPackageVersionLookupNotSupportedError(error): error is PackageVersionLookupNotSupportedError` type guard. It recognizes the error via its stable `code`, so it works even when the error crosses an extension bundle boundary and `instanceof` would fail.
+- Added an optional `errorMode` to `PythonPackageGetterApi.getPackageAvailableVersions`. The default `legacy` mode preserves the existing `undefined` result for unsupported lookups and operational failures. The opt-in `throw` mode rejects with `PackageVersionLookupNotSupportedError` for unsupported capabilities and propagates operational failures unchanged.
+
+### Changed
+
+- Documented that `PackageManager.getPackageAvailableVersions` implementations should throw `PackageVersionLookupNotSupportedError` when version lookup is unsupported and let operational failures propagate. Resolving to `undefined` continues to be treated by callers as an unsupported capability.
+
+## [1.2.0]
+
+### Added
+
+- Added `PackageManagementInteractionOptions` with an optional `runHeadless?: boolean` property, mixed into `PackageManagementOptions`. When `true`, package management operations run without any user prompts or interaction — steps that would normally require input, such as selecting packages to install when none are specified, are skipped instead of prompting — for automated or headless scenarios such as integration tests.
+- Added `RemoveEnvironmentOptions` with an optional `runHeadless?: boolean` property to remove environments without a confirmation prompt in automated or headless scenarios.
+
+## [1.1.0]
+
+### Added
+
+- Re-exported the `Pep440Version` type from `@renovatebot/pep440` for use with the new package version APIs.
+- Added the optional `PackageInfo.isTransitive?: boolean` property to indicate whether a package is a transitive dependency.
+- Added `GetPackagesOptions` with an optional `skipCache?: boolean` property. When `true`, package managers bypass cached data and query the underlying package management tool.
+- Added optional `PackageManager.getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[]` to return manager-specific filesystem patterns to monitor for package installation and removal changes, in addition to the default site-packages metadata locations.
+- Added optional `PackageManager.getDirectPackageNames?(environment: PythonEnvironment): Promise<Set<string> | undefined>` to return a best-effort set of direct, non-transitive package names when supported by the package manager.
+- Added optional `PackageManager.getVersion?(environment: PythonEnvironment): Promise<Pep440Version | undefined>` to return the version of the underlying package management tool, such as pip, uv, or conda.
+- Added optional `PackageManager.getPackageAvailableVersions?(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>` to return the available versions of a package in newest-first order when supported.
+- Added optional `PackageManager.formatInstallSpec?(packageName: string, version: string): string` to format a versioned install specification using manager-specific syntax, such as `name==version` for pip or `name=version` for conda.
+- Added `PythonPackageGetterApi.getPackageAvailableVersions(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>` so API consumers can query a package's available versions in newest-first order. Resolves to `undefined` when the environment's package manager does not support version listing.
+
+### Changed
+
+- Added the optional `options?: GetPackagesOptions` parameter to `PackageManager.getPackages(environment, options?)` and `PythonPackageGetterApi.getPackages(environment, options?)`. Consumers can set `options.skipCache` to request fresh package data.

package/out/cjs/main.cjs

@@ -0,0 +1,101 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonEnvironments = exports.EXTENSION_ID = exports.PackageVersionLookupNotSupportedError = exports.PackageChangeKind = exports.EnvironmentChangeKind = void 0;
+exports.isPackageVersionLookupNotSupportedError = isPackageVersionLookupNotSupportedError;
+const vscode_1 = require("vscode");
+/**
+ * Enum representing the kinds of environment changes.
+ */
+var EnvironmentChangeKind;
+(function (EnvironmentChangeKind) {
+    /**
+     * Indicates that an environment was added.
+     */
+    EnvironmentChangeKind["add"] = "add";
+    /**
+     * Indicates that an environment was removed.
+     */
+    EnvironmentChangeKind["remove"] = "remove";
+})(EnvironmentChangeKind || (exports.EnvironmentChangeKind = EnvironmentChangeKind = {}));
+/**
+ * Enum representing the kinds of package changes.
+ */
+var PackageChangeKind;
+(function (PackageChangeKind) {
+    /**
+     * Indicates that a package was added.
+     */
+    PackageChangeKind["add"] = "add";
+    /**
+     * Indicates that a package was removed.
+     */
+    PackageChangeKind["remove"] = "remove";
+})(PackageChangeKind || (exports.PackageChangeKind = PackageChangeKind = {}));
+/**
+ * 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.
+ */
+class PackageVersionLookupNotSupportedError extends Error {
+    constructor(message) {
+        super(message ?? 'The package manager does not support looking up available package versions.');
+        /**
+         * Stable discriminator identifying this error type across bundle boundaries.
+         */
+        this.code = 'PackageVersionLookupNotSupported';
+        this.name = 'PackageVersionLookupNotSupportedError';
+        // Preserve the prototype chain when this class is transpiled to older targets so that
+        // `instanceof` continues to work within a single bundle.
+        Object.setPrototypeOf(this, PackageVersionLookupNotSupportedError.prototype);
+    }
+}
+exports.PackageVersionLookupNotSupportedError = PackageVersionLookupNotSupportedError;
+/**
+ * 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`).
+ */
+function isPackageVersionLookupNotSupportedError(error) {
+    return (error instanceof PackageVersionLookupNotSupportedError ||
+        (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'PackageVersionLookupNotSupported'));
+}
+exports.EXTENSION_ID = 'ms-python.vscode-python-envs';
+var PythonEnvironments;
+(function (PythonEnvironments) {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    async function api() {
+        const extension = vscode_1.extensions.getExtension(exports.EXTENSION_ID);
+        if (extension === undefined) {
+            throw new Error(`Python Environments extension (${exports.EXTENSION_ID}) is not installed or is disabled`);
+        }
+        if (!extension.isActive) {
+            await extension.activate();
+        }
+        const api = extension.exports;
+        if (!api) {
+            throw new Error(`Python Environments extension (${exports.EXTENSION_ID}) did not expose its API. Ensure "python.useEnvironmentsExtension" is enabled and reload the window.`);
+        }
+        return api;
+    }
+    PythonEnvironments.api = api;
+})(PythonEnvironments || (exports.PythonEnvironments = PythonEnvironments = {}));

package/out/{main.d.ts → cjs/main.d.ts}

@@ -1,4 +1,6 @@
-import { Disposable, Event, FileChangeType, LogOutputChannel, MarkdownString, TaskExecution, Terminal, TerminalOptions, ThemeIcon, Uri } from 'vscode';
+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.
  */
@@ -274,6 +276,16 @@ export interface QuickCreateConfig {
      */
     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.
  *
@@ -345,7 +357,7 @@ export interface EnvironmentManager {
      * Invoked to delete the given environment. Typical triggers include an explicit user
      * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
-    remove?(environment: PythonEnvironment): Promise<void>;
+    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.
@@ -484,6 +496,10 @@ export interface PackageInfo {
      * The URIs associated with the package.
      */
     readonly uris?: readonly Uri[];
+    /**
+     * Whether the package is a transitive dependency.
+     */
+    readonly isTransitive?: boolean;
 }
 /**
  * Interface representing a package.
@@ -571,18 +587,79 @@ export interface PackageManager {
     /**
      * 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): Promise<Package[] | undefined>;
+    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.
@@ -670,7 +747,30 @@ export interface DidChangePythonProjectsEventArgs {
      */
     removed: PythonProject[];
 }
-export type PackageManagementOptions = {
+/**
+ * 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.
      */
@@ -704,7 +804,7 @@ export type PackageManagementOptions = {
      * The list of packages to uninstall.
      */
     uninstall: string[];
-};
+});
 /**
  * Options for creating a Python environment.
  */
@@ -758,9 +858,8 @@ export interface PythonEnvironmentManagerRegistrationApi {
      *
      * @param manager Environment Manager implementation to register.
      * @param options Optional registration options.
-     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
-     * automatic extension detection fails, such as during F5 debugging where the extension's file path
-     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @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}
      */
@@ -792,9 +891,10 @@ export interface PythonEnvironmentManagementApi {
      * 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): Promise<void>;
+    removeEnvironment(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 }
 export interface PythonEnvironmentsApi {
     /**
@@ -849,9 +949,8 @@ export interface PythonPackageManagerRegistrationApi {
      *
      * @param manager Package Manager implementation to register.
      * @param options Optional registration options.
-     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
-     * automatic extension detection fails, such as during F5 debugging where the extension's file path
-     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @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}
      */
@@ -859,6 +958,52 @@ export interface PythonPackageManagerRegistrationApi {
         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.
@@ -871,9 +1016,28 @@ export interface PythonPackageGetterApi {
      * 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): Promise<Package[] | undefined>;
+    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}