Clarify what ILocator.resolveEnv() does.

Author: ericsnowcurrently

src/client/pythonEnvironments/base/locator.ts

@@ -62,16 +62,29 @@ export interface ILocator<E extends BasicPythonEnvsChangedEvent = PythonEnvsChan
     /**
      * 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;
 
     /**
-     * Fill in any missing info in the given data, if possible.
+     * 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.
      *
-     * The result is a copy of whatever was passed in.
+     * @param env - the Python executable path or partial env info to find and update
      */
-    resolveEnv(env: PythonEnvInfo): Promise<PythonEnvInfo | undefined>;
+    resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined>;
 }
 
 interface IEmitter<E extends BasicPythonEnvsChangedEvent> {
@@ -100,7 +113,7 @@ export abstract class LocatorBase<E extends BasicPythonEnvsChangedEvent = Python
 
     public abstract iterEnvs(query?: QueryForEvent<E>): PythonEnvsIterator;
 
-    public async resolveEnv(_env: PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+    public async resolveEnv(_env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
         return undefined;
     }
 }

src/client/pythonEnvironments/base/locators.ts

@@ -24,7 +24,7 @@ export class Locators extends PythonEnvsWatchers implements ILocator {
         return chain(iterators);
     }
 
-    public async resolveEnv(env: PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
         for (const locator of this.locators) {
             const resolved = await locator.resolveEnv(env);
             if (resolved !== undefined) {
@@ -57,7 +57,7 @@ export class DisableableLocator extends DisableableEnvsWatcher implements ILocat
         return this.locator.iterEnvs(query);
     }
 
-    public async resolveEnv(env: PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
         if (!this.enabled) {
             return undefined;
         }

src/test/pythonEnvironments/base/common.ts

@@ -3,7 +3,7 @@
 
 import { createDeferred } from '../../../client/common/utils/async';
 import { Architecture } from '../../../client/common/utils/platform';
-import { parseBasicVersionInfo } from '../../../client/common/utils/version';
+import { EMPTY_VERSION, parseBasicVersionInfo } from '../../../client/common/utils/version';
 import {
     PythonEnvInfo,
     PythonEnvKind,
@@ -16,13 +16,41 @@ import { PythonEnvsChangedEvent } from '../../../client/pythonEnvironments/base/
 export function createEnv(
     name: string,
     versionStr: string,
-    kind = PythonEnvKind.Unknown,
-    executable = 'python',
+    kind?: PythonEnvKind,
+    executable?: string,
     idStr?: string
 ): PythonEnvInfo {
+    if (kind === undefined) {
+        kind = PythonEnvKind.Unknown;
+    }
+    if (executable === undefined || executable === '') {
+        executable = 'python';
+    }
     const id = idStr ? idStr : `${kind}-${name}`;
+    const version = parseVersion(versionStr);
+    return {
+        id,
+        kind,
+        version,
+        name,
+        location: '',
+        arch: Architecture.x86,
+        executable: {
+            filename: executable,
+            sysPrefix: '',
+            mtime: -1,
+            ctime: -1
+        },
+        distro: { org: '' }
+    };
+}
+
+function parseVersion(versionStr: string): PythonVersion {
     const parsed = parseBasicVersionInfo<PythonVersion>(versionStr);
     if (!parsed) {
+        if (versionStr === '') {
+            return EMPTY_VERSION as PythonVersion;
+        }
         throw Error(`invalid version ${versionStr}`);
     }
     const { version, after } = parsed;
@@ -44,21 +72,7 @@ export function createEnv(
             serial: parseInt(serialStr, 10)
         };
     }
-    return {
-        id,
-        kind,
-        version,
-        name,
-        location: '',
-        arch: Architecture.x86,
-        executable: {
-            filename: executable,
-            sysPrefix: '',
-            mtime: -1,
-            ctime: -1
-        },
-        distro: { org: 'PSF' }
-    };
+    return version;
 }
 
 export function createLocatedEnv(
@@ -125,13 +139,14 @@ export class SimpleLocator extends Locator {
         }
         return iterator();
     }
-    public async resolveEnv(env: PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+        const envInfo: PythonEnvInfo = typeof env === 'string' ? createEnv('', '', undefined, env) : env;
         if (this.callbacks?.resolve === undefined) {
-            return env;
+            return envInfo;
         } else if (this.callbacks?.resolve === null) {
             return undefined;
         } else {
-            return this.callbacks.resolve(env);
+            return this.callbacks.resolve(envInfo);
         }
     }
 }