Code execution APIs (#15)

Author: karthiknadig

src/api.ts

@@ -1,4 +1,4 @@
-import { Uri, Disposable, MarkdownString, Event, LogOutputChannel, ThemeIcon, Terminal } from 'vscode';
+import { Uri, Disposable, MarkdownString, Event, LogOutputChannel, ThemeIcon, Terminal, TaskExecution } from 'vscode';
 
 /**
  * The path to an icon, or a theme-specific configuration of icons.
@@ -767,13 +767,11 @@ export interface Installable {
     readonly uri?: Uri;
 }
 
-export interface PythonTaskResult {}
-
 export interface PythonProcess {
     /**
      * The process ID of the Python process.
      */
-    readonly pid: number;
+    readonly pid?: number;
 
     /**
      * The standard input of the Python process.
@@ -798,10 +796,10 @@ export interface PythonProcess {
     /**
      * Event that is fired when the Python process exits.
      */
-    onExit: Event<number>;
+    onExit(listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
 }
 
-export interface PythonEnvironmentManagerApi {
+export interface PythonEnvironmentManagerRegistrationApi {
     /**
      * Register an environment manager implementation.
      *
@@ -810,7 +808,9 @@ export interface PythonEnvironmentManagerApi {
      * @see {@link EnvironmentManager}
      */
     registerEnvironmentManager(manager: EnvironmentManager): Disposable;
+}
 
+export interface PythonEnvironmentItemApi {
     /**
      * Create a Python environment item from the provided environment info. This item is used to interact
      * with the environment.
@@ -820,7 +820,9 @@ export interface PythonEnvironmentManagerApi {
      * @returns The Python environment.
      */
     createPythonEnvironmentItem(info: PythonEnvironmentInfo, manager: EnvironmentManager): PythonEnvironment;
+}
 
+export interface PythonEnvironmentManagementApi {
     /**
      * Create a Python environment using environment manager associated with the scope.
      *
@@ -836,7 +838,9 @@ export interface PythonEnvironmentManagerApi {
      * @returns A promise that resolves when the environment has been removed.
      */
     removeEnvironment(environment: PythonEnvironment): Promise<void>;
+}
 
+export interface PythonEnvironmentsApi {
     /**
      * Initiates a refresh of Python environments within the specified scope.
      * @param scope - The scope within which to search for environments.
@@ -857,6 +861,16 @@ export interface PythonEnvironmentManagerApi {
      */
     onDidChangeEnvironments: Event<DidChangeEnvironmentsEventArgs>;
 
+    /**
+     * This method is used to get the details missing from a PythonEnvironment. Like
+     * {@link PythonEnvironment.execInfo} and other details.
+     *
+     * @param context : The PythonEnvironment or Uri for which details are required.
+     */
+    resolveEnvironment(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
+}
+
+export interface PythonProjectEnvironmentApi {
     /**
      * Sets the current Python environment within the specified scope.
      * @param scope - The scope within which to set the environment.
@@ -876,17 +890,16 @@ export interface PythonEnvironmentManagerApi {
      * @see {@link DidChangeEnvironmentEventArgs}
      */
     onDidChangeEnvironment: Event<DidChangeEnvironmentEventArgs>;
-
-    /**
-     * This method is used to get the details missing from a PythonEnvironment. Like
-     * {@link PythonEnvironment.execInfo} and other details.
-     *
-     * @param context : The PythonEnvironment or Uri for which details are required.
-     */
-    resolveEnvironment(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 }
 
-export interface PythonPackageManagerApi {
+export interface PythonEnvironmentManagerApi
+    extends PythonEnvironmentManagerRegistrationApi,
+        PythonEnvironmentItemApi,
+        PythonEnvironmentManagementApi,
+        PythonEnvironmentsApi,
+        PythonProjectEnvironmentApi {}
+
+export interface PythonPackageManagerRegistrationApi {
     /**
      * Register a package manager implementation.
      *
@@ -895,24 +908,9 @@ export interface PythonPackageManagerApi {
      * @see {@link PackageManager}
      */
     registerPackageManager(manager: PackageManager): Disposable;
+}
 
-    /**
-     * Install 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>;
-
+export interface PythonPackageGetterApi {
     /**
      * Refresh the list of packages in a Python Environment.
      *
@@ -934,7 +932,9 @@ export interface PythonPackageManagerApi {
      * @see {@link DidChangePackagesEventArgs}
      */
     onDidChangePackages: Event<DidChangePackagesEventArgs>;
+}
 
+export interface PythonPackageItemApi {
     /**
      * Create a package item from the provided package info.
      *
@@ -946,38 +946,46 @@ export interface PythonPackageManagerApi {
     createPackageItem(info: PackageInfo, environment: PythonEnvironment, manager: PackageManager): Package;
 }
 
-/**
- * The API for interacting with Python projects. A project in python is any folder or file that is a contained
- * in some manner. For example, a PEP-723 compliant file can be treated as a project. A folder with a `pyproject.toml`,
- * or just python files can be treated as a project. All this allows you to do is set a python environment for that project.
- *
- * By default all `vscode.workspace.workspaceFolders` are treated as projects.
- */
-export interface PythonProjectApi {
+export interface PythonPackageManagementApi {
     /**
-     * Add a python project or projects to the list of projects.
+     * Install packages into a Python Environment.
      *
-     * @param projects The project or projects to add.
+     * @param environment The Python Environment into which packages are to be installed.
+     * @param packages The packages to install.
+     * @param options Options for installing packages.
      */
-    addPythonProject(projects: PythonProject | PythonProject[]): void;
+    installPackages(environment: PythonEnvironment, packages: string[], options: PackageInstallOptions): Promise<void>;
 
     /**
-     * Remove a python project from the list of projects.
+     * Uninstall packages from a Python Environment.
      *
-     * @param project The project to remove.
+     * @param environment The Python Environment from which packages are to be uninstalled.
+     * @param packages The packages to uninstall.
      */
-    removePythonProject(project: PythonProject): void;
+    uninstallPackages(environment: PythonEnvironment, packages: PackageInfo[] | string[]): Promise<void>;
+}
 
+export interface PythonPackageManagerApi
+    extends PythonPackageManagerRegistrationApi,
+        PythonPackageGetterApi,
+        PythonEnvironmentManagerApi,
+        PythonPackageItemApi {}
+
+export interface PythonProjectCreationApi {
     /**
-     * Get all python projects.
+     * Register a Python project creator.
+     *
+     * @param creator The project creator to register.
+     * @returns A disposable that can be used to unregister the project creator.
+     * @see {@link PythonProjectCreator}
      */
-    getPythonProjects(): readonly PythonProject[];
-
+    registerPythonProjectCreator(creator: PythonProjectCreator): Disposable;
+}
+export interface PythonProjectGetterApi {
     /**
-     * Event raised when python projects are added or removed.
-     * @see {@link DidChangePythonProjectsEventArgs}
+     * Get all python projects.
      */
-    onDidChangePythonProjects: Event<DidChangePythonProjectsEventArgs>;
+    getPythonProjects(): readonly PythonProject[];
 
     /**
      * Get the python project for a given URI.
@@ -986,52 +994,110 @@ export interface PythonProjectApi {
      * @returns The project or `undefined` if not found.
      */
     getPythonProject(uri: Uri): PythonProject | undefined;
+}
 
+export interface PythonProjectModifyApi {
     /**
-     * Register a Python project creator.
+     * Add a python project or projects to the list of projects.
      *
-     * @param creator The project creator to register.
-     * @returns A disposable that can be used to unregister the project creator.
-     * @see {@link PythonProjectCreator}
+     * @param projects The project or projects to add.
      */
-    registerPythonProjectCreator(creator: PythonProjectCreator): Disposable;
+    addPythonProject(projects: PythonProject | PythonProject[]): void;
+
+    /**
+     * Remove a python project from the list of projects.
+     *
+     * @param project The project to remove.
+     */
+    removePythonProject(project: PythonProject): void;
+
+    /**
+     * Event raised when python projects are added or removed.
+     * @see {@link DidChangePythonProjectsEventArgs}
+     */
+    onDidChangePythonProjects: Event<DidChangePythonProjectsEventArgs>;
 }
 
-export interface PythonExecutionApi {
+/**
+ * The API for interacting with Python projects. A project in python is any folder or file that is a contained
+ * in some manner. For example, a PEP-723 compliant file can be treated as a project. A folder with a `pyproject.toml`,
+ * or just python files can be treated as a project. All this allows you to do is set a python environment for that project.
+ *
+ * By default all `vscode.workspace.workspaceFolders` are treated as projects.
+ */
+export interface PythonProjectApi extends PythonProjectCreationApi, PythonProjectGetterApi, PythonProjectModifyApi {}
+
+export interface PythonTerminalCreateApi {
     createTerminal(
-        cwd: string | Uri | PythonProject,
-        environment?: PythonEnvironment,
-        envVars?: { [key: string]: string },
-    ): Promise<Terminal>;
-    runInTerminal(
         environment: PythonEnvironment,
-        cwd: string | Uri | PythonProject,
-        command: string,
-        args?: string[],
+        cwd: string | Uri,
+        envVars?: { [key: string]: string },
     ): Promise<Terminal>;
+}
+
+export interface PythonTerminalExecutionOptions {
+    cwd: string | Uri;
+    args?: string[];
+
+    show?: boolean;
+}
+
+export interface PythonTerminalRunApi {
+    runInTerminal(environment: PythonEnvironment, options: PythonTerminalExecutionOptions): Promise<Terminal>;
     runInDedicatedTerminal(
-        terminalKey: string | Uri,
+        terminalKey: Uri,
         environment: PythonEnvironment,
-        cwd: string | Uri | PythonProject,
-        command: string,
-        args?: string[],
+        options: PythonTerminalExecutionOptions,
     ): Promise<Terminal>;
-    runAsTask(
-        environment: PythonEnvironment,
-        cwd: string | Uri | PythonProject,
-        command: string,
-        args?: string[],
-        envVars?: { [key: string]: string },
-    ): Promise<PythonTaskResult>;
-    runInBackground(
-        environment: PythonEnvironment,
-        cwd: string | Uri | PythonProject,
-        command: string,
-        args?: string[],
-        envVars?: { [key: string]: string },
-    ): Promise<PythonProcess>;
 }
+
+/**
+ *
+ * Example:
+ *  * Running Script: `python myscript.py --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["myscript.py", "--arg1"]
+ *    }
+ *  ```
+ *  * Running a module: `python -m my_module --arg1`
+ *  ```typescript
+ *    {
+ *       args: ["-m", "my_module", "--arg1"]
+ *    }
+ *  ```
+ */
+export interface PythonTaskExecutionOptions {
+    project?: PythonProject;
+    args: string[];
+    cwd?: string;
+    env?: { [key: string]: string };
+    name: string;
+}
+
+export interface PythonTaskRunApi {
+    runAsTask(environment: PythonEnvironment, options: PythonTaskExecutionOptions): Promise<TaskExecution>;
+}
+
+export interface PythonBackgroundRunOptions {
+    args: string[];
+    cwd?: string;
+    env?: { [key: string]: string };
+}
+export interface PythonBackgroundRunApi {
+    runInBackground(environment: PythonEnvironment, options: PythonBackgroundRunOptions): Promise<PythonProcess>;
+}
+
+export interface PythonExecutionApi
+    extends PythonTerminalCreateApi,
+        PythonTerminalRunApi,
+        PythonTaskRunApi,
+        PythonBackgroundRunApi {}
 /**
  * The API for interacting with Python environments, package managers, and projects.
  */
-export interface PythonEnvironmentApi extends PythonEnvironmentManagerApi, PythonPackageManagerApi, PythonProjectApi {}
+export interface PythonEnvironmentApi
+    extends PythonEnvironmentManagerApi,
+        PythonPackageManagerApi,
+        PythonProjectApi,
+        PythonExecutionApi {}

src/extension.ts

@@ -70,7 +70,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         registerAutoProjectProvider(projectCreators),
     );
 
-    setPythonApi(envManagers, projectManager, projectCreators);
+    setPythonApi(envManagers, projectManager, projectCreators, terminalManager);
 
     const managerView = new EnvManagerView(envManagers);
     context.subscriptions.push(managerView);