Merge branch 'main' into notebook-path-fix

Author: eleanorjboyd

README.md

@@ -12,7 +12,6 @@ The Python Environments and Package Manager extension for VS Code helps you mana
 
 <img src=https://raw.githubusercontent.com/microsoft/vscode-python-environments/main/images/python-envs-overview.gif width=734 height=413>
 
-
 ### Environment Management
 
 This extension provides an Environments view, which can be accessed via the VS Code Activity Bar, where you can manage your Python environments. Here, you can create, delete, and switch between environments, as well as install and uninstall packages within the selected environment. It also provides APIs for extension developers to contribute their own environment managers.
@@ -54,19 +53,44 @@ See [api.ts](https://github.com/microsoft/vscode-python-environments/blob/main/s
 To consume these APIs you can look at the example here:
 https://github.com/microsoft/vscode-python-environments/blob/main/examples/README.md
 
+### Callable Commands
+
+The extension provides a set of callable commands that can be used to interact with the environment and package managers. These commands can be invoked from other extensions or from the command palette.
+
+#### `python-envs.createAny`
+
+Create a new environment using any of the available environment managers. This command will prompt the user to select the environment manager to use. Following options are available on this command:
+
+```typescript
+{
+    /**
+     * Default `false`. If `true` the creation provider should show back button when showing QuickPick or QuickInput.
+     */
+    showBackButton?: boolean;
+
+    /**
+     * Default `true`. If `true`, the environment after creation will be selected.
+     */
+    selectEnvironment?: boolean;
+}
+```
+
+usage: `await vscode.commands.executeCommand('python-envs.createAny', options);`
 
 ## Extension Dependency
 
-This section provides an overview of how the Python extension interacts with the Python Environments extension and other tool-specific extensions. The Python Environments extension allows users to create, manage, and remove Python environments and packages. It also provides an API that other extensions can use to support environment management or consume it for running Python tools or projects.  
+This section provides an overview of how the Python extension interacts with the Python Environments extension and other tool-specific extensions. The Python Environments extension allows users to create, manage, and remove Python environments and packages. It also provides an API that other extensions can use to support environment management or consume it for running Python tools or projects.
 
 Tools that may rely on these APIs in their own extensions include:
-- **Debuggers** (e.g., `debugpy`)
-- **Linters** (e.g., Pylint, Flake8, Mypy)
-- **Formatters** (e.g., Black, autopep8)
-- **Language Server extensions** (e.g., Pylance, Jedi)
-- **Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
+
+-   **Debuggers** (e.g., `debugpy`)
+-   **Linters** (e.g., Pylint, Flake8, Mypy)
+-   **Formatters** (e.g., Black, autopep8)
+-   **Language Server extensions** (e.g., Pylance, Jedi)
+-   **Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
 
 ### API Dependency
+
 The relationship between these extensions can be represented as follows:
 
 <img src=https://raw.githubusercontent.com/microsoft/vscode-python-environments/refs/heads/main/images/extension_relationships.png width=734 height=413>
@@ -75,7 +99,7 @@ Users who do not need to execute code or work in **Virtual Workspaces** can use
 
 ### Trust Relationship Between Python and Python Environments Extensions
 
-VS Code supports trust management, allowing extensions to function in either **trusted** or **untrusted** scenarios. Code execution and tools that can modify the user’s environment are typically unavailable in untrusted scenarios.  
+VS Code supports trust management, allowing extensions to function in either **trusted** or **untrusted** scenarios. Code execution and tools that can modify the user’s environment are typically unavailable in untrusted scenarios.
 
 The relationship is illustrated below:
 

src/api.ts

@@ -596,7 +596,7 @@ export interface PackageManager {
     /**
      * Installs/Uninstall packages in the specified Python environment.
      * @param environment - The Python environment in which to install packages.
-     * @param packages - The packages to install.
+     * @param options - Options for managing packages.
      * @returns A promise that resolves when the installation is complete.
      */
     manage(environment: PythonEnvironment, options: PackageManagementOptions): Promise<void>;

src/common/pickers/managers.ts

@@ -21,6 +21,7 @@ function getDescription(mgr: InternalEnvironmentManager | InternalPackageManager
 export async function pickEnvironmentManager(
     managers: InternalEnvironmentManager[],
     defaultManagers?: InternalEnvironmentManager[],
+    showBackButton?: boolean,
 ): Promise<string | undefined> {
     if (managers.length === 0) {
         return;
@@ -72,6 +73,7 @@ export async function pickEnvironmentManager(
     const item = await showQuickPickWithButtons(items, {
         placeHolder: Pickers.Managers.selectEnvironmentManager,
         ignoreFocusOut: true,
+        showBackButton,
     });
     return (item as QuickPickItem & { id: string })?.id;
 }

src/common/telemetry/constants.ts

@@ -4,9 +4,13 @@ export enum EventNames {
 
     ENVIRONMENT_MANAGER_REGISTERED = 'ENVIRONMENT_MANAGER.REGISTERED',
     PACKAGE_MANAGER_REGISTERED = 'PACKAGE_MANAGER.REGISTERED',
+    ENVIRONMENT_MANAGER_SELECTED = 'ENVIRONMENT_MANAGER.SELECTED',
+    PACKAGE_MANAGER_SELECTED = 'PACKAGE_MANAGER.SELECTED',
 
     VENV_USING_UV = 'VENV.USING_UV',
     VENV_CREATION = 'VENV.CREATION',
+
+    PACKAGE_MANAGEMENT = 'PACKAGE_MANAGEMENT',
 }
 
 // Map all events to their properties
@@ -43,16 +47,43 @@ export interface IEventNamePropertyMapping {
     };
 
     /* __GDPR__
-        "venv.using_uv": {"owner": "karthiknadig" }
+        "environment_manager.selected": {
+            "managerId" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "karthiknadig" }
+        }
+    */
+    [EventNames.ENVIRONMENT_MANAGER_SELECTED]: {
+        managerId: string;
+    };
+
+    /* __GDPR__
+        "package_manager.selected": {
+            "managerId" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "karthiknadig" }
+        }
     */
-    [EventNames.VENV_USING_UV]: never | undefined;
+    [EventNames.PACKAGE_MANAGER_SELECTED]: {
+        managerId: string;
+    };
 
     /* __GDPR__
+        "venv.using_uv": {"owner": "karthiknadig" }
+    */
+    [EventNames.VENV_USING_UV]: never | undefined /* __GDPR__
         "venv.creation": {
             "creationType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "karthiknadig" }
         }
-    */
+    */;
     [EventNames.VENV_CREATION]: {
         creationType: 'quick' | 'custom';
     };
+
+    /* __GDPR__
+        "package.install": {
+            "managerId": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "karthiknadig" },
+            "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "karthiknadig" }
+        }
+    */
+    [EventNames.PACKAGE_MANAGEMENT]: {
+        managerId: string;
+        result: 'success' | 'error' | 'cancelled';
+    };
 }

src/common/telemetry/helpers.ts

@@ -0,0 +1,28 @@
+import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../../features/settings/settingHelpers';
+import { PythonProjectManager } from '../../internal.api';
+import { EventNames } from './constants';
+import { sendTelemetryEvent } from './sender';
+
+export function sendManagerSelectionTelemetry(pm: PythonProjectManager) {
+    const ems: Set<string> = new Set();
+    const ps: Set<string> = new Set();
+    pm.getProjects().forEach((project) => {
+        const m = getDefaultEnvManagerSetting(pm, project.uri);
+        if (m) {
+            ems.add(m);
+        }
+
+        const p = getDefaultPkgManagerSetting(pm, project.uri);
+        if (p) {
+            ps.add(p);
+        }
+    });
+
+    ems.forEach((em) => {
+        sendTelemetryEvent(EventNames.ENVIRONMENT_MANAGER_SELECTED, undefined, { managerId: em });
+    });
+
+    ps.forEach((pkg) => {
+        sendTelemetryEvent(EventNames.PACKAGE_MANAGER_SELECTED, undefined, { managerId: pkg });
+    });
+}

src/extension.ts

@@ -1,7 +1,7 @@
 import { commands, ExtensionContext, LogOutputChannel, Terminal, Uri } from 'vscode';
 
 import { PythonEnvironmentManagers } from './features/envManagers';
-import { registerLogger, traceInfo } from './common/logging';
+import { registerLogger, traceError, traceInfo } from './common/logging';
 import { EnvManagerView } from './features/views/envManagersView';
 import {
     addPythonProject,
@@ -56,6 +56,7 @@ import { registerTools } from './common/lm.apis';
 import { GetEnvironmentInfoTool, InstallPackageTool } from './features/copilotTools';
 import { TerminalActivationImpl } from './features/terminal/terminalActivationState';
 import { getEnvironmentForTerminal } from './features/terminal/utils';
+import { sendManagerSelectionTelemetry } from './common/telemetry/helpers';
 
 export async function activate(context: ExtensionContext): Promise<PythonEnvironmentApi> {
     const start = new StopWatch();
@@ -88,7 +89,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
     const projectCreators: ProjectCreators = new ProjectCreatorsImpl();
     context.subscriptions.push(
         projectCreators,
-        projectCreators.registerPythonProjectCreator(new ExistingProjects()),
+        projectCreators.registerPythonProjectCreator(new ExistingProjects(projectManager)),
         projectCreators.registerPythonProjectCreator(new AutoFindProjects(projectManager)),
     );
 
@@ -138,7 +139,11 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 envManagers,
                 projectManager,
             );
-            packageManager.manage(environment, { install: [] });
+            try {
+                packageManager.manage(environment, { install: [] });
+            } catch (err) {
+                traceError('Error when running command python-envs.packages', err);
+            }
         }),
         commands.registerCommand('python-envs.uninstallPackage', async (context: unknown) => {
             await handlePackageUninstall(context, envManagers);
@@ -263,8 +268,10 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             registerSystemPythonFeatures(nativeFinder, context.subscriptions, outputChannel),
             registerCondaFeatures(nativeFinder, context.subscriptions, outputChannel),
         ]);
+
         sendTelemetryEvent(EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION, start.elapsedTime);
         await terminalManager.initialize(api);
+        sendManagerSelectionTelemetry(projectManager);
     });
 
     sendTelemetryEvent(EventNames.EXTENSION_ACTIVATION_DURATION, start.elapsedTime);

src/features/creators/autoFindProjects.ts

@@ -1,11 +1,12 @@
 import * as path from 'path';
 import { Uri } from 'vscode';
-import { showQuickPickWithButtons } from '../../common/window.apis';
+import { showQuickPickWithButtons, showWarningMessage } from '../../common/window.apis';
 import { ProjectCreatorString } from '../../common/localize';
 import { PythonProject, PythonProjectCreator, PythonProjectCreatorOptions } from '../../api';
 import { PythonProjectManager } from '../../internal.api';
 import { showErrorMessage } from '../../common/errors/utils';
 import { findFiles } from '../../common/workspace.apis';
+import { traceInfo } from '../../common/logging';
 
 function getUniqueUri(uris: Uri[]): {
     label: string;
@@ -68,8 +69,9 @@ export class AutoFindProjects implements PythonProjectCreator {
         const filtered = files.filter((uri) => {
             const p = this.pm.get(uri);
             if (p) {
-                // If there ia already a project with the same path, skip it.
-                // If there is a project with the same parent path, skip it.
+                // Skip this project if:
+                // 1. There's already a project registered with exactly the same path
+                // 2. There's already a project registered with this project's parent directory path
                 const np = path.normalize(p.uri.fsPath);
                 const nf = path.normalize(uri.fsPath);
                 const nfp = path.dirname(nf);
@@ -79,11 +81,20 @@ export class AutoFindProjects implements PythonProjectCreator {
         });
 
         if (filtered.length === 0) {
+            // No new projects found that are not already in the project manager
+            traceInfo('All discovered projects are already registered in the project manager');
+            setImmediate(() => {
+                showWarningMessage('No new projects found');
+            });
             return;
         }
 
+        traceInfo(`Found ${filtered.length} new potential projects that aren't already registered`);
+
         const projects = await pickProjects(filtered);
         if (!projects || projects.length === 0) {
+            // User cancelled the selection.
+            traceInfo('User cancelled project selection.');
             return;
         }
 

src/features/creators/existingProjects.ts

@@ -1,12 +1,18 @@
 import * as path from 'path';
 import { PythonProject, PythonProjectCreator, PythonProjectCreatorOptions } from '../../api';
 import { ProjectCreatorString } from '../../common/localize';
-import { showOpenDialog } from '../../common/window.apis';
+import { showOpenDialog, showWarningMessage } from '../../common/window.apis';
+import { PythonProjectManager } from '../../internal.api';
+import { traceInfo } from '../../common/logging';
+import { Uri, window, workspace } from 'vscode';
+import { traceLog } from '../../common/logging';
 
 export class ExistingProjects implements PythonProjectCreator {
     public readonly name = 'existingProjects';
     public readonly displayName = ProjectCreatorString.addExistingProjects;
 
+    constructor(private readonly pm: PythonProjectManager) {}
+
     async create(_options?: PythonProjectCreatorOptions): Promise<PythonProject | PythonProject[] | undefined> {
         const results = await showOpenDialog({
             canSelectFiles: true,
@@ -19,12 +25,73 @@ export class ExistingProjects implements PythonProjectCreator {
         });
 
         if (!results || results.length === 0) {
+            // User cancelled the dialog & doesn't want to add any projects
             return;
         }
 
-        return results.map((r) => ({
-            name: path.basename(r.fsPath),
-            uri: r,
-        }));
+        // do we have any limitations that need to be applied here?
+        // like selected folder not child of workspace folder?
+
+        const filtered = results.filter((uri) => {
+            const p = this.pm.get(uri);
+            if (p) {
+                // Skip this project if there's already a project registered with exactly the same path
+                const np = path.normalize(p.uri.fsPath);
+                const nf = path.normalize(uri.fsPath);
+                return np !== nf;
+            }
+            return true;
+        });
+
+        if (filtered.length === 0) {
+            // No new projects found that are not already in the project manager
+            traceInfo('All discovered projects are already registered in the project manager');
+            setImmediate(() => {
+                showWarningMessage('No new projects found');
+            });
+            return;
+        }
+
+        // for all the selected files / folders, check to make sure they are in the workspace
+        const resultsOutsideWorkspace: Uri[] = [];
+        const workspaceRoots: Uri[] = workspace.workspaceFolders?.map((w) => w.uri) || [];
+        const resultsInWorkspace = filtered.filter((r) => {
+            const exists = workspaceRoots.some((w) => r.fsPath.startsWith(w.fsPath));
+            if (!exists) {
+                traceLog(`File ${r.fsPath} is not in the workspace, ignoring it from 'add projects' list.`);
+                resultsOutsideWorkspace.push(r);
+            }
+            return exists;
+        });
+        if (resultsInWorkspace.length === 0) {
+            // Show a single error message with option to add to workspace
+            const response = await window.showErrorMessage(
+                'Selected items are not in the current workspace.',
+                'Add to Workspace',
+                'Cancel',
+            );
+
+            if (response === 'Add to Workspace') {
+                // Use the command palette to let user adjust which folders to add
+                // Add folders programmatically using workspace API
+                for (const r of resultsOutsideWorkspace) {
+                    // if the user selects a file, add that file to the workspace
+                    await // if the user selects a folder, add that folder to the workspace
+                    await workspace.updateWorkspaceFolders(
+                        workspace.workspaceFolders?.length || 0, // Start index
+                        0, // Delete count
+                        {
+                            uri: r,
+                        },
+                    );
+                }
+            }
+            return;
+        } else {
+            return resultsInWorkspace.map((uri) => ({
+                name: path.basename(uri.fsPath),
+                uri,
+            })) as PythonProject[];
+        }
     }
 }