Add an API to add a new locator

Author: Kartik Raj

src/client/pythonEnvironments/api.ts

@@ -20,13 +20,16 @@ export type GetLocatorFunc = () => Promise<IDiscoveryAPI>;
 class PythonEnvironments implements IDiscoveryAPI {
     private locator!: IDiscoveryAPI;
 
+    public addNewLocator = this.locator.addNewLocator;
+
     constructor(
         // These are factories for the sub-components the full component is composed of:
         private readonly getLocator: GetLocatorFunc,
     ) {}
 
     public async activate(): Promise<void> {
         this.locator = await this.getLocator();
+        this.addNewLocator = this.locator.addNewLocator;
     }
 
     public get onProgress(): Event<ProgressNotificationEvent> {

src/client/pythonEnvironments/base/locator.ts

@@ -14,6 +14,62 @@ import {
     PythonEnvsWatcher,
 } from './watcher';
 
+export interface ILocatorClass {
+    new (root?: string): ILocatorAPI;
+}
+
+export interface ILocatorAPI {
+    iterEnvs?(): IPythonEnvsIterator<EnvInfo>;
+    readonly onChanged?: Event<LocatorEnvsChangedEvent>;
+}
+
+export type EnvInfo = {
+    envSources: EnvSource[];
+    executablePath: string;
+    envPath?: string;
+};
+
+/**
+ * These can be used when querying for a particular env.
+ */
+interface EnvironmentProviderMetadata {
+    readonly envType: EnvType;
+    readonly searchLocation?: string;
+    readonly envSources: EnvSource[];
+    readonly isRootBasedLocator: boolean;
+}
+
+type EnvironmentMetaData = EnvironmentProviderMetadata;
+
+export interface LocatorEnvsChangedEvent {
+    /**
+     * Any details known about the environment which can be used for query.
+     */
+    env?: EnvironmentMetaData;
+    type: EnvChangeType;
+}
+
+export type EnvChangeType = 'add' | 'remove' | 'update';
+
+export enum EnvType {
+    VirtualEnv = 'VirtualEnv',
+    Conda = 'Conda',
+    Unknown = 'Unknown',
+    Global = 'GlobalInterpreter',
+}
+
+export enum EnvSource {
+    Conda = 'Conda',
+    Pipenv = 'PipEnv',
+    Poetry = 'Poetry',
+    VirtualEnv = 'VirtualEnv',
+    Venv = 'Venv',
+    VirtualEnvWrapper = 'VirtualEnvWrapper',
+    WindowsStore = 'WindowsStore',
+    Pyenv = 'Pyenv',
+    Custom = 'Custom',
+}
+
 /**
  * A single update to a previously provided Python env object.
  */
@@ -153,7 +209,9 @@ export type BasicEnvInfo = {
  * events emitted via `onChanged` do not need to provide information
  * for the specific environments that changed.
  */
-export interface ILocator<I = PythonEnvInfo, E = PythonEnvsChangedEvent> extends IPythonEnvsWatcher<E> {
+export interface ILocator<I = PythonEnvInfo, E extends BasicPythonEnvsChangedEvent = PythonEnvsChangedEvent>
+    extends IPythonEnvsWatcher<E>,
+        IEnvProvider {
     /**
      * Iterate over the enviroments known tos this locator.
      *
@@ -173,6 +231,10 @@ export interface ILocator<I = PythonEnvInfo, E = PythonEnvsChangedEvent> extends
     iterEnvs(query?: QueryForEvent<E>): IPythonEnvsIterator<I>;
 }
 
+export interface IEnvProvider {
+    addNewLocator?(LocatorClass: ILocatorClass, isWorkspace: boolean): void;
+}
+
 interface IResolver {
     /**
      * Find as much info about the given Python environment as possible.
@@ -203,7 +265,7 @@ export type TriggerRefreshOptions = {
     ifNotTriggerredAlready?: boolean;
 };
 
-export interface IDiscoveryAPI {
+export interface IDiscoveryAPI extends IEnvProvider {
     /**
      * Tracks discovery progress for current list of known environments, i.e when it starts, finishes or any other relevant
      * stage. Note the progress for a particular query is currently not tracked or reported, this only indicates progress of

src/client/pythonEnvironments/base/locators/composite/envsCollectionService.ts

@@ -47,6 +47,8 @@ export class EnvsCollectionService extends PythonEnvsWatcher<PythonEnvCollection
         return this.progress.event;
     }
 
+    public addNewLocator = this.locator.addNewLocator;
+
     public getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined {
         const stage = options?.stage ?? ProgressReportStage.discoveryFinished;
         return this.progressPromises.get(stage)?.promise;

src/client/pythonEnvironments/base/locators/composite/envsReducer.ts

@@ -27,6 +27,8 @@ export class PythonEnvsReducer implements ILocator<BasicEnvInfo> {
         return this.parentLocator.onChanged;
     }
 
+    public addNewLocator = this.parentLocator.addNewLocator;
+
     constructor(private readonly parentLocator: ILocator<BasicEnvInfo>) {}
 
     public iterEnvs(query?: PythonLocatorQuery): IPythonEnvsIterator<BasicEnvInfo> {

src/client/pythonEnvironments/base/locators/composite/envsResolver.ts

@@ -34,6 +34,8 @@ export class PythonEnvsResolver implements IResolvingLocator {
         return this.parentLocator.onChanged;
     }
 
+    public addNewLocator = this.parentLocator.addNewLocator;
+
     constructor(
         private readonly parentLocator: ILocator<BasicEnvInfo>,
         private readonly environmentInfoService: IEnvironmentInfoService,