ux: clarify missing uv prerequisite

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: eleanorjboyd

src/common/localize.ts

@@ -383,8 +383,10 @@ export namespace UvInstallStrings {
     export const clickToInstallPython = l10n.t('No Python found, click to install');
     export const selectPythonVersion = l10n.t('Select Python version to install');
     export const installUvForVersionLookupPrompt = l10n.t(
-        'The Python Environments extension uses uv to view and install available Python versions. Install uv now? This will download and run an installer from https://astral.sh. Alternatively, cancel and install Python yourself.',
+        'The Global environment manager uses uv to find and install Python versions. uv was not found. Install uv to continue, or install Python another way.',
     );
+    export const otherPythonInstallationOptions = l10n.t('Other installation options');
+    export const close = l10n.t('Close');
     export const installed = l10n.t('installed');
     export const fetchingVersions = l10n.t('Fetching available Python versions...');
     export const failedToFetchVersions = l10n.t('Failed to fetch available Python versions');

src/managers/builtin/uvPythonInstaller.ts

@@ -11,6 +11,8 @@ import {
     TaskScope,
 } from 'vscode';
 import { spawnProcess } from '../../common/childProcess.apis';
+import { launchBrowser } from '../../common/env.apis';
+import { showErrorMessageWithLogs } from '../../common/errors/utils';
 import { Common, UvInstallStrings } from '../../common/localize';
 import { traceError, traceInfo, traceLog, traceWarn } from '../../common/logging';
 import { getGlobalPersistentState } from '../../common/persistentState';
@@ -28,6 +30,8 @@ export const UV_INSTALL_PYTHON_DONT_ASK_KEY = 'python-envs:uv:UV_INSTALL_PYTHON_
 
 const MAX_PROMPT_DETAIL_LENGTH = 120;
 const TASK_TIMEOUT_MS = 5 * 60 * 1000;
+const PYTHON_INSTALLATION_OPTIONS_URL =
+    'https://code.visualstudio.com/docs/python/python-tutorial#_install-a-python-interpreter';
 
 // Accept only numeric release segments before forwarding script-controlled input to uv.
 const INSTALLABLE_PYTHON_VERSION = /^\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.dev\d+)?$/i;
