feat: add project-scoped package managers

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

Author: edvilme

api/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.5.0]
+
+### Added
+
+- Added the optional `PackageManager.createForProject` factory for package managers whose operations depend on the calling Python project.
+
 ## [1.4.0]
 
 ### Changed

api/package-lock.json

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

api/package.json

@@ -1613,6 +1613,7 @@ Reports and changes the packages of an environment.
 | `refresh(environment)` | `(environment: PythonEnvironment) => Promise<void>` | Yes | Re-reads the installed package list. |
 | `getPackages(environment, options?)` | `(environment: PythonEnvironment, options?: GetPackagesOptions) => Promise<Package[] \| undefined>` | Yes | Returns installed packages, or `undefined` if they cannot be retrieved. |
 | `getPackageWatchTargets(environment)` | `(environment: PythonEnvironment) => RelativePattern[]` | No | Extra filesystem patterns to watch for install and uninstall changes, appended to the default site-packages locations. Implement for manager-specific locations such as `conda-meta`. |
+| `createForProject(project)` | `(project: PythonProject) => PackageManager` | No | Creates a manager bound to a project for project-sensitive operations. |
 | `getDirectPackageNames(environment)` | `(environment: PythonEnvironment) => Promise<Set<string> \| undefined>` | No | Best-effort set of non-transitive package names. Most tools cannot record user intent - pip uses `pip list --not-required`, which reports leaf packages rather than explicitly installed ones. |
 | `clearCache()` | `() => Promise<void>` | No | Drops cached package data. |
 | `getVersion(environment)` | `(environment: PythonEnvironment) => Promise<Pep440Version \| undefined>` | No | Version of the underlying tool, such as pip, uv, or conda. |

docs/README.md

@@ -86,6 +86,7 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
             this._onDidChangePythonProjects,
             this._onDidChangePackages,
             this._onDidChangeEnvironmentVariables,
