feat: improve package management (#279)

⚠️ BREAKING CHANGE: This PR has an API change that replaces `install`
and `uninstall` methods on package manager with `manage`.

Reasoning: Both the install and uninstall flows did very similar things.
In all the implementations this was duplicating the steps. The idea here
is to make it easier from the flow perspective.


![image](https://github.com/user-attachments/assets/53087fca-ddc9-44f4-bcb9-9b005264db56)

Author: karthiknadig

examples/sample1/src/api.ts

@@ -48,23 +48,6 @@ export interface PythonCommandRunConfiguration {
     args?: string[];
 }
 
-export enum TerminalShellType {
-    powershell = 'powershell',
-    powershellCore = 'powershellCore',
-    commandPrompt = 'commandPrompt',
-    gitbash = 'gitbash',
-    bash = 'bash',
-    zsh = 'zsh',
-    ksh = 'ksh',
-    fish = 'fish',
-    cshell = 'cshell',
-    tcshell = 'tcshell',
-    nushell = 'nushell',
-    wsl = 'wsl',
-    xonsh = 'xonsh',
-    unknown = 'unknown',
-}
-
 /**
  * Contains details on how to use a particular python environment
  *
@@ -73,7 +56,7 @@ export enum TerminalShellType {
  * 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:
- *     - {@link TerminalShellType.unknown} will be used if provided.
+ *     - '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.
@@ -82,7 +65,7 @@ export enum TerminalShellType {
  * 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:
- *     - {@link TerminalShellType.unknown} will be used if provided.
+ *     - '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.
  *
@@ -107,11 +90,11 @@ export interface PythonEnvironmentExecutionInfo {
     /**
      * Details on how to activate an environment using a shell specific command.
      * If set this will override the {@link PythonEnvironmentExecutionInfo.activation}.
-     * {@link TerminalShellType.unknown} is used if shell type is not known.
-     * If {@link TerminalShellType.unknown} is not provided and shell type is not known then
+     * '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<TerminalShellType, PythonCommandRunConfiguration[]>;
+    shellActivation?: Map<string, PythonCommandRunConfiguration[]>;
 
     /**
      * Details on how to deactivate an environment.
@@ -121,11 +104,11 @@ export interface PythonEnvironmentExecutionInfo {
     /**
      * Details on how to deactivate an environment using a shell specific command.
      * If set this will override the {@link PythonEnvironmentExecutionInfo.deactivation} property.
-     * {@link TerminalShellType.unknown} is used if shell type is not known.
-     * If {@link TerminalShellType.unknown} is not provided and shell type is not known then
+     * '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<TerminalShellType, PythonCommandRunConfiguration[]>;
+    shellDeactivation?: Map<string, PythonCommandRunConfiguration[]>;
 }
 
 /**
@@ -592,20 +575,12 @@ export interface PackageManager {
     log?: LogOutputChannel;
 
     /**
-     * Installs packages in the specified Python environment.
+     * Installs/Uninstall packages in the specified Python environment.
      * @param environment - The Python environment in which to install packages.
      * @param packages - The packages to install.
      * @returns A promise that resolves when the installation is complete.
      */
-    install(environment: PythonEnvironment, packages?: string[], options?: PackageInstallOptions): Promise<void>;
-
-    /**
-     * Uninstalls packages from the specified Python environment.
-     * @param environment - The Python environment from which to uninstall packages.
-     * @param packages - The packages to uninstall, which can be an array of packages or strings.
-     * @returns A promise that resolves when the uninstall is complete.
-     */
-    uninstall(environment: PythonEnvironment, packages?: Package[] | string[]): Promise<void>;
+    manage(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
 
     /**
      * Refreshes the package list for the specified Python environment.
@@ -730,15 +705,47 @@ export interface DidChangePythonProjectsEventArgs {
     removed: PythonProject[];
 }
 
-/**
- * Options for package installation.
- */
-export interface PackageInstallOptions {
-    /**
-     * Upgrade the packages if it is already installed.
-     */
-    upgrade?: boolean;
-}
+export type PackageManagementOptions =
+    | {
+          /**
+           * Upgrade the packages if it is already installed.
+           */
+          upgrade?: boolean;
+
+          /**
+           * Show option to skip package installation
+           */
+          showSkipOption?: boolean;
+          /**
+           * The list of packages to install.
+           */
+          install: string[];
+
+          /**
+           * The list of packages to uninstall.
+           */
+          uninstall?: string[];
+      }
+    | {
+          /**
+           * Upgrade the packages if it is already installed.
+           */
+          upgrade?: boolean;
+
+          /**
+           * Show option to skip package installation
+           */
+          showSkipOption?: boolean;
+          /**
+           * The list of packages to install.
+           */
+          install?: string[];
+
+          /**
+           * The list of packages to uninstall.
+           */
+          uninstall: string[];
+      };
 
 export interface PythonProcess {
     /**
@@ -921,21 +928,13 @@ export interface PythonPackageItemApi {
 
 export interface PythonPackageManagementApi {
     /**
-     * Install packages into a Python Environment.
+     * Install/Uninstall packages into a Python Environment.
      *
      * @param environment The Python Environment into which packages are to be installed.
      * @param packages The packages to install.
      * @param options Options for installing packages.
      */
-    installPackages(environment: PythonEnvironment, packages: string[], options?: PackageInstallOptions): Promise<void>;
-
-    /**
-     * Uninstall packages from a Python Environment.
-     *
-     * @param environment The Python Environment from which packages are to be uninstalled.
-     * @param packages The packages to uninstall.
-     */
-    uninstallPackages(environment: PythonEnvironment, packages: PackageInfo[] | string[]): Promise<void>;
+    managePackages(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
 }
 
 export interface PythonPackageManagerApi

package-lock.json

@@ -6,13 +6,12 @@
     "publisher": "ms-python",
     "preview": true,
     "engines": {
-        "vscode": "^1.99.0-20250317"
+        "vscode": "^1.100.0-20250407"
     },
     "categories": [
         "Other"
     ],
     "enabledApiProposals": [
-        "terminalShellType",
         "terminalShellEnv"
     ],
     "capabilities": {
@@ -142,7 +141,6 @@
             {
                 "command": "python-envs.reset",
                 "title": "%python-envs.reset.title%",
-                "shortTitle": "Reset Environment",
                 "category": "Python",
                 "icon": "$(sync)"
             },
@@ -174,7 +172,6 @@
             {
                 "command": "python-envs.packages",
                 "title": "%python-envs.packages.title%",
-                "shortTitle": "Modify Packages",
                 "category": "Python",
                 "icon": "$(package)"
             },
@@ -534,7 +531,7 @@
         "@types/node": "20.2.5",
         "@types/sinon": "^17.0.3",
         "@types/stack-trace": "0.0.29",
-        "@types/vscode": "^1.97.0",
+        "@types/vscode": "^1.99.0",
         "@types/which": "^3.0.4",
         "@typescript-eslint/eslint-plugin": "^8.16.0",
         "@typescript-eslint/parser": "^8.16.0",

package.json

@@ -16,12 +16,12 @@
     "python-envs.createAny.title": "Create Environment",
     "python-envs.set.title": "Set Workspace Environment",
     "python-envs.setEnv.title": "Set As Workspace Environment",
-    "python-envs.reset.title": "Reset Environment Selection to Default",
+    "python-envs.reset.title": "Reset to Default",
     "python-envs.remove.title": "Delete Environment",
     "python-envs.refreshAllManagers.title": "Refresh All Environment Managers",
     "python-envs.refreshManager.title": "Refresh Environments List",
     "python-envs.refreshPackages.title": "Refresh Packages List",
-    "python-envs.packages.title": "Install or Remove Packages",
+    "python-envs.packages.title": "Manage Packages",
     "python-envs.clearCache.title": "Clear Cache",
     "python-envs.runInTerminal.title": "Run in Terminal",
     "python-envs.createTerminal.title": "Create Python Terminal",

package.nls.json

@@ -575,20 +575,12 @@ export interface PackageManager {
     log?: LogOutputChannel;
 
     /**
-     * Installs packages in the specified Python environment.
+     * Installs/Uninstall packages in the specified Python environment.
      * @param environment - The Python environment in which to install packages.
      * @param packages - The packages to install.
      * @returns A promise that resolves when the installation is complete.
      */
-    install(environment: PythonEnvironment, packages?: string[], options?: PackageInstallOptions): Promise<void>;
-
-    /**
-     * Uninstalls packages from the specified Python environment.
-     * @param environment - The Python environment from which to uninstall packages.
-     * @param packages - The packages to uninstall, which can be an array of packages or strings.
-     * @returns A promise that resolves when the uninstall is complete.
-     */
-    uninstall(environment: PythonEnvironment, packages?: Package[] | string[]): Promise<void>;
+    manage(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
 
     /**
      * Refreshes the package list for the specified Python environment.
@@ -713,20 +705,47 @@ export interface DidChangePythonProjectsEventArgs {
     removed: PythonProject[];
 }
 
-/**
- * Options for package installation.
- */
-export interface PackageInstallOptions {
-    /**
-     * Upgrade the packages if it is already installed.
-     */
-    upgrade?: boolean;
+export type PackageManagementOptions =
+    | {
+          /**
+           * Upgrade the packages if it is already installed.
+           */
+          upgrade?: boolean;
 
-    /**
-     * Show option to skip package installation
-     */
-    showSkipOption?: boolean;
-}
+          /**
+           * Show option to skip package installation
+           */
+          showSkipOption?: boolean;
+          /**
+           * The list of packages to install.
+           */
+          install: string[];
+
+          /**
+           * The list of packages to uninstall.
+           */
+          uninstall?: string[];
+      }
+    | {
+          /**
+           * Upgrade the packages if it is already installed.
+           */
+          upgrade?: boolean;
+
+          /**
+           * Show option to skip package installation
+           */
+          showSkipOption?: boolean;
+          /**
+           * The list of packages to install.
+           */
+          install?: string[];
+
+          /**
+           * The list of packages to uninstall.
+           */
+          uninstall: string[];
+      };
 
 export interface PythonProcess {
     /**
@@ -909,21 +928,13 @@ export interface PythonPackageItemApi {
 
 export interface PythonPackageManagementApi {
     /**
-     * Install packages into a Python Environment.
+     * Install/Uninstall packages into a Python Environment.
      *
      * @param environment The Python Environment into which packages are to be installed.
      * @param packages The packages to install.
      * @param options Options for installing packages.
      */
-    installPackages(environment: PythonEnvironment, packages: string[], options?: PackageInstallOptions): Promise<void>;
-
-    /**
-     * Uninstall packages from a Python Environment.
-     *
-     * @param environment The Python Environment from which packages are to be uninstalled.
-     * @param packages The packages to uninstall.
-     */
-    uninstallPackages(environment: PythonEnvironment, packages: PackageInfo[] | string[]): Promise<void>;
+    managePackages(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;
 }
 
 export interface PythonPackageManagerApi