API for Python Projects/Workspaces

[karthiknadig]

import { Uri, Event, WorkspaceFolder } from 'vscode';
/**
 * A python workspace is similar to a VS Code workspace. All workspaces are equal with no notion of
 * active or primary workspace. The main difference from VS Code {@link WorkspaceFolder workspace folder}
 * is that a file can treated like a workspace (see PEP-723 https://peps.python.org/pep-0723/).
 */
export interface PythonWorkspace {
    /**
     * The name of the python workspace. Defaults to the basename of its {@link Uri.path uri-path}
     * if not provided. Typically name of the file or folder.
     */
    readonly name: string;

    /**
     * The associated uri of the python workspace.
     */
    readonly uri: Uri;
}

/**
 * An event that is emitted when {@link PythonWorkspace python workspaces} are added or removed.
 */
export interface PythonWorkspacesChangedEvent {
    /**
     * The python workspaces that have been added.
     */
    readonly added: readonly PythonWorkspace[];

    /**
     * The python workspaces that have been removed.
     */
    readonly removed: readonly PythonWorkspace[];
}

export interface PythonWorkspaces {
    /**
     * [internal] Add python workspaces to the collection.
     *
     * @param pyWorkspace The python workspaces to add.
     *
     */
    addPythonWorkspace(...pyWorkspace: PythonWorkspace[]): void;

    /**
     * [internal] Remove python workspaces from the collection.
     *
     * @param pyWorkspace The python workspaces to remove.
     */
    removePythonWorkspace(...pyWorkspace: PythonWorkspace[]): boolean;

    /**
     * [internal] Create {@link PythonWorkspace python workspace} object for the given uri.
     * * will return the existing workspace if one already exists for the given uri
     *
     * @param uri The uri for which to create the python workspace.
     * @param name The name of the python workspace. Defaults to the basename of the file or folder.
     * @returns The a python workspace.
     */
    createPythonWorkspace(uri: Uri, name?: string): PythonWorkspace;

    /**
     * An event that is emitted when python workspaces are added or removed.
     *
     * **Note:** This event is not fired when workspaces as available in VS Code
     * are loaded for the first time.
     */
    onDidChangePythonWorkspaces: Event<PythonWorkspacesChangedEvent>;

    /**
     * List of {@link PythonWorkspace python workspaces}. Empty if no python workspaces are available.
     */
    readonly workspaces: readonly PythonWorkspace[];

    /**
     * Get the {@link PythonWorkspace python workspace} that contains the given uri.
     * * returns `undefined` when the given uri doesn't match any workspace
     *
     * @param uri An uri.
     * @returns The python workspace or `undefined`.
     */
    getPythonWorkspace(uri: Uri): PythonWorkspace | undefined;
}

[karthiknadig]

This is an API proposal. There is nothing to verify here.