.vscode-server/extensions/ms-python.vscode-python-envs-1.20.1-linux-arm64/docs/projects-api-reference.md

Python Projects API Reference

Modifying Projects

This is how the projects API is designed with the different parts of the project flow. Here getPythonProjects is used as an example function but behavior will mirror other getter and setter functions exposed in the API.

1. API Call: Extensions can calls getPythonProjects on PythonEnvironmentApi.
2. API Implementation: PythonEnvironmentApiImpl delegates to its internal project manager.
3. Internal API: The project manager is typed as PythonProjectManager.
4. Concrete Implementation: PythonProjectManagerImpl implements the actual logic.
5. Data Model: Returns an array of PythonProject objects.

Project Creators

This is how creating projects work with the API as it uses a method of registering external or internal project creators and maintaining project states internally in just this extension.

• Project Creators: Any extension can implement and register a project creator by conforming to the PythonProjectCreator interface. Each creator provides a create method that returns one or more new projects (or their URIs). The create method is responsible for add the new projects to the project manager.
• Registration: Project creators are registered with the API, making them discoverable and usable by the extension or other consumers.
• Integration: Once a project is created, it is added to the internal project manager (PythonProjectManagerImpl in src/features/projectManager.ts), which updates the set of known projects and persists settings if necessary.

What an Extension Must Do

1. Implement the Creator Interface:

   • Create a class that implements the PythonProjectCreator interface.
   • Provide a unique name, a user-friendly displayName, and a create method that returns one or more PythonProject objects or URIs.

2. Register the Creator:

   • Register the creator with the main API (usually via a registration method exposed by this extension’s API surface).
   • This makes the creator discoverable and usable by the extension and other consumers.

3. Add Projects Directly:

   • If your creator directly creates PythonProject objects, you MUST call the internal project manager’s add method during your create function to add projects as ones in the workspace.

Responsibilities Table

Step	External Extension’s Responsibility	Internal Python-Envs-Ext Responsibility
Implement PythonProjectCreator interface	☑️
Register the creator	☑️
Provide create method	☑️
Add projects to project manager	☑️
Update project settings		☑️
Track and list creators		☑️
Invoke creator and handle results		☑️

Example Implementation: ExistingProjects

The ExistingProjects class is an example of a project creator. It allows users to select files or folders from the workspace and creates new PythonProject instances for them. After creation, these projects are added to the internal project manager:

create function implementation abbreviated:

async create(
        _options?: PythonProjectCreatorOptions,
    ): Promise<PythonProject | PythonProject[] | Uri | Uri[] | undefined> {
const projects = resultsInWorkspace.map(
                (uri) => new PythonProjectsImpl(path.basename(uri.fsPath), uri),
            ) as PythonProject[];
this.pm.add(projects);
return projects;
    }

creator registration (usually on extension activation):

  projectCreators.registerPythonProjectCreator(new ExistingProjects(projectManager)),

• Implements: PythonProjectCreator
• Adds projects to: PythonProjectManager (see below)