[Draft] feature: Manage package versions from sidebar

api/package.json

@@ -48,5 +48,8 @@
         "@types/vscode": "^1.99.0",
         "mve": "^0.1.2",
         "typescript": "^5.1.3"
+    },
+    "dependencies": {
+        "@renovatebot/pep440": "^3.1.0"
     }
 }

api/src/main.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+import type { Pep440Version } from '@renovatebot/pep440';
 import {
     Disposable,
     Event,
@@ -20,6 +21,7 @@ import {
  * This is the public API for other extensions to interact with the Python Environments extension.
  */
 
+export type { Pep440Version } from '@renovatebot/pep440';
 /**
  * The path to an icon, or a theme-specific configuration of icons.
  */
@@ -677,20 +679,57 @@ 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>;
 
     /**
      * Event that is fired when packages change.
      */
     onDidChangePackages?: Event<DidChangePackagesEventArgs>;
 
+    /**
+     * Fetches the names of direct (non-transitive) packages for the specified Python environment.
+     * @param environment - The Python environment for which to fetch direct package names.
+     * @returns A promise that resolves to an array of package name strings, or undefined if not supported.
+     */
+    fetchDirectPackageNames?(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.
+     * @param packageName - The name of the package to look up.
+     * @param environment - The Python environment context for the lookup.
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
+     *          or `undefined` if this manager does not support version listing.
+     */
+    getAvailableVersions?(packageName: string, environment: PythonEnvironment): 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;
 }
 
 /**
@@ -794,6 +833,17 @@ export interface DidChangePythonProjectsEventArgs {
     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;
+}
+
 export type PackageManagementOptions =
     | {
           /**
@@ -1025,9 +1075,10 @@ 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>;
 
     /**
      * Event raised when the list of packages in a Python Environment changes.
@@ -1059,12 +1110,33 @@ export interface PythonPackageManagementApi {
     managePackages(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
 }
 
+export interface Pep440VersionApi {
+    /**
+     * Get the version of the package manager tool associated with the given environment.
+     *
+     * @param environment The Python Environment whose package manager version is requested.
+     * @returns The {@link Pep440Version} of the package manager tool, or `undefined` if not available.
+     */
+    getPackageManagerVersion(environment: PythonEnvironment): Promise<Pep440Version | undefined>;
+
+    /**
+     * Get the list of available versions for a package from the package manager
+     * associated with the given environment.
+     *
+     * @param packageName The name of the package.
+     * @param environment The Python Environment context for the lookup.
+     * @returns An array of {@link Pep440Version} objects (newest first), or `undefined` if not supported.
+     */
+    getAvailableVersions(packageName: string, environment: PythonEnvironment): Promise<Pep440Version[] | undefined>;
+}
+
 export interface PythonPackageManagerApi
     extends
         PythonPackageManagerRegistrationApi,
         PythonPackageGetterApi,
         PythonPackageManagementApi,
-        PythonPackageItemApi {}
+        PythonPackageItemApi,
+        Pep440VersionApi {}
 
 export interface PythonProjectCreationApi {
     /**

examples/sample1/src/api.ts

@@ -611,9 +611,10 @@ 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>;
 
     /**
      * Event that is fired when packages change.
@@ -714,6 +715,17 @@ export interface DidChangePythonProjectsEventArgs {
     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 for package management.
  */
@@ -915,7 +927,8 @@ export interface PythonProjectEnvironmentApi {
 }
 
 export interface PythonEnvironmentManagerApi
-    extends PythonEnvironmentManagerRegistrationApi,
+    extends
+        PythonEnvironmentManagerRegistrationApi,
         PythonEnvironmentItemApi,
         PythonEnvironmentManagementApi,
         PythonEnvironmentsApi,
@@ -949,9 +962,10 @@ 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>;
 
     /**
      * Event raised when the list of packages in a Python Environment changes.
@@ -984,7 +998,8 @@ export interface PythonPackageManagementApi {
 }
 
 export interface PythonPackageManagerApi
-    extends PythonPackageManagerRegistrationApi,
+    extends
+        PythonPackageManagerRegistrationApi,
         PythonPackageGetterApi,
         PythonPackageManagementApi,
         PythonPackageItemApi {}
@@ -1203,10 +1218,7 @@ export interface PythonBackgroundRunApi {
 }
 
 export interface PythonExecutionApi
-    extends PythonTerminalCreateApi,
-        PythonTerminalRunApi,
-        PythonTaskRunApi,
-        PythonBackgroundRunApi {}
+    extends PythonTerminalCreateApi, PythonTerminalRunApi, PythonTaskRunApi, PythonBackgroundRunApi {}
 
 /**
  * Event arguments for when the monitored `.env` files or any other sources change.
@@ -1255,7 +1267,8 @@ export interface PythonEnvironmentVariablesApi {
  * The API for interacting with Python environments, package managers, and projects.
  */
 export interface PythonEnvironmentApi
-    extends PythonEnvironmentManagerApi,
+    extends
+        PythonEnvironmentManagerApi,
         PythonPackageManagerApi,
         PythonProjectApi,
         PythonExecutionApi,