feat: add getPackageAvailableVersions to public API and bump API to 1.1.0

api/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the `@vscode/python-environments` API package are documen
 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.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.
+- Changed `PackageManager.refresh(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, allowing implementations to return the refreshed package list.
+- Changed `PythonPackageGetterApi.refreshPackages(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, exposing the refreshed package list to API consumers.
+
 ## [1.37.0]
 
 - Aligned the API package version with the Python Environments extension version.

api/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "author": {
         "name": "Microsoft Corporation"
     },

src/api.ts

@@ -1108,6 +1108,22 @@ export interface PythonPackageGetterApi {
      */
     getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
 
+    /**
+     * Get the list of available versions for a package, newest first.
+     *
+     * Support depends on the package manager backing the environment. Managers that do
+     * not implement version lookup resolve to `undefined`.
+     *
+     * @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),
+     *          or `undefined` if the package manager does not support version listing.
+     */
+    getPackageAvailableVersions(
+        environment: PythonEnvironment,
+        packageName: string,
+    ): Promise<Pep440Version[] | undefined>;
+
     /**
      * Event raised when the list of packages in a Python Environment changes.
      * @see {@link DidChangePackagesEventArgs}

src/features/pythonApi.ts

@@ -16,6 +16,7 @@ import {
     PackageInfo,
     PackageManagementOptions,
     PackageManager,
+    Pep440Version,
     PythonBackgroundRunOptions,
     PythonEnvironment,
     PythonEnvironmentApi,
@@ -319,6 +320,17 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         }
         return manager.getPackages(context, options);
     }
+    async getPackageAvailableVersions(
+        context: PythonEnvironment,
+        packageName: string,
+    ): Promise<Pep440Version[] | undefined> {
+        await waitForEnvManagerId([context.envId.managerId]);
+        const manager = this.envManagers.getPackageManager(context);
+        if (!manager) {
+            return Promise.resolve(undefined);
+        }
+        return manager.getPackageAvailableVersions(context, packageName);
+    }
     onDidChangePackages: Event<DidChangePackagesEventArgs> = this._onDidChangePackages.event;
 
     createPackageItem(info: PackageInfo, environment: PythonEnvironment, manager: PackageManager): Package {