Add the base Python envs locators. (microsoft#13764)

Author: Eric Snow

src/client/common/utils/async.ts

@@ -117,16 +117,16 @@ export function createDeferredFromPromise<T>(promise: Promise<T>): Deferred<T> {
 /**
  * An iterator that yields nothing.
  */
-export function iterEmpty<T, R = void>(): AsyncIterator<T, R> {
+export function iterEmpty<T>(): AsyncIterator<T, void> {
     // tslint:disable-next-line:no-empty
-    return ((async function* () {})() as unknown) as AsyncIterator<T, R>;
+    return ((async function* () {})() as unknown) as AsyncIterator<T, void>;
 }
 
-type NextResult<T, R = void> = { index: number } & (
-    | { result: IteratorResult<T, R>; err: null }
+type NextResult<T> = { index: number } & (
+    | { result: IteratorResult<T, T | void>; err: null }
     | { result: null; err: Error }
 );
-async function getNext<T, R = void>(it: AsyncIterator<T, R>, indexMaybe?: number): Promise<NextResult<T, R>> {
+async function getNext<T>(it: AsyncIterator<T, T | void>, indexMaybe?: number): Promise<NextResult<T>> {
     const index = indexMaybe === undefined ? -1 : indexMaybe;
     try {
         const result = await it.next();
@@ -149,32 +149,34 @@ const NEVER: Promise<unknown> = new Promise(() => {});
  * @param iterators - the async iterators from which to yield items
  * @param onError - called/awaited once for each iterator that fails
  */
-export async function* chain<T, R = void>(
-    iterators: AsyncIterator<T | void, R>[],
+export async function* chain<T>(
+    iterators: AsyncIterator<T, T | void>[],
     onError?: (err: Error, index: number) => Promise<void>
     // Ultimately we may also want to support cancellation.
-): AsyncIterator<T | R | void, void> {
+): AsyncIterator<T, void> {
     const promises = iterators.map(getNext);
     let numRunning = iterators.length;
     while (numRunning > 0) {
         const { index, result, err } = await Promise.race(promises);
         if (err !== null) {
-            promises[index] = NEVER as Promise<NextResult<T, R>>;
+            promises[index] = NEVER as Promise<NextResult<T>>;
             numRunning -= 1;
             if (onError !== undefined) {
                 await onError(err, index);
             }
             // XXX Log the error.
         } else if (result!.done) {
-            promises[index] = NEVER as Promise<NextResult<T, R>>;
+            promises[index] = NEVER as Promise<NextResult<T>>;
             numRunning -= 1;
             // If R is void then result.value will be undefined.
             if (result!.value !== undefined) {
                 yield result!.value;
             }
         } else {
             promises[index] = getNext(iterators[index], index);
-            yield result!.value;
+            // Only the "return" result can be undefined (void),
+            // so we're okay here.
+            yield result!.value as T;
         }
     }
 }

src/client/pythonEnvironments/base/locator.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Event, Uri } from 'vscode';
+import { iterEmpty } from '../../common/utils/async';
+import { PythonEnvInfo, PythonEnvKind } from './info';
+import { BasicPythonEnvsChangedEvent, IPythonEnvsWatcher, PythonEnvsChangedEvent, PythonEnvsWatcher } from './watcher';
+
+/**
+ * An async iterator of `PythonEnvInfo`.
+ */
+export type PythonEnvsIterator = AsyncIterator<PythonEnvInfo, void>;
+
+/**
+ * An empty Python envs iterator.
+ */
+export const NOOP_ITERATOR: PythonEnvsIterator = iterEmpty<PythonEnvInfo>();
+
+/**
+ * The most basic info to send to a locator when requesting environments.
+ *
+ * This is directly correlated with the `BasicPythonEnvsChangedEvent`
+ * emitted by watchers.
+ *
+ * @prop kinds - if provided, results should be limited to these env kinds
+ */
+export type BasicPythonLocatorQuery = {
+    kinds?: PythonEnvKind[];
+};
+
+/**
+ * The full set of possible info to send to a locator when requesting environments.
+ *
+ * This is directly correlated with the `PythonEnvsChangedEvent`
+ * emitted by watchers.
+ *
+ * @prop - searchLocations - if provided, results should be limited to
+ *         within these locations
+ */
+export type PythonLocatorQuery = BasicPythonLocatorQuery & {
+    searchLocations?: Uri[];
+};
+
+type QueryForEvent<E> = E extends PythonEnvsChangedEvent ? PythonLocatorQuery : BasicPythonLocatorQuery;
+
+/**
+ * A single Python environment locator.
+ *
+ * Each locator object is responsible for identifying the Python
+ * environments in a single location, whether a directory, a directory
+ * tree, or otherwise.  That location is identified when the locator
+ * is instantiated.
+ *
+ * Based on the narrow focus of each locator, the assumption is that
+ * calling iterEnvs() to pick up a changed env is effectively no more
+ * expensive than tracking down that env specifically.  Consequently,
+ * events emitted via `onChanged` do not need to provide information
+ * for the specific environments that changed.
+ */
+export interface ILocator<E extends BasicPythonEnvsChangedEvent = PythonEnvsChangedEvent>
+    extends IPythonEnvsWatcher<E> {
+    /**
+     * Iterate over the enviroments known tos this locator.
+     *
+     * Locators are not required to have provide all info about
+     * an environment.  However, each yielded item will at least
+     * include all the `PythonEnvBaseInfo` data.
+     *
+     * @param query - if provided, the locator will limit results to match
+     */
+    iterEnvs(query?: QueryForEvent<E>): PythonEnvsIterator;
+
+    /**
+     * Find the given Python environment and fill in as much missing info as possible.
+     *
+     * If the locator can find the environment then the result is as
+     * much info about that env as the locator has.  At the least this
+     * will include all the `PythonEnvBaseInfo` data.  If a `PythonEnvInfo`
+     * was provided then the result will be a copy with any updates or
+     * extra info applied.
+     *
+     * If the locator could not find the environment then `undefined`
+     * is returned.
+     *
+     * @param env - the Python executable path or partial env info to find and update
+     */
+    resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined>;
+}
+
+interface IEmitter<E extends BasicPythonEnvsChangedEvent> {
+    fire(e: E): void;
+}
+
+/**
+ * The generic base for Python envs locators.
+ *
+ * By default `resolveEnv()` returns undefined.  Subclasses may override
+ * the method to provide an implementation.
+ *
+ * Subclasses will call `this.emitter.fire()` to emit events.
+ *
+ * Also, in most cases the default event type (`PythonEnvsChangedEvent`)
+ * should be used.  Only in low-level cases should you consider using
+ * `BasicPythonEnvsChangedEvent`.
+ */
+export abstract class LocatorBase<E extends BasicPythonEnvsChangedEvent = PythonEnvsChangedEvent> implements ILocator<E> {
+    public readonly onChanged: Event<E>;
+    protected readonly emitter: IEmitter<E>;
+    constructor(watcher: IPythonEnvsWatcher<E> & IEmitter<E>) {
+        this.emitter = watcher;
+        this.onChanged = watcher.onChanged;
+    }
+
+    public abstract iterEnvs(query?: QueryForEvent<E>): PythonEnvsIterator;
+
+    public async resolveEnv(_env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+        return undefined;
+    }
+}
+
+/**
+ * The base for most Python envs locators.
+ *
+ * By default `resolveEnv()` returns undefined.  Subclasses may override
+ * the method to provide an implementation.
+ *
+ * Subclasses will call `this.emitter.fire()` * to emit events.
+ *
+ * In most cases this is the class you will want to subclass.
+ * Only in low-level cases should you consider subclassing `LocatorBase`
+ * using `BasicPythonEnvsChangedEvent.
+ */
+export abstract class Locator extends LocatorBase {
+    constructor() {
+        super(new PythonEnvsWatcher());
+    }
+}

src/client/pythonEnvironments/base/locators.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { chain } from '../../common/utils/async';
+import { PythonEnvInfo } from './info';
+import { ILocator, NOOP_ITERATOR, PythonEnvsIterator, PythonLocatorQuery } from './locator';
+import { DisableableEnvsWatcher, PythonEnvsWatchers } from './watchers';
+
+/**
+ * A wrapper around a set of locators, exposing them as a single locator.
+ *
+ * Events and iterator results are combined.
+ */
+export class Locators extends PythonEnvsWatchers implements ILocator {
+    constructor(
+        // The locators will be watched as well as iterated.
+        private readonly locators: ReadonlyArray<ILocator>
+    ) {
+        super(locators);
+    }
+
+    public iterEnvs(query?: PythonLocatorQuery): PythonEnvsIterator {
+        const iterators = this.locators.map((loc) => loc.iterEnvs(query));
+        return chain(iterators);
+    }
+
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+        for (const locator of this.locators) {
+            const resolved = await locator.resolveEnv(env);
+            if (resolved !== undefined) {
+                return resolved;
+            }
+        }
+        return undefined;
+    }
+}
+
+/**
+ * A locator wrapper that can be disabled.
+ *
+ * If disabled, events emitted by the wrapped locator are discarded,
+ * `iterEnvs()` yields nothing, and `resolveEnv()` already returns
+ * `undefined`.
+ */
+export class DisableableLocator extends DisableableEnvsWatcher implements ILocator {
+    constructor(
+        // To wrapp more than one use `Locators`.
+        private readonly locator: ILocator
+    ) {
+        super(locator);
+    }
+
+    public iterEnvs(query?: PythonLocatorQuery): PythonEnvsIterator {
+        if (!this.enabled) {
+            return NOOP_ITERATOR;
+        }
+        return this.locator.iterEnvs(query);
+    }
+
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+        if (!this.enabled) {
+            return undefined;
+        }
+        return this.locator.resolveEnv(env);
+    }
+}

src/client/pythonEnvironments/base/watcher.ts

@@ -6,6 +6,11 @@
 import { Event, EventEmitter, Uri } from 'vscode';
 import { PythonEnvKind } from './info';
 
+// The use cases for `BasicPythonEnvsChangedEvent` are currently
+// hypothetical.  However, there's a real chance they may prove
+// useful for the concrete low-level locators.  So for now we are
+// keeping the separate "basic" type.
+
 /**
  * The most basic info for a Python environments event.
  *
@@ -40,17 +45,21 @@ export interface IPythonEnvsWatcher<E extends BasicPythonEnvsChangedEvent = Pyth
 }
 
 /**
- * This provides the fundamental functionality of a watcher for any event type.
+ * This provides the fundamental functionality of a Python envs watcher.
  *
  * Consumers register listeners (callbacks) using `onChanged`.  Each
  * listener is invoked when `fire()` is called.
  *
- * Note that in most cases classes will not inherit from this classes,
+ * Note that in most cases classes will not inherit from this class,
  * but instead keep a private watcher property.  The rule of thumb
  * is to follow whether or not consumers of *that* class should be able
  * to trigger events (via `fire()`).
+ *
+ * Also, in most cases the default event type (`PythonEnvsChangedEvent`)
+ * should be used.  Only in low-level cases should you consider using
+ * `BasicPythonEnvsChangedEvent`.
  */
-class WatcherBase<T> implements IPythonEnvsWatcher<T> {
+export class PythonEnvsWatcher<T extends BasicPythonEnvsChangedEvent = PythonEnvsChangedEvent> implements IPythonEnvsWatcher<T> {
     /**
      * The hook for registering event listeners (callbacks).
      */
@@ -68,49 +77,3 @@ class WatcherBase<T> implements IPythonEnvsWatcher<T> {
         this.didChange.fire(event);
     }
 }
-
-// The use cases for BasicPythonEnvsWatcher are currently hypothetical.
-// However, there's a real chance they may prove useful for the concrete
-// locators.  Adding BasicPythonEnvsWatcher later will be much harder
-// than removing it later, so we're leaving it for now.
-
-/**
- * A watcher for the basic Python environments events.
- *
- * This should be used only in low-level cases, with the most
- * rudimentary watchers.  Most of the time `PythonEnvsWatcher`
- * should be used instead.
- *
- * Note that in most cases classes will not inherit from this classes,
- * but instead keep a private watcher property.  The rule of thumb
- * is to follow whether or not consumers of *that* class should be able
- * to trigger events (via `fire()`).
- */
-export class BasicPythonEnvsWatcher extends WatcherBase<BasicPythonEnvsChangedEvent> {
-    /**
-     * Fire an event based on the given info.
-     */
-    public trigger(kind?: PythonEnvKind) {
-        this.fire({ kind });
-    }
-}
-
-/**
- * A general-use watcher for Python environments events.
- *
- * In most cases this is the class you will want to use or subclass.
- * Only in low-level cases should you consider using `BasicPythonEnvsWatcher`.
- *
- * Note that in most cases classes will not inherit from this classes,
- * but instead keep a private watcher property.  The rule of thumb
- * is to follow whether or not consumers of *that* class should be able
- * to trigger events (via `fire()`).
- */
-export class PythonEnvsWatcher extends WatcherBase<PythonEnvsChangedEvent> {
-    /**
-     * Fire an event based on the given info.
-     */
-    public trigger(kind?: PythonEnvKind, searchLocation?: Uri) {
-        this.fire({ kind, searchLocation });
-    }
-}

src/client/pythonEnvironments/base/watchers.ts

@@ -31,7 +31,7 @@ type EnvsEventListener = (e: PythonEnvsChangedEvent) => unknown;
  * If disabled, events emitted by the wrapped watcher are discarded.
  */
 export class DisableableEnvsWatcher implements IPythonEnvsWatcher {
-    private enabled = true;
+    protected enabled = true;
     constructor(
         // To wrap more than one use `PythonEnvWatchers`.
         private readonly wrapped: IPythonEnvsWatcher