feature: Manage package versions from sidebar (microsoft#1511)

<img width="809" height="308" alt="image"
src="https://github.com/user-attachments/assets/70d99115-4825-4d83-946f-e61f45b63e21"
/>

# Feature: Manage package versions from sidebar

This pull request adds a new "Manage Package Version" command to the
Python Envs extension, allowing users to update the version of an
installed package via the UI.

## 1. Select "Manage Package Version" in packages view. 
- Click on the new gear button next to each package to manage versions. 

<img width="659" height="763" alt="image"
src="https://github.com/user-attachments/assets/04a14f4b-93f4-43af-b806-7ff434ce5eec"
/>

- Note that this feature is disabled for transitive packages (microsoft#1530)

<img width="639" height="538" alt="image"
src="https://github.com/user-attachments/assets/f9e8bf02-3ea3-42fd-8795-1793cd7c4b56"
/>



## 2a. Select the desired version
For package managers that support it (conda, uv, pip >= 21.2.0), the
extension fetches all available versions from the index and displays
them in a picker.
<img width="1339" height="804" alt="image"
src="https://github.com/user-attachments/assets/505a3cd6-e7c4-4ba2-a69f-7c9912c4b232"
/>

## 2b. Type the desired version
If the package versions cannot be fetched, the extension prompts the
user to type in the desired version
<img width="1205" height="198" alt="image"
src="https://github.com/user-attachments/assets/94fd322b-e1e0-498a-8c7e-486426924041"
/>

__User is warned if input is not a correct version number.__

<img width="1207" height="206" alt="image"
src="https://github.com/user-attachments/assets/0d7df6e5-55e4-4747-8736-884fdcb835c6"
/>

-------------------------

Fixes microsoft#1368 
Fixes microsoft#512

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

api/package-lock.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/package.json

@@ -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.
  */
@@ -711,6 +713,38 @@ export interface PackageManager {
      * @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 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 this manager does not support version listing.
+     */
+    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;
 }
 
 /**

api/src/main.ts

@@ -282,6 +282,12 @@
                 "category": "Python Envs",
                 "icon": "$(trash)"
             },
+            {
+                "command": "python-envs.managePackageVersion",
+                "title": "%python-envs.managePackageVersion.title%",
+                "category": "Python Envs",
+                "icon": "$(gear)"
+            },
             {
                 "command": "python-envs.copyEnvPath",
                 "title": "%python-envs.copyEnvPath.title%",
@@ -514,6 +520,11 @@
                     "group": "inline",
                     "when": "view == env-managers && viewItem =~ /.*pythonBrokenEnvironment.*/ && viewItem =~ /.*copied.*/"
                 },
+                {
+                    "command": "python-envs.managePackageVersion",
+                    "group": "inline",
+                    "when": "view == env-managers && viewItem == python-package"
+                },
                 {
                     "command": "python-envs.uninstallPackage",
                     "group": "inline",
@@ -556,6 +567,11 @@
                     "command": "python-envs.revealProjectInExplorer",
                     "when": "view == python-projects && viewItem =~ /.*python-workspace.*/"
                 },
+                {
+                    "command": "python-envs.managePackageVersion",
+                    "group": "inline",
+                    "when": "view == python-projects && viewItem == python-package"
+                },
                 {
                     "command": "python-envs.uninstallPackage",
                     "group": "inline",

package-lock.json

@@ -45,5 +45,6 @@
     "python-envs.revealProjectInExplorer.title": "Reveal Project in Explorer",
     "python-envs.revealEnvInManagerView.title": "Reveal in Environment Managers View",
     "python-envs.runPetInTerminal.title": "Run Python Environment Tool (PET) in Terminal...",
+    "python-envs.managePackageVersion.title": "Manage Package Version",
     "python-envs.alwaysUseUv.description": "When set to true, uv will be used to manage all virtual environments if available. When set to false, uv will only manage virtual environments explicitly created by uv."
 }

package.json

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+import type { Pep440Version } from '@renovatebot/pep440';
 import type {
     Disposable,
     Event,
@@ -14,6 +15,8 @@ import type {
     Uri,
 } from 'vscode';
 
+export type { Pep440Version } from '@renovatebot/pep440';
+
 /**
  * The path to an icon, or a theme-specific configuration of icons.
  */
@@ -705,6 +708,37 @@ export interface PackageManager {
      * @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, conda).
+     * @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 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 this manager does not support version listing.
+     */
+    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;
 }
 
 /**

package.nls.json

@@ -50,6 +50,7 @@ import {
     createTerminalCommand,
     getPackageCommandOptions,
     handlePackageUninstall,
+    managePackageVersion,
     refreshPackagesCommand,
     removeEnvironmentCommand,
     removePythonProject,
@@ -320,6 +321,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         commands.registerCommand('python-envs.uninstallPackage', async (context: unknown) => {
             await handlePackageUninstall(context, envManagers);
         }),
+        commands.registerCommand('python-envs.managePackageVersion', async (context: unknown) => {
+            await managePackageVersion(context, envManagers);
+        }),
         commands.registerCommand('python-envs.set', async (item) => {
             await setEnvironmentCommand(item, envManagers, projectManager);
         }),