+            this.envManagers.onDidChangePackageProviderPackages((e) => this._onDidChangePackages.fire(e)),
             this.envManagers.onDidChangeActiveEnvironment((e) => {
                 this._onDidChangeEnvironment.fire(e);
                 const location = e.uri?.fsPath ?? 'global';
@@ -295,12 +296,7 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
     }
 
     registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable {
-        const disposables: Disposable[] = [];
-        disposables.push(this.envManagers.registerPackageManager(manager, options));
-        if (manager.onDidChangePackages) {
-            disposables.push(manager.onDidChangePackages((e) => this._onDidChangePackages.fire(e)));
-        }
-        return new Disposable(() => disposables.forEach((d) => d.dispose()));
+        return this.envManagers.registerPackageManager(manager, options);
     }
     async managePackages(context: PythonEnvironment, options: PackageManagementOptions): Promise<void> {
         await waitForEnvManagerId([context.envId.managerId]);

src/extensionApi.ts

@@ -343,7 +343,8 @@ export async function handlePackageUninstall(context: unknown, em: EnvironmentMa
         }
         const moduleName = context.pkg.name;
         const environment = context.parent.environment;
-        const packageManager = em.getPackageManager(environment);
+        const packageManager =
+            context instanceof ProjectPackage ? context.manager : em.getPackageManager(environment);
         await packageManager?.manage(environment, { uninstall: [moduleName], install: [] });
         return;
     }
@@ -358,7 +359,8 @@ export async function managePackageVersion(context: unknown, em: EnvironmentMana
     if (context instanceof PackageTreeItem || context instanceof ProjectPackage) {
         const pkg = context.pkg;
         const environment = context.parent.environment;
-        const packageManager = em.getPackageManager(environment);
+        const packageManager =
+            context instanceof ProjectPackage ? context.manager : em.getPackageManager(environment);
 
         if (!packageManager) {
             return;

src/features/envCommands.ts

@@ -111,6 +111,7 @@ export interface EnvironmentManagers extends Disposable {
      */
     onDidChangeActiveEnvironment: Event<DidChangeEnvironmentEventArgs>;
     onDidChangePackages: Event<InternalDidChangePackagesEventArgs>;
+    onDidChangePackageProviderPackages: Event<DidChangePackagesEventArgs>;
 
     onDidChangeEnvironmentManager: Event<DidChangeEnvironmentManagerEventArgs>;
     onDidChangePackageManager: Event<DidChangePackageManagerEventArgs>;
@@ -171,6 +172,11 @@ function generateId(name: string, extensionId?: string): string {
 export class PythonEnvironmentManagers implements EnvironmentManagers {
     private _environmentManagers: Map<string, InternalEnvironmentManager> = new Map();
     private _packageManagers: Map<string, InternalPackageManager> = new Map();
+    private _projectPackageManagers: Map<string, InternalPackageManager> = new Map();
+    private readonly _packageManagerEventSubscriptions = new Map<
+        string,
+        Map<Event<DidChangePackagesEventArgs>, Disposable>
+    >();
     private readonly subscriptions: Disposable[] = [];
 
     /**
@@ -198,6 +204,7 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
     /** Fires when the active (selected) environment for a scope actually changes. */
     private _onDidChangeActiveEnvironment = new EventEmitter<DidChangeEnvironmentEventArgs>();
     private _onDidChangePackages = new EventEmitter<InternalDidChangePackagesEventArgs>();
+    private _onDidChangePackageProviderPackages = new EventEmitter<DidChangePackagesEventArgs>();
 
     public onDidChangeEnvironmentManager: Event<DidChangeEnvironmentManagerEventArgs> =
         this._onDidChangeEnvironmentManager.event;
@@ -208,6 +215,8 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
     public onDidChangeManagerEnvironment: Event<DidChangeEnvironmentEventArgs> =
         this._onDidChangeManagerEnvironment.event;
     public onDidChangePackages: Event<InternalDidChangePackagesEventArgs> = this._onDidChangePackages.event;
+    public onDidChangePackageProviderPackages: Event<DidChangePackagesEventArgs> =
+        this._onDidChangePackageProviderPackages.event;
 
     /** Fires only when the *selected* manager's environment for a scope actually changes. */
     public onDidChangeActiveEnvironment: Event<DidChangeEnvironmentEventArgs> =
@@ -301,20 +310,9 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
             traceError(ex);
             throw ex;
         }
-        const disposables: Disposable[] = [];
         const mgr = new InternalPackageManager(managerId, manager);
 
-        disposables.push(
-            mgr.onDidChangePackages((e: DidChangePackagesEventArgs) => {
-                setImmediate(() =>
-                    this._onDidChangePackages.fire({
-                        environment: e.environment,
-                        manager: mgr,
-                        changes: e.changes,
-                    }),
-                );
-            }),
-        );
+        this.subscribeToPackageManagerEvents(mgr, mgr);
 
         this._packageManagers.set(managerId, mgr);
         this._onDidChangePackageManager.fire({ kind: 'registered', manager: mgr });
@@ -327,14 +325,23 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
 
         return new Disposable(() => {
             this._packageManagers.delete(managerId);
-            disposables.forEach((d) => d.dispose());
+            for (const [key, scopedManager] of this._projectPackageManagers) {
+                if (scopedManager.id === managerId) {
+                    this._projectPackageManagers.delete(key);
+                }
+            }
+            this.disposePackageManagerEventSubscriptions(managerId);
             setImmediate(() => this._onDidChangePackageManager.fire({ kind: 'unregistered', manager: mgr }));
         });
     }
 
     public dispose() {
         this._environmentManagers.clear();
         this._packageManagers.clear();
+        this._projectPackageManagers.clear();
+        for (const managerId of this._packageManagerEventSubscriptions.keys()) {
+            this.disposePackageManagerEventSubscriptions(managerId);
+        }
         this._inlineRoutingOverrides.clear();
         this.subscriptions.forEach((subscription) => subscription.dispose());
         this._onDidChangeEnvironmentManager.dispose();
@@ -343,6 +350,7 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         this._onDidChangeManagerEnvironment.dispose();
         this._onDidChangeActiveEnvironment.dispose();
         this._onDidChangePackages.dispose();
+        this._onDidChangePackageProviderPackages.dispose();
     }
 
     /**
@@ -407,17 +415,21 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         }
 
         if (context === undefined || context instanceof Uri) {
+            const project = context ? this.pm.get(context) : undefined;
             const defaultPkgManagerId = getDefaultPkgManagerSetting(this.pm, context);
             const defaultEnvManagerId = getDefaultEnvManagerSetting(this.pm, context);
             if (defaultPkgManagerId) {
-                return this._packageManagers.get(defaultPkgManagerId);
+                return this.getProjectPackageManager(this._packageManagers.get(defaultPkgManagerId), project);
             }
 
             if (defaultEnvManagerId) {
                 const preferredPkgManagerId =
                     this._environmentManagers.get(defaultEnvManagerId)?.preferredPackageManagerId;
                 if (preferredPkgManagerId) {
-                    return this._packageManagers.get(preferredPkgManagerId);
+                    return this.getProjectPackageManager(
+                        this._packageManagers.get(preferredPkgManagerId),
+                        project,
+                    );
                 }
             }
             return undefined;
@@ -439,6 +451,69 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         return undefined;
     }
 
+    private getProjectPackageManager(
+        manager: InternalPackageManager | undefined,
+        project: PythonProject | undefined,
+    ): InternalPackageManager | undefined {
+        if (!manager || !project) {
+            return manager;
+        }
+
+        const key = `${manager.id}:${normalizePath(project.uri.fsPath)}`;
+        let scopedManager = this._projectPackageManagers.get(key);
+        if (!scopedManager) {
+            scopedManager = manager.createProjectScopedManager(project);
+            if (scopedManager) {
+                this._projectPackageManagers.set(key, scopedManager);
+                this.subscribeToPackageManagerEvents(manager, scopedManager);
+            }
+        }
+        return scopedManager ?? manager;
+    }
+
+    private subscribeToPackageManagerEvents(
+        provider: InternalPackageManager,
+        manager: InternalPackageManager,
+    ): void {
+        const event = manager.packageChangeEvent;
+        if (!event) {
+            return;
+        }
+
+        let subscriptions = this._packageManagerEventSubscriptions.get(provider.id);
+        if (!subscriptions) {
+            subscriptions = new Map();
+            this._packageManagerEventSubscriptions.set(provider.id, subscriptions);
+        }
+        if (subscriptions.has(event)) {
+            return;
+        }
+
+        subscriptions.set(
+            event,
+            event((e) => {
+                this._onDidChangePackageProviderPackages.fire(e);
+                const eventManager =
+                    Array.from(this._projectPackageManagers.values()).find(
+                        (candidate) => candidate.id === provider.id && candidate.wraps(e.manager),
+                    ) ?? provider;
+                setImmediate(() =>
+                    this._onDidChangePackages.fire({
+                        environment: e.environment,
+                        manager: eventManager,
+                        changes: e.changes,
+                    }),
+                );
+            }),
+        );
+    }
+
+    private disposePackageManagerEventSubscriptions(managerId: string): void {
+        const subscriptions = this._packageManagerEventSubscriptions.get(managerId);
+        subscriptions?.forEach((subscription) => subscription.dispose());
+        this._packageManagerEventSubscriptions.delete(managerId);
+    }
+
     public get managers(): InternalEnvironmentManager[] {
         return Array.from(this._environmentManagers.values());
     }

src/features/envManagers.ts

@@ -153,7 +153,9 @@ export function registerPackageWatchers(
             return;
         }
 
-        const watcherKey = `${environment.envId.managerId}:${environment.envId.id}:${selectedPackageManager.id}`;
+        const packageManagerKey =
+            `${selectedPackageManager.id}:${selectedPackageManager.project?.uri.toString() ?? ''}`;
+        const watcherKey = `${environment.envId.managerId}:${environment.envId.id}:${packageManagerKey}`;
         if (activeWatcherByConsumer.get(consumer) === watcherKey) {
             return;
         }

src/managers/common/packageWatcher.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import type { Pep440Version } from '@renovatebot/pep440';
-import { CancellationError, Disposable, LogOutputChannel, MarkdownString, RelativePattern } from 'vscode';
+import { CancellationError, Disposable, Event, LogOutputChannel, MarkdownString, RelativePattern } from 'vscode';
 import { PackageVersionLookupNotSupportedError } from '../../publicErrors';
 import { ISSUES_URL } from '../../common/constants';
 import { CreateEnvironmentNotSupported, RemoveEnvironmentNotSupported } from '../../common/errors/NotSupportedError';
@@ -27,6 +27,7 @@ import type {
     PackageManagementOptions,
     PackageManager,
     PythonEnvironment,
+    PythonProject,
     QuickCreateConfig,
     RefreshEnvironmentsScope,
     RemoveEnvironmentOptions,
@@ -210,10 +211,17 @@ function inferPackageManagementTrigger(
 }
 
 export class InternalPackageManager implements PackageManager {
+    private readonly relatedManagers: WeakSet<PackageManager>;
+
     public constructor(
         public readonly id: string,
         private readonly manager: PackageManager,
-    ) {}
+        public readonly project?: PythonProject,
+        relatedManagers?: WeakSet<PackageManager>,
+    ) {
+        this.relatedManagers = relatedManagers ?? new WeakSet<PackageManager>();
+        this.relatedManagers.add(manager);
+    }
 
     public get name(): string {
         return this.manager.name;
@@ -279,10 +287,23 @@ export class InternalPackageManager implements PackageManager {
         return this.manager.onDidChangePackages ? this.manager.onDidChangePackages(handler) : new Disposable(() => {});
     }
 
-    equals(other: PackageManager): boolean {
+    get packageChangeEvent(): Event<DidChangePackagesEventArgs> | undefined {
+        return this.manager.onDidChangePackages;
+    }
+
+    wraps(other: PackageManager): boolean {
         return this.manager === other;
     }
 
+    equals(other: PackageManager): boolean {
+        return this.relatedManagers.has(other);
+    }
+
+    createProjectScopedManager(project: PythonProject): InternalPackageManager | undefined {
+        const manager = this.manager.createForProject?.(project);
+        return manager ? new InternalPackageManager(this.id, manager, project, this.relatedManagers) : undefined;
+    }
+
     getVersion(environment: PythonEnvironment): Promise<Pep440Version | undefined> {
         return this.manager.getVersion ? this.manager.getVersion(environment) : Promise.resolve(undefined);
     }