Add the base Python environments "watchers". (microsoft#13735)

Watchers are the event-based part of locators.

Author: Eric Snow

src/client/pythonEnvironments/base/watcher.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// tslint:disable:max-classes-per-file
+
+import { Event, EventEmitter, Uri } from 'vscode';
+import { PythonEnvKind } from './info';
+
+/**
+ * The most basic info for a Python environments event.
+ *
+ * @prop kind - the env kind, if any, affected by the event
+ */
+export type BasicPythonEnvsChangedEvent = {
+ kind?: PythonEnvKind;
+};
+
+/**
+ * The full set of possible info for a Python environments event.
+ *
+ * @prop searchLocation - the location, if any, affected by the event
+ */
+export type PythonEnvsChangedEvent = BasicPythonEnvsChangedEvent & {
+ searchLocation?: Uri;
+};
+
+/**
+ * A "watcher" for events related to changes to Python environemts.
+ *
+ * The watcher will notify listeners (callbacks registered through
+ * `onChanged`) of events at undetermined times. The actual emitted
+ * events, their source, and the timing is entirely up to the watcher
+ * implementation.
+ */
+export interface IPythonEnvsWatcher<E extends BasicPythonEnvsChangedEvent = PythonEnvsChangedEvent> {
+ /**
+ * The hook for registering event listeners (callbacks).
+ */
+ readonly onChanged: Event<E>;
+}
+
+/**
+ * This provides the fundamental functionality of a watcher for any event type.
+ *
+ * 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,
+ * 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()`).
+ */
+class WatcherBase<T> implements IPythonEnvsWatcher<T> {
+ /**
+ * The hook for registering event listeners (callbacks).
+ */
+ public readonly onChanged: Event<T>;
+ private readonly didChange = new EventEmitter<T>();
+
+ constructor() {
+ this.onChanged = this.didChange.event;
+ }
+
+ /**
+ * Send the event to all registered listeners.
+ */
+ public fire(event: 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

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Disposable, Event } from 'vscode';
+import { IPythonEnvsWatcher, PythonEnvsChangedEvent, PythonEnvsWatcher } from './watcher';
+
+/**
+ * A wrapper around a set of watchers, exposing them as a single watcher.
+ *
+ * If any of the wrapped watchers emits an event then this wrapper
+ * emits that event.
+ */
+export class PythonEnvsWatchers implements IPythonEnvsWatcher {
+ public readonly onChanged: Event<PythonEnvsChangedEvent>;
+ private watcher = new PythonEnvsWatcher();
+
+ constructor(watchers: ReadonlyArray<IPythonEnvsWatcher>) {
+ this.onChanged = this.watcher.onChanged;
+ watchers.forEach((w) => {
+ w.onChanged((e) => this.watcher.fire(e));
+ });
+ }
+}
+
+// This matches the `vscode.Event` arg.
+type EnvsEventListener = (e: PythonEnvsChangedEvent) => unknown;
+
+/**
+ * A watcher wrapper that can be disabled.
+ *
+ * If disabled, events emitted by the wrapped watcher are discarded.
+ */
+export class DisableableEnvsWatcher implements IPythonEnvsWatcher {
+ private enabled = true;
+ constructor(
+ // To wrap more than one use `PythonEnvWatchers`.
+ private readonly wrapped: IPythonEnvsWatcher
+ ) {}
+
+ /**
+ * Ensure that the watcher is enabled.
+ */
+ public enable() {
+ this.enabled = true;
+ }
+
+ /**
+ * Ensure that the watcher is disabled.
+ */
+ public disable() {
+ this.enabled = false;
+ }
+
+ // This matches the signature of `vscode.Event`.
+ public onChanged(listener: EnvsEventListener, thisArgs?: unknown, disposables?: Disposable[]): Disposable {
+ return this.wrapped.onChanged(
+ (e: PythonEnvsChangedEvent) => {
+ if (this.enabled) {
+ listener(e);
+ }
+ },
+ thisArgs,
+ disposables
+ );
+ }
+}

src/test/pythonEnvironments/base/watcher.unit.test.ts

@@ -0,0 +1,163 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as assert from 'assert';
+import { Uri } from 'vscode';
+import { PythonEnvKind } from '../../../client/pythonEnvironments/base/info';
+import {
+ BasicPythonEnvsChangedEvent,
+ BasicPythonEnvsWatcher,
+ PythonEnvsChangedEvent,
+ PythonEnvsWatcher
+} from '../../../client/pythonEnvironments/base/watcher';
+
+const KINDS_TO_TEST = [
+ PythonEnvKind.Unknown,
+ PythonEnvKind.System,
+ PythonEnvKind.Custom,
+ PythonEnvKind.OtherGlobal,
+ PythonEnvKind.Venv,
+ PythonEnvKind.Conda,
+ PythonEnvKind.OtherVirtual
+];
+
+suite('pyenvs watcher - BasicPythonEnvsWatcher', () => {
+ suite('fire()', () => {
+ test('empty event', () => {
+ const expected: BasicPythonEnvsChangedEvent = {};
+ const watcher = new BasicPythonEnvsWatcher();
+ let event: BasicPythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.fire(expected);
+
+ assert.equal(event, expected);
+ });
+
+ KINDS_TO_TEST.forEach((kind) => {
+ test(`non-empty event ("${kind}")`, () => {
+ const expected: BasicPythonEnvsChangedEvent = {
+ kind: kind
+ };
+ const watcher = new BasicPythonEnvsWatcher();
+ let event: BasicPythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.fire(expected);
+
+ assert.equal(event, expected);
+ });
+ });
+ });
+
+ suite('trigger()', () => {
+ test('empty event', () => {
+ const expected: BasicPythonEnvsChangedEvent = {
+ kind: undefined
+ };
+ const watcher = new BasicPythonEnvsWatcher();
+ let event: BasicPythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.trigger();
+
+ assert.deepEqual(event, expected);
+ });
+
+ KINDS_TO_TEST.forEach((kind) => {
+ test(`non-empty event ("${kind}")`, () => {
+ const expected: BasicPythonEnvsChangedEvent = {
+ kind: kind
+ };
+ const watcher = new BasicPythonEnvsWatcher();
+ let event: BasicPythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.trigger(kind);
+
+ assert.deepEqual(event, expected);
+ });
+ });
+ });
+});
+
+suite('pyenvs watcher - PythonEnvsWatcher', () => {
+ const location = Uri.file('some-dir');
+
+ suite('fire()', () => {
+ test('empty event', () => {
+ const expected: PythonEnvsChangedEvent = {};
+ const watcher = new PythonEnvsWatcher();
+ let event: PythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.fire(expected);
+
+ assert.equal(event, expected);
+ });
+
+ KINDS_TO_TEST.forEach((kind) => {
+ test(`non-empty event ("${kind}")`, () => {
+ const expected: PythonEnvsChangedEvent = {
+ kind: kind,
+ searchLocation: location
+ };
+ const watcher = new PythonEnvsWatcher();
+ let event: PythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.fire(expected);
+
+ assert.equal(event, expected);
+ });
+ });
+ });
+
+ suite('trigger()', () => {
+ test('empty event', () => {
+ const expected: PythonEnvsChangedEvent = {
+ kind: undefined,
+ searchLocation: undefined
+ };
+ const watcher = new PythonEnvsWatcher();
+ let event: PythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.trigger();
+
+ assert.deepEqual(event, expected);
+ });
+
+ KINDS_TO_TEST.forEach((kind) => {
+ test(`non-empty event ("${kind}")`, () => {
+ const expected: PythonEnvsChangedEvent = {
+ kind: kind,
+ searchLocation: location
+ };
+ const watcher = new PythonEnvsWatcher();
+ let event: PythonEnvsChangedEvent | undefined;
+ watcher.onChanged((e) => {
+ event = e;
+ });
+
+ watcher.trigger(kind, location);
+
+ assert.deepEqual(event, expected);
+ });
+ });
+ });
+});