Distinguish between direct and transitive packages (#1530)

This pull request attempts to identify transitive packages in the user
environment, and show indicators in the UI.

Author: edvilme

api/src/main.ts

@@ -578,6 +578,11 @@ export interface PackageInfo {
      * The URIs associated with the package.
      */
     readonly uris?: readonly Uri[];
+
+    /**
+     * Whether the package is a transitive dependency.
+     */
+    readonly isTransitive?: boolean;
 }
 
 /**
@@ -670,9 +675,9 @@ export interface PackageManager {
     /**
      * Refreshes the package list for the specified Python environment.
      * @param environment - The Python environment for which to refresh the package list.
-     * @returns A promise that resolves when the refresh is complete.
+     * @returns A promise that resolves with the refreshed list of packages, or undefined.
      */
-    refresh(environment: PythonEnvironment): Promise<void>;
+    refresh(environment: PythonEnvironment): Promise<Package[] | undefined>;
 
     /**
      * Retrieves the list of packages for the specified Python environment.
@@ -687,6 +692,20 @@ export interface PackageManager {
      */
     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.
@@ -1029,9 +1048,9 @@ export interface PythonPackageGetterApi {
      * Refresh the list of packages in a Python Environment.
      *
      * @param environment The Python Environment for which the list of packages is to be refreshed.
-     * @returns A promise that resolves when the list of packages has been refreshed.
+     * @returns A promise that resolves with the refreshed list of packages, or undefined.
      */
-    refreshPackages(environment: PythonEnvironment): Promise<void>;
+    refreshPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
 
     /**
      * Get the list of packages in a Python Environment.

src/api.ts

@@ -572,6 +572,11 @@ export interface PackageInfo {
      * The URIs associated with the package.
      */
     readonly uris?: readonly Uri[];
+
+    /**
+     * Whether the package is a transitive dependency.
+     */
+    readonly isTransitive?: boolean;
 }
 
 /**
@@ -664,9 +669,9 @@ export interface PackageManager {
     /**
      * Refreshes the package list for the specified Python environment.
      * @param environment - The Python environment for which to refresh the package list.
-     * @returns A promise that resolves when the refresh is complete.
+     * @returns A promise that resolves with the refreshed list of packages, or undefined.
      */
-    refresh(environment: PythonEnvironment): Promise<void>;
+    refresh(environment: PythonEnvironment): Promise<Package[] | undefined>;
 
     /**
      * Retrieves the list of packages for the specified Python environment.
@@ -681,6 +686,20 @@ export interface PackageManager {
      */
     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.
@@ -1023,9 +1042,9 @@ export interface PythonPackageGetterApi {
      * Refresh the list of packages in a Python Environment.
      *
      * @param environment The Python Environment for which the list of packages is to be refreshed.
-     * @returns A promise that resolves when the list of packages has been refreshed.
+     * @returns A promise that resolves with the refreshed list of packages, or undefined.
      */
-    refreshPackages(environment: PythonEnvironment): Promise<void>;
+    refreshPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
 
     /**
      * Get the list of packages in a Python Environment.

src/features/envCommands.ts

@@ -305,6 +305,20 @@ export async function removeEnvironmentCommand(context: unknown, managers: Envir
 
 export async function handlePackageUninstall(context: unknown, em: EnvironmentManagers) {
     if (context instanceof PackageTreeItem || context instanceof ProjectPackage) {
+        if (context.pkg.isTransitive) {
+            const confirm = await showInformationMessage(
+                l10n.t(
+                    'The package "{0}" is a transitive dependency. Uninstalling it may break other packages that depend on it.',
+                    context.pkg.name,
+                ),
+                { modal: true },
+                l10n.t('Uninstall Anyway'),
+                l10n.t('Cancel'),
+            );
+            if (confirm !== l10n.t('Uninstall Anyway')) {
+                return;
+            }
+        }
         const moduleName = context.pkg.name;
         const environment = context instanceof ProjectPackage ? context.parent.environment : context.parent.environment;
         const packageManager = em.getPackageManager(environment);

src/features/pythonApi.ts

@@ -250,7 +250,7 @@ class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         }
         return manager.manage(context, options);
     }
-    async refreshPackages(context: PythonEnvironment): Promise<void> {
+    async refreshPackages(context: PythonEnvironment): Promise<Package[] | undefined> {
         await waitForEnvManagerId([context.envId.managerId]);
         const manager = this.envManagers.getPackageManager(context);
         if (!manager) {

src/features/views/envManagersView.ts

@@ -252,9 +252,13 @@ export class EnvManagerView implements TreeDataProvider<EnvTreeItem>, Disposable
             const views: EnvTreeItem[] = [];
 
             if (pkgManager) {
-                const packages = await pkgManager.getPackages(environment);
+                let packages = await pkgManager.refresh(environment);
                 if (packages && packages.length > 0) {
-                    views.push(...packages.map((p) => new PackageTreeItem(p, parent, pkgManager)));
+                    views.push(
+                        ...packages
+                            .sort((a, b) => (a.isTransitive === b.isTransitive ? 0 : a.isTransitive ? 1 : -1))
+                            .map((p) => new PackageTreeItem(p, parent, pkgManager)),
+                    );
                 } else {
                     views.push(new EnvInfoTreeItem(parent, ProjectViews.noPackages));
                 }

src/features/views/projectView.ts

@@ -244,7 +244,7 @@ export class ProjectView implements TreeDataProvider<ProjectTreeItem> {
                 return [new ProjectEnvironmentInfo(environmentItem, ProjectViews.noPackageManager)];
             }
 
-            let packages = await pkgManager.getPackages(environment);
+            let packages = await pkgManager.refresh(environment);
             if (!packages) {
                 return [new ProjectEnvironmentInfo(environmentItem, ProjectViews.noPackages)];
             }

src/features/views/treeViewItems.ts

@@ -1,4 +1,4 @@
-import { Command, MarkdownString, ThemeIcon, TreeItem, TreeItemCollapsibleState } from 'vscode';
+import { Command, MarkdownString, ThemeIcon, TreeItem, TreeItemCollapsibleState, l10n } from 'vscode';
 import { EnvironmentGroupInfo, IconPath, Package, PythonEnvironment, PythonProject } from '../../api';
 import { EnvViewStrings, UvInstallStrings, VenvManagerStrings } from '../../common/localize';
 import { InternalEnvironmentManager, InternalPackageManager } from '../../internal.api';
@@ -210,10 +210,13 @@ export class PackageTreeItem implements EnvTreeItem {
         public readonly manager: InternalPackageManager,
     ) {
         const item = new TreeItem(pkg.displayName);
-        item.iconPath = pkg.iconPath;
-        item.contextValue = 'python-package';
-        item.description = pkg.description ?? pkg.version;
-        item.tooltip = pkg.tooltip;
+        const defaultIcon = pkg.isTransitive ? new ThemeIcon('list-tree') : new ThemeIcon('package');
+        item.iconPath = pkg.iconPath ?? defaultIcon;
+        item.contextValue = pkg.isTransitive ? 'python-package-transitive' : 'python-package';
+        item.description = (pkg.isTransitive ? l10n.t('(transitive) ') : '') + (pkg.description ?? pkg.version);
+        item.tooltip = pkg.isTransitive
+            ? l10n.t('This package is a dependency of another installed package. It may also have been explicitly installed.')
+            : pkg.tooltip;
         this.treeItem = item;
     }
 }
@@ -431,7 +434,7 @@ export class ProjectPackage implements ProjectTreeItem {
         this.id = ProjectPackage.getId(parent, pkg);
         const item = new TreeItem(this.pkg.displayName, TreeItemCollapsibleState.None);
         item.iconPath = this.pkg.iconPath;
-        item.contextValue = 'python-package';
+        item.contextValue = this.pkg.isTransitive ? 'python-package-transitive' : 'python-package';
         item.description = this.pkg.description ?? this.pkg.version;
         item.tooltip = this.pkg.tooltip;
         this.treeItem = item;

src/internal.api.ts

@@ -364,7 +364,7 @@ export class InternalPackageManager implements PackageManager {
         }
     }
 
-    refresh(environment: PythonEnvironment): Promise<void> {
+    refresh(environment: PythonEnvironment): Promise<Package[] | undefined> {
         return this.manager.refresh(environment);
     }
 
@@ -446,6 +446,8 @@ export class PythonPackageImpl implements Package {
     public readonly iconPath?: IconPath;
     public readonly uris?: readonly Uri[];
 
+    public readonly isTransitive?: boolean;
+
     constructor(
         public readonly pkgId: PackageId,
         info: PackageInfo,
@@ -457,6 +459,7 @@ export class PythonPackageImpl implements Package {
         this.tooltip = info.tooltip;
         this.iconPath = info.iconPath;
         this.uris = info.uris;
+        this.isTransitive = info.isTransitive;
     }
 }
 

src/managers/builtin/pipListUtils.ts

@@ -1,11 +1,20 @@
+import { LogOutputChannel } from 'vscode';
+
 export interface PipPackage {
     name: string;
     version: string;
     displayName: string;
     description: string;
 }
+export function parseUvTree(data: string): string[] {
+    return data
+        .split('\n')
+        .map((line) => line.trim())
+        .map((line) => line.split(/\s+/, 1)[0])
+        .filter((name) => !!name);
+}
 
-export function parsePipListJson(data: string): PipPackage[] {
+export function parsePipListJson(data: string, log?: LogOutputChannel): PipPackage[] {
     try {
         const json = JSON.parse(data);
         if (Array.isArray(json)) {
@@ -18,8 +27,8 @@ export function parsePipListJson(data: string): PipPackage[] {
                     description: version,
                 }));
         }
-    } catch (_) {
-        // If JSON parsing fails, return an empty array. The caller can decide how to handle this case.
+    } catch (ex) {
+        log?.error('Failed to parse pip list JSON output', ex);
     }
     return [];
 }

src/managers/builtin/pipPackageManager.ts

@@ -21,7 +21,7 @@ import {
 } from '../../api';
 import { updatePackagesAndNotify } from '../common/packageChanges';
 import { getWorkspacePackagesToInstall } from './pipUtils';
-import { managePackages, refreshPipPackages } from './utils';
+import { managePackages, normalizePackageName, refreshPipDirectPackageNames, refreshPipPackages } from './utils';
 import { VenvManager } from './venvManager';
 
 export class PipPackageManager implements PackageManager, Disposable {
@@ -101,16 +101,21 @@ export class PipPackageManager implements PackageManager, Disposable {
         );
     }
 
-    async refresh(environment: PythonEnvironment): Promise<void> {
-        await window.withProgress(
+    async refresh(environment: PythonEnvironment): Promise<Package[] | undefined> {
+        return window.withProgress(
             {
                 location: ProgressLocation.Window,
                 title: 'Refreshing packages',
             },
             async () => {
-                await updatePackagesAndNotify(this, environment, this.packages.get(environment.envId.id), (changes) => {
-                    this._onDidChangePackages.fire({ environment, manager: this, changes });
-                });
+                return updatePackagesAndNotify(
+                    this,
+                    environment,
+                    this.packages.get(environment.envId.id),
+                    (changes) => {
+                        this._onDidChangePackages.fire({ environment, manager: this, changes });
+                    },
+                );
             },
         );
     }
@@ -129,4 +134,15 @@ export class PipPackageManager implements PackageManager, Disposable {
         this._onDidChangePackages.dispose();
         this.packages.clear();
     }
+
+    /**
+     * Returns direct (non-transitive) package names using `pip list --not-required` or `uv pip tree --depth=0`.
+     *
+     * Note: These commands return packages with no installed dependents (leaf packages), not packages
+     * the user explicitly installed. pip/uv do not track install intent.
+     */
+    async getDirectPackageNames(environment: PythonEnvironment): Promise<Set<string> | undefined> {
+        const data = await refreshPipDirectPackageNames(environment, this.log);
+        return data ? new Set(data.map(normalizePackageName)) : undefined;
+    }
 }