Provide options support for refreshInterpreters API. (#18316)

* Provide options support for refreshInterpreters API.

* Fire event to indicate cache is getting cleared.

Author: karthiknadig

src/client/apiTypes.ts

@@ -108,6 +108,10 @@ export interface ActiveInterpreterChangedParams {
     resource?: Uri;
 }
 
+export interface RefreshInterpretersOptions {
+    clearCache?: boolean;
+}
+
 export interface IProposedExtensionAPI {
     environment: {
         /**
@@ -151,8 +155,11 @@ export interface IProposedExtensionAPI {
          * This API will re-trigger environment discovery. Extensions can wait on the returned
          * promise to get the updated interpreters list. If there is a refresh already going on
          * then it returns the promise for that refresh.
+         * @param options : [optional]
+         *     * clearCache : When true, this will clear the cache before interpreter refresh
+         *                    is triggered.
          */
-        refreshInterpreters(): Promise<string[] | undefined>;
+        refreshInterpreters(options?: RefreshInterpretersOptions): Promise<string[] | undefined>;
         /**
          * Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
          * refreshes going on.

src/client/proposedApi.ts

@@ -8,6 +8,7 @@ import {
     InterpreterDetailsOptions,
     InterpretersChangedParams,
     IProposedExtensionAPI,
+    RefreshInterpretersOptions,
 } from './apiTypes';
 import { IConfigurationService, IInterpreterPathService, Resource } from './common/types';
 import { IComponentAdapter } from './interpreter/contracts';
@@ -97,8 +98,8 @@ export function buildProposedApi(
             setActiveInterpreter(interpreterPath: string, resource?: Resource): Promise<void> {
                 return interpreterPathService.update(resource, ConfigurationTarget.Workspace, interpreterPath);
             },
-            async refreshInterpreters(): Promise<string[] | undefined> {
-                await discoveryApi.triggerRefresh(undefined);
+            async refreshInterpreters(options?: RefreshInterpretersOptions): Promise<string[] | undefined> {
+                await discoveryApi.triggerRefresh(options ? { clearCache: options.clearCache } : undefined);
                 const paths = discoveryApi.getEnvs().map((e) => e.executable.filename);
                 return Promise.resolve(paths);
             },

src/client/pythonEnvironments/base/locator.ts

@@ -182,7 +182,7 @@ export interface IDiscoveryAPI {
     /**
      * Triggers a new refresh for query if there isn't any already running.
      */
-    triggerRefresh(query?: PythonLocatorQuery): Promise<void>;
+    triggerRefresh(query?: PythonLocatorQuery & { clearCache?: boolean }): Promise<void>;
     /**
      * Get current list of known environments.
      */

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

@@ -51,6 +51,11 @@ export interface IEnvsCollectionCache {
      * validating cache.
      */
     validateCache(): Promise<void>;
+
+    /**
+     * Clears the in-memory cache. This can be used for hard refresh.
+     */
+    clearCache(): Promise<void>;
 }
 
 export type PythonEnvCompleteInfo = { hasCompleteInfo?: boolean } & PythonEnvInfo;
@@ -134,6 +139,15 @@ export class PythonEnvInfoCache extends PythonEnvsWatcher<PythonEnvCollectionCha
             await this.persistentStorage.store(this.envs);
         }
     }
+
+    public clearCache(): Promise<void> {
+        this.envs.forEach((e) => {
+            this.fire({ old: e, new: undefined });
+        });
+        reportInterpretersChanged([{ path: undefined, type: 'clear-all' }]);
+        this.envs = [];
+        return Promise.resolve();
+    }
 }
 
 /**

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

@@ -6,7 +6,6 @@ import '../../../../common/extensions';
 import { createDeferred } from '../../../../common/utils/async';
 import { StopWatch } from '../../../../common/utils/stopWatch';
 import { traceError } from '../../../../logging';
-import { reportInterpretersChanged } from '../../../../proposedApi';
 import { sendTelemetryEvent } from '../../../../telemetry';
 import { EventName } from '../../../../telemetry/constants';
 import { PythonEnvInfo } from '../../info';
@@ -81,23 +80,20 @@ export class EnvsCollectionService extends PythonEnvsWatcher<PythonEnvCollection
         return query ? cachedEnvs.filter(getQueryFilter(query)) : cachedEnvs;
     }
 
-    public triggerRefresh(query?: PythonLocatorQuery): Promise<void> {
+    public triggerRefresh(query?: PythonLocatorQuery & { clearCache?: boolean }): Promise<void> {
         let refreshPromise = this.getRefreshPromiseForQuery(query);
         if (!refreshPromise) {
             refreshPromise = this.startRefresh(query);
         }
         return refreshPromise;
     }
 
-    private startRefresh(query: PythonLocatorQuery | undefined): Promise<void> {
+    private startRefresh(query: (PythonLocatorQuery & { clearCache?: boolean }) | undefined): Promise<void> {
         const stopWatch = new StopWatch();
         const deferred = createDeferred<void>();
 
-        if (!query) {
-            // `undefined` query means this is full refresh of environments.
-            // Trigger an event indicating that we need to clear everything and start
-            // fresh.
-            reportInterpretersChanged([{ path: undefined, type: 'clear-all' }]);
+        if (query?.clearCache) {
+            this.cache.clearCache();
         }
         // Ensure we set this before we trigger the promise to accurately track when a refresh has started.
         this.refreshPromises.set(query, deferred.promise);

src/test/pythonEnvironments/base/locators/composite/envsCollectionService.unit.test.ts

@@ -158,7 +158,6 @@ suite('Python envs locator - Environments Collection', async () => {
             }),
         );
 
-        sinon.assert.calledWithExactly(reportInterpretersChangedStub, [{ path: undefined, type: 'clear-all' }]);
         envs.forEach((e) => {
             sinon.assert.calledWithExactly(reportInterpretersChangedStub, [
                 {
@@ -167,9 +166,7 @@ suite('Python envs locator - Environments Collection', async () => {
                 },
             ]);
         });
-
-        // One for each environment and one for global 'clear-all' event.
-        sinon.assert.callCount(reportInterpretersChangedStub, envs.length + 1);
+        sinon.assert.callCount(reportInterpretersChangedStub, envs.length);
     });
 
     test('triggerRefresh() refreshes the collection and storage with any new environments', async () => {
@@ -204,7 +201,6 @@ suite('Python envs locator - Environments Collection', async () => {
         assertEnvsEqual(storage, expected);
 
         const eventData = [
-            { path: undefined, type: 'clear-all' },
             {
                 path: path.join(TEST_LAYOUT_ROOT, 'doesNotExist'),
                 type: 'remove',
@@ -307,7 +303,6 @@ suite('Python envs locator - Environments Collection', async () => {
         assertEnvsEqual(envs, expected);
 
         const eventData = [
-            { path: undefined, type: 'clear-all' },
             {
                 path: path.join(TEST_LAYOUT_ROOT, 'doesNotExist'),
                 type: 'remove',
@@ -404,7 +399,6 @@ suite('Python envs locator - Environments Collection', async () => {
         );
 
         const eventData = [
-            { path: undefined, type: 'clear-all' },
             {
                 path: path.join(TEST_LAYOUT_ROOT, 'doesNotExist'),
                 type: 'remove',
@@ -447,7 +441,6 @@ suite('Python envs locator - Environments Collection', async () => {
         expect(isFired).to.equal(true);
 
         const eventData = [
-            { path: undefined, type: 'clear-all' },
             {
                 path: path.join(TEST_LAYOUT_ROOT, 'conda1', 'python.exe'),
                 type: 'add',
@@ -614,12 +607,6 @@ suite('Python envs locator - Environments Collection', async () => {
             downstreamEvents.sort((a, b) => (a.type && b.type ? a.type?.localeCompare(b.type) : 0)),
         );
 
-        [
-            { path: undefined, type: 'clear-all' },
-            { path: undefined, type: 'clear-all' },
-        ].forEach((d) => {
-            sinon.assert.calledWithExactly(reportInterpretersChangedStub, [d]);
-        });
-        sinon.assert.calledTwice(reportInterpretersChangedStub);
+        sinon.assert.notCalled(reportInterpretersChangedStub);
     });
 });