Merge branch 'main' into update-readme

Author: cwebster-99

.nvmrc

@@ -0,0 +1 @@
+20.18.0

.vscode/launch.json

@@ -11,7 +11,7 @@
             "request": "launch",
             "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
             "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-            "preLaunchTask": "${defaultBuildTask}"
+            "preLaunchTask": "npm: watch"
         },
         {
             "name": "Unit Tests",
@@ -30,7 +30,7 @@
             "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
             "skipFiles": ["<node_internals>/**"],
             "outFiles": ["${workspaceFolder}/out/**/*.js", "!${workspaceFolder}/**/node_modules**/*"],
-            "preLaunchTask": "tasks: watch-tests"
+            "preLaunchTask": "npm: watch-tests"
         },
         {
             "name": "Extension Tests",
@@ -41,7 +41,7 @@
                 "--extensionTestsPath=${workspaceFolder}/out/test/"
             ],
             "outFiles": ["${workspaceFolder}/out/**/*.js", "${workspaceFolder}/dist/**/*.js"],
-            "preLaunchTask": "tasks: watch-tests"
+            "preLaunchTask": "${defaultBuildTask}"
         }
     ]
 }

.vscode/settings.json

@@ -12,11 +12,17 @@
     "typescript.tsc.autoDetect": "off",
     "editor.formatOnSave": true,
     "[typescript]": {
-        "editor.defaultFormatter": "esbenp.prettier-vscode"
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+        }
     },
     "[python]": {
         "editor.defaultFormatter": "charliermarsh.ruff",
-        "diffEditor.ignoreTrimWhitespace": false
+        "diffEditor.ignoreTrimWhitespace": false,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+        }
     },
     "prettier.tabWidth": 4,
     "python-envs.defaultEnvManager": "ms-python.python:venv",

.vscode/tasks.json

@@ -25,13 +25,16 @@
             "presentation": {
                 "reveal": "never",
                 "group": "watchers"
-            },
-            "group": "build"
+            }
         },
         {
-            "label": "tasks: watch-tests",
+            "label": "tasks: build",
             "dependsOn": ["npm: watch", "npm: watch-tests"],
-            "problemMatcher": []
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "never",
+                "group": "watchers"
+            }
         },
         {
             "type": "npm",

README.md

@@ -99,9 +99,34 @@ See [api.ts](https://github.com/microsoft/vscode-python-environments/blob/main/s
 
 To consume these APIs you can look at the example here: [API Consumption Examples](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:
 
@@ -121,7 +146,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:
 

package.json

@@ -86,6 +86,22 @@
                         "onExP",
                         "preview"
                     ]
+                },
+                "python-envs.terminal.autoActivationType": {
+                    "type": "string",
+                    "markdownDescription": "%python-envs.terminal.autoActivationType.description%",
+                    "default": "command",
+                    "enum": [
+                        "command",
+                        "shellStartup",
+                        "off"
+                    ],
+                    "markdownEnumDescriptions": [
+                        "%python-envs.terminal.autoActivationType.command%",
+                        "%python-envs.terminal.autoActivationType.shellStartup%",
+                        "%python-envs.terminal.autoActivationType.off%"
+                    ],
+                    "scope": "machine"
                 }
             }
         },
@@ -228,14 +244,16 @@
                 "title": "%python-envs.copyProjectPath.title%",
                 "category": "Python Envs",
                 "icon": "$(copy)"
+            },
+            {
+                "command": "python-envs.terminal.revertStartupScriptChanges",
+                "title": "%python-envs.terminal.revertStartupScriptChanges.title%",
+                "category": "Python Envs",
+                "icon": "$(discard)"
             }
         ],
         "menus": {
             "commandPalette": [
-                {
-                    "command": "python-envs.packages",
-                    "when": "false"
-                },
                 {
                     "command": "python-envs.refreshAllManagers",
                     "when": "false"
@@ -491,22 +509,53 @@
         ],
         "languageModelTools": [
             {
-                "name": "python_get_packages",
-                "displayName": "Get Python Packages",
-                "modelDescription": "Returns the packages installed in the given Python file's environment. You should call this when you want to generate Python code to determine the users preferred packages. Also call this to determine if you need to provide installation instructions in a response.",
-                "toolReferenceName": "pythonGetPackages",
+                "name": "python_environment",
+                "userDescription": "Get Python environment info for a file or path, including version, packages, and the command to run it.",
+                "displayName": "Get Python Environment Information",
+                "modelDescription": "Provides details about the Python environment for a specified file or workspace, including environment type, Python version, run command, and installed packages with their versions. Use this tool to determine the correct command for executing Python code in this workspace.",
+                "toolReferenceName": "pythonGetEnvironmentInfo",
                 "tags": [],
                 "icon": "$(files)",
+                "canBeReferencedInPrompt": true,
                 "inputSchema": {
                     "type": "object",
                     "properties": {
-                        "filePath": {
+                        "resourcePath": {
                             "type": "string"
                         }
                     },
-                    "description": "The path to the Python file or workspace to get the installed packages for.",
+                    "description": "The path to the Python file or workspace to get the environment information for.",
+                    "required": [
+                        "resourcePath"
+                    ]
+                }
+            },
+            {
+                "name": "python_install_package",
+                "displayName": "Install Python Package",
+                "modelDescription": "Installs Python packages in the given workspace. Use this tool to install packages in the user's chosen environment.",
+                "toolReferenceName": "pythonInstallPackage",
+                "tags": [],
+                "icon": "$(package)",
+                "canBeReferencedInPrompt": true,
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "packageList": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "description": "The list of packages to install."
+                        },
+                        "resourcePath": {
+                            "type": "string",
+                            "description": "The path to the Python file or workspace to get the environment information for."
+                        }
+                    },
                     "required": [
-                        "filePath"
+                        "packageList",
+                        "resourcePath"
                     ]
                 }
             }

package.nls.json

@@ -6,6 +6,11 @@
     "python-envs.pythonProjects.envManager.description": "The environment manager for creating and managing environments for this project.",
     "python-envs.pythonProjects.packageManager.description": "The package manager for managing packages in environments for this project.",
     "python-envs.terminal.showActivateButton.description": "Whether to show the 'Activate' button in the terminal menu",
+    "python-envs.terminal.autoActivationType.description": "The type of activation to use when activating an environment in the terminal",
+    "python-envs.terminal.autoActivationType.command": "Activation by executing a command in the terminal.",
+    "python-envs.terminal.autoActivationType.shellStartup": "Activation by modifying the terminal shell startup script. To use this feature we will need to modify your shell startup scripts.",
+    "python-envs.terminal.autoActivationType.off": "No automatic activation of environments.",
+    "python-envs.terminal.revertStartupScriptChanges.title": "Revert Shell Startup Script Changes",
     "python-envs.setEnvManager.title": "Set Environment Manager",
     "python-envs.setPkgManager.title": "Set Package Manager",
     "python-envs.addPythonProject.title": "Add Python Project",

src/api.ts

@@ -2,16 +2,16 @@
 // Licensed under the MIT License.
 
 import {
-    Uri,
     Disposable,
-    MarkdownString,
     Event,
+    FileChangeType,
     LogOutputChannel,
-    ThemeIcon,
-    Terminal,
+    MarkdownString,
     TaskExecution,
+    Terminal,
     TerminalOptions,
-    FileChangeType,
+    ThemeIcon,
+    Uri,
 } from 'vscode';
 
 /**
@@ -333,7 +333,7 @@ export interface QuickCreateConfig {
  */
 export interface EnvironmentManager {
     /**
-     * The name of the environment manager.
+     * The name of the environment manager. Allowed characters (a-z, A-Z, 0-9, -, _).
      */
     readonly name: string;
 
@@ -374,7 +374,7 @@ export interface EnvironmentManager {
 
     /**
      * The quick create details for the environment manager. Having this method also enables the quick create feature
-     * for the environment manager.
+     * for the environment manager. Should Implement {@link EnvironmentManager.create} to support quick create.
      */
     quickCreateConfig?(): QuickCreateConfig | undefined;
 
@@ -564,7 +564,7 @@ export interface DidChangePackagesEventArgs {
  */
 export interface PackageManager {
     /**
-     * The name of the package manager.
+     * The name of the package manager. Allowed characters (a-z, A-Z, 0-9, -, _).
      */
     name: string;
 
@@ -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>;
@@ -667,9 +667,14 @@ export interface PythonProjectCreatorOptions {
     name: string;
 
     /**
-     * Optional path that may be provided as a root for the project.
+     * Path provided as the root for the project.
      */
-    uri?: Uri;
+    rootUri: Uri;
+
+    /**
+     * Boolean indicating whether the project should be created without any user input.
+     */
+    quickCreate?: boolean;
 }
 
 /**
@@ -702,11 +707,20 @@ export interface PythonProjectCreator {
     readonly iconPath?: IconPath;
 
     /**
-     * Creates a new Python project or projects.
-     * @param options - Optional parameters for creating the Python project.
-     * @returns A promise that resolves to a Python project, an array of Python projects, or undefined.
+     * Creates a new Python project(s) or, if files are not a project, returns Uri(s) to the created files.
+     * Anything that needs its own python environment constitutes a project.
+     * @param options Optional parameters for creating the Python project.
+     * @returns A promise that resolves to one of the following:
+     *   - PythonProject or PythonProject[]: when a single or multiple projects are created.
+     *   - Uri or Uri[]: when files are created that do not constitute a project.
+     *   - undefined: if project creation fails.
+     */
+    create(options?: PythonProjectCreatorOptions): Promise<PythonProject | PythonProject[] | Uri | Uri[] | undefined>;
+
+    /**
+     * A flag indicating whether the project creator supports quick create where no user input is required.
      */
-    create(options?: PythonProjectCreatorOptions): Promise<PythonProject | PythonProject[] | undefined>;
+    readonly supportsQuickCreate?: boolean;
 }
 
 /**

src/common/command.api.ts

@@ -1,5 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { commands } from 'vscode';
+import { Disposable } from 'vscode-jsonrpc';
+
+export function registerCommand(command: string, callback: (...args: any[]) => any, thisArg?: any): Disposable {
+    return commands.registerCommand(command, callback, thisArg);
+}
 
 export function executeCommand<T = unknown>(command: string, ...rest: any[]): Thenable<T> {
     return commands.executeCommand(command, ...rest);

src/common/commands.ts

@@ -0,0 +1,3 @@
+export namespace Commands {
+    export const viewLogs = 'python-envs.viewLogs';
+}