Change public API for execution to return an object and provide a callback which is called when interpreter setting changes

[karrtikr]

Old design: #11294

Want to have a public API that returns an object which initially contains an array of strings for the command to execute a Python interpreter. The expectation is we may need to include environment variable details at some point. Update the API as follows,

export interface IExtensionApi {
    /**
     * Promise indicating whether all parts of the extension have completed loading or not.
     * @type {Promise<void>}
     * @memberof IExtensionApi
     */
    ready: Promise<void>;
    debug: {
        /**
         * Generate an array of strings for commands to pass to the Python executable to launch the debugger for remote debugging.
         * Users can append another array of strings of what they want to execute along with relevant arguments to Python.
         * E.g `['/Users/..../pythonVSCode/pythonFiles/lib/python/debugpy', '--listen', 'localhost:57039', '--wait-for-client']`
         * @param {string} host
         * @param {number} port
         * @param {boolean} [waitUntilDebuggerAttaches=true]
         * @returns {Promise<string[]>}
         */
        getRemoteLauncherCommand(host: string, port: number, waitUntilDebuggerAttaches: boolean): Promise<string[]>;

        /**
         * Gets the path to the debugger package used by the extension.
         * @returns {Promise<string>}
         */
        getDebuggerPackagePath(): Promise<string | undefined>;
    };
    /**
     * Return internal settings within the extension which are stored in VSCode storage
     */
    settings: {
        /**
         * An event that is emitted when execution details (for a resource) change. For instance, when interpreter configuration changes.
         */
        readonly onDidChangeExecutionDetails: Event<Uri | undefined>;
        /**
         * Returns all the details the consumer needs to execute code within the selected environment,
         * corresponding to the specified resource taking into account any workspace-specific settings
         * for the workspace to which this resource belongs.
         * @param {Resource} [resource] A resource for which the setting is asked for.
         * * When no resource is provided, the setting scoped to the first workspace folder is returned.
         * * If no folder is present, it returns the global setting.
         * @returns {({ execCommand: string[] | undefined })}
         */
        getExecutionDetails(
            resource?: Resource
        ): {
            /**
             * E.g of execution commands returned could be,
             * * `['<path to the interpreter set in settings>']`
             * * `['<path to the interpreter selected by the extension when setting is not set>']`
             * * `['conda', 'run', 'python']` which is used to run from within Conda environments.
             * or something similar for some other Python environments.
             *
             * @type {(string[] | undefined)} When return value is `undefined`, it means no interpreter is set.
             * Otherwise, join the items returned using space to construct the full execution command.
             */
            execCommand: string[] | undefined;
        };
    };
    datascience: {
        /**
         * Launches Data Viewer component.
         * @param {IDataViewerDataProvider} dataProvider Instance that will be used by the Data Viewer component to fetch data.
         * @param {string} title Data Viewer title
         */
        showDataViewer(dataProvider: IDataViewerDataProvider, title: string): Promise<void>;
    };
}

[karrtikr]

Tracking the issue for documenting the API microsoft/vscode-docs#3829

Code runner changes: formulahendry/vscode-code-runner#635

[brettcannon]

/cc @jakebailey

[jakebailey]

Seems good. I would have maybe had the event include the new info, but maybe it's too expensive and users should just requery if needed.

@erictraut For awareness.

[brettcannon]

@jakebailey it's a possibility. It's one of those tricky things where we are trying to design for the future which means decomposing way more than we would if we were designing just for today.

[karrtikr]

@jakebailey We can send just pythonPath for now but as Brett pointed out, as the API begins to include more details, all of the execution details won't be readily available when firing the events.
So we'll have to query these ourselves to send these along with events, which seems rather unnecessary as users can do that themselves if needed.

[karrtikr]

Also, the default VSCode setting change event API do not include the new info, so we are just keeping up with the trend 🙂

[jakebailey]

Fine with me.

[jamilraichouni]

Hi!

Would be great if getExecutionDetails were also providing the prefix of a possibly activated conda environment.

That can be identified using the path from execCommand, but then everybody has to do that by his own doing something like

1. Check if environment variable CONDA_PREFIX is set and if not:
2. Check, if there is a conda executable in the same path as the interpreter given in execCommand.

I have a use case where I need to get the conda env prefix during runtime of a conda Python process even if the conda env has not been activated. If there is a more stable way to do that, let me know, please.

Cheers,
Jamil

[karrtikr]

@jamilraichouni I have opened up a new issue #13044 for you, we'll let you know our thoughts there.