@@ -235,7 +239,17 @@ async function ensureUvForVersionLookup(
     if (selection !== UvInstallStrings.installUv) {
         return 'declined';
     }
+    return installUvForVersionLookup(log);
+}
+
+async function installUvForVersionLookup(
+    log?: LogOutputChannel,
+    showInstallFailure = false,
+): Promise<EnsureUvForInlineScriptVersionLookupResult> {
     if (!(await installUv(log))) {
+        if (showInstallFailure) {
+            await showErrorMessageWithLogs(UvInstallStrings.uvInstallFailed, log);
+        }
         return 'failed';
     }
     if (await isUvInstalled(log)) {
@@ -252,7 +266,25 @@ async function ensureUvForVersionLookup(
  * @returns Whether uv is available for version lookup.
  */
 export async function ensureUvForPythonVersionLookup(log?: LogOutputChannel): Promise<boolean> {
-    return (await ensureUvForVersionLookup(UvInstallStrings.installUvForVersionLookupPrompt, log)) === 'available';
+    if (await isUvInstalled(log)) {
+        return true;
+    }
+
+    const selection = await showInformationMessage(
+        UvInstallStrings.installUvForVersionLookupPrompt,
+        { modal: true },
+        UvInstallStrings.installUv,
+        UvInstallStrings.otherPythonInstallationOptions,
+        UvInstallStrings.close,
+    );
+    if (selection === UvInstallStrings.otherPythonInstallationOptions) {
+        await launchBrowser(PYTHON_INSTALLATION_OPTIONS_URL);
+        return false;
+    }
+    if (selection !== UvInstallStrings.installUv) {
+        return false;
+    }
+    return (await installUvForVersionLookup(log, true)) === 'available';
 }
 
 export async function ensureUvForInlineScriptVersionLookupDetailed(

src/test/managers/builtin/uvPythonInstaller.unit.test.ts

@@ -4,6 +4,7 @@ import * as path from 'path';
 import * as sinon from 'sinon';
 import { CancellationToken, LogOutputChannel, ShellExecution, TaskExecution, TaskProcessEndEvent } from 'vscode';
 import * as childProcessApis from '../../../common/childProcess.apis';
+import * as envApis from '../../../common/env.apis';
 import { Common, UvInstallStrings } from '../../../common/localize';
 import * as persistentState from '../../../common/persistentState';
 import { EventNames } from '../../../common/telemetry/constants';
@@ -36,6 +37,7 @@ suite('uvPythonInstaller - promptInstallPythonViaUv', () => {
     let isUvInstalledStub: sinon.SinonStub;
     let showErrorMessageStub: sinon.SinonStub;
     let showInformationMessageStub: sinon.SinonStub;
+    let launchBrowserStub: sinon.SinonStub;
     let sendTelemetryEventStub: sinon.SinonStub;
     let mockState: { get: sinon.SinonStub; set: sinon.SinonStub; clear: sinon.SinonStub };
 
@@ -53,6 +55,7 @@ suite('uvPythonInstaller - promptInstallPythonViaUv', () => {
         sinon.stub(helpers, 'getUvExecutable').resolves('uv');
         showErrorMessageStub = sinon.stub(windowApis, 'showErrorMessage');
         showInformationMessageStub = sinon.stub(windowApis, 'showInformationMessage');
+        launchBrowserStub = sinon.stub(envApis, 'launchBrowser').resolves(true);
         sendTelemetryEventStub = sinon.stub(telemetrySender, 'sendTelemetryEvent');
     });
 
@@ -289,9 +292,31 @@ suite('uvPythonInstaller - promptInstallPythonViaUv', () => {
             UvInstallStrings.installUvForVersionLookupPrompt,
             { modal: true },
             UvInstallStrings.installUv,
+            UvInstallStrings.otherPythonInstallationOptions,
+            UvInstallStrings.close,
         );
     });
 
+    test('should open alternate Python installation guidance', async () => {
+        isUvInstalledStub.resolves(false);
+        showInformationMessageStub.resolves(UvInstallStrings.otherPythonInstallationOptions);
+
+        assert.strictEqual(await ensureUvForPythonVersionLookup(mockLog), false);
+        sinon.assert.calledOnceWithExactly(
+            launchBrowserStub,
+            'https://code.visualstudio.com/docs/python/python-tutorial#_install-a-python-interpreter',
+        );
+    });
+
+    test('should close global Python version lookup without installing uv', async () => {
+        isUvInstalledStub.resolves(false);
+        showInformationMessageStub.resolves(UvInstallStrings.close);
+
+        assert.strictEqual(await ensureUvForPythonVersionLookup(mockLog), false);
+        sinon.assert.notCalled(launchBrowserStub);
+        assert.strictEqual(showErrorMessageStub.callCount, 0);
+    });
+
     test('should install uv for global Python version lookup after consent', async () => {
         isUvInstalledStub.onFirstCall().resolves(false);
         isUvInstalledStub.onSecondCall().resolves(true);
@@ -303,6 +328,17 @@ suite('uvPythonInstaller - promptInstallPythonViaUv', () => {
         assert.strictEqual(executeTaskStub.callCount, 1);
     });
 
+    test('should report a failed uv installation for global Python version lookup', async () => {
+        isUvInstalledStub.resolves(false);
+        showInformationMessageStub.resolves(UvInstallStrings.installUv);
+        showErrorMessageStub.resolves(Common.viewLogs);
+        stubUvInstallTask(1);
+
+        assert.strictEqual(await ensureUvForPythonVersionLookup(mockLog), false);
+        sinon.assert.calledOnceWithExactly(showErrorMessageStub, UvInstallStrings.uvInstallFailed, Common.viewLogs);
+        sinon.assert.calledOnce(mockLog.show as sinon.SinonStub);
+    });
+
     test('should install uv before fetching versions and selecting Python', async () => {
         const order: string[] = [];
         isUvInstalledStub.onFirstCall().resolves(false);
@@ -563,6 +599,7 @@ suite('uvPythonInstaller - executable handoff', () => {
     let spawnStub: sinon.SinonStub;
     let executeTaskStub: sinon.SinonStub;
     let telemetryStub: sinon.SinonStub;
+    let showInformationMessageStub: sinon.SinonStub;
     let expectedExecutable: string;
     const pythonPath = path.join(home, 'managed-python', 'python');
 
@@ -588,7 +625,7 @@ suite('uvPythonInstaller - executable handoff', () => {
         expectedExecutable = path.join(installDir, 'uv');
         telemetryStub = sinon.stub(telemetrySender, 'sendTelemetryEvent');
         sinon.stub(windowApis, 'showErrorMessage');
-        sinon.stub(windowApis, 'showInformationMessage');
+        showInformationMessageStub = sinon.stub(windowApis, 'showInformationMessage');
         sinon
             .stub(windowApis, 'withProgress')
             .callsFake(async (_options, task) =>
@@ -662,6 +699,19 @@ suite('uvPythonInstaller - executable handoff', () => {
         assert(!telemetryStub.calledWith(EventNames.UV_PYTHON_INSTALL_FAILED));
     });
 
+    test('uses the installed executable to populate the Global version picker when PATH is unchanged', async () => {
+        const originalPath = process.env.PATH;
+        showInformationMessageStub.resolves(UvInstallStrings.installUv);
+        sinon.stub(windowApis, 'showQuickPick').callsFake(async (items) => (Array.isArray(items) ? items[0] : undefined));
+
+        assert.strictEqual(await selectPythonVersionToInstall(), '3.11.15');
+
+        assert.strictEqual(process.env.PATH, originalPath);
+        sinon.assert.calledWith(spawnStub, expectedExecutable, ['--version']);
+        sinon.assert.calledWith(spawnStub, expectedExecutable, ['python', 'list', '--output-format', 'json']);
+        assert.strictEqual(await helpers.getUvExecutable(), expectedExecutable);
+    });
+
     test('does not replace executable resolution after an installer failure', async () => {
         taskExitCode = 1;
         assert.strictEqual(await installPythonWithUv(), undefined);