Refactor Python installation logic and compatibility checks

Author: Jason2866

src/installer/get-python.js

@@ -14,90 +14,62 @@ import path from 'path';
 import { promisify } from 'util';
 
 const execFile = promisify(require('child_process').execFile);
+const FALLBACK_PYTHON_VERSION = '3.13';
 
 /**
  * Simple logger for minimal output with timestamp
- * @param {string} level - Log level ('info', 'warn', 'error')
- * @param {string} message - Log message to output
  */
 function log(level, message) {
   const timestamp = new Date().toISOString();
-  // eslint-disable-next-line no-console
   console[level](`[${timestamp}] [Python-Installer] ${message}`);
 }
 
 /**
- * Check if Python version meets compatibility requirements
- * Supports different validation modes for finding existing vs installing new Python
- * @param {string} pythonVersion - Python version string (e.g., "3.13.1")
- * @param {boolean} forInstallation - If true, only allows 3.13.x; if false, allows 3.10-3.13
- * @returns {boolean} True if version is compatible with requirements
+ * Check if Python version is compatible (3.10-3.13)
  */
-function isPythonVersionCompatible(pythonVersion, forInstallation = false) {
+function isPythonCompatible(pythonVersion) {
   const versionParts = pythonVersion.split('.');
   const major = parseInt(versionParts[0], 10);
   const minor = parseInt(versionParts[1], 10);
 
-  if (major !== 3) {
-    return false;
-  }
-
-  if (forInstallation) {
-    return minor === 13; // Only 3.13.x for new installations
-  } else {
-    return minor >= 10 && minor <= 13; // 3.10-3.13 for finding existing installations
-  }
+  return major === 3 && minor >= 10 && minor <= 13;
 }
 
 /**
- * Search for existing Python executable in system PATH with version validation
- * Scans through PATH directories to find compatible Python installations.
- * Accepts Python versions 3.10 through 3.13. Returns first valid installation found.
- * @returns {Promise<string|null>} Path to first valid Python executable or null if not found
- * @throws {Error} If distutils module is missing in found Python installation
+ * Search for existing compatible Python installation (3.10-3.13) in system PATH
  */
 export async function findPythonExecutable() {
   const exenames = proc.IS_WINDOWS ? ['python.exe'] : ['python3', 'python'];
   const envPath = process.env.PLATFORMIO_PATH || process.env.PATH;
-  const errors = [];
 
   log('info', 'Searching for compatible Python installation (3.10-3.13)');
 
-  // Search through all PATH locations for Python executables with early exit on first match
   for (const location of envPath.split(path.delimiter)) {
     for (const exename of exenames) {
       const executable = path.normalize(path.join(location, exename)).replace(/"/g, '');
+      
       try {
-        if (
-          fs.existsSync(executable) &&
-          (await isValidPythonVersion(executable)) &&
-          (await callInstallerScript(executable, ['check', 'python']))
-        ) {
+        if (fs.existsSync(executable) && 
+            await isValidPythonVersion(executable) &&
+            await callInstallerScript(executable, ['check', 'python'])) {
           log('info', `Found compatible Python: ${executable}`);
           return executable;
         }
       } catch (err) {
-        errors.push(err);
+        // Continue searching, but log significant errors
+        if (err.message && !err.message.includes('timeout')) {
+          log('warn', `Python check failed for ${executable}: ${err.message}`);
+        }
       }
     }
   }
 
-  // Handle specific error conditions that should be propagated
-  for (const err of errors) {
-    if (err.toString().includes('Could not find distutils module')) {
-      throw err;
-    }
-  }
-
-  log('info', 'No compatible system Python found, will install Python 3.13');
+  log('info', 'No compatible Python found, will install Python 3.13 via UV');
   return null;
 }
 
 /**
- * Validate Python executable version and basic functionality
- * This function is used for FINDING existing installations, not for installation validation
- * @param {string} executable - Full path to Python executable
- * @returns {Promise<boolean>} True if Python version is acceptable (3.10-3.13)
+ * Validate Python executable version (3.10-3.13)
  */
 async function isValidPythonVersion(executable) {
   try {
@@ -113,218 +85,151 @@ async function isValidPythonVersion(executable) {
       return false;
     }
 
-    return isPythonVersionCompatible(versionMatch[1], false); // Allow 3.10-3.13 for finding existing
+    const version = versionMatch[1];
+    const isCompatible = isPythonCompatible(version);
+    
+    if (isCompatible) {
+      log('info', `Found Python ${version}`);
+    }
+    
+    return isCompatible;
   } catch {
     return false;
   }
 }
 
 /**
- * Check if UV (astral-sh/uv) package manager is available on the system
- * UV is a fast Python package installer and resolver written in Rust
- * @returns {Promise<boolean>} True if UV is installed and accessible via PATH
+ * Check if UV package manager is available
  */
 async function isUVAvailable() {
   try {
     await execFile('uv', ['--version'], { timeout: 5000 });
-    log('info', 'UV is available on system');
+    log('info', 'UV is available');
     return true;
   } catch {
-    log('info', 'UV not found on system');
+    log('info', 'UV not found, will install');
     return false;
   }
 }
 
 /**
- * Install UV package manager using official installation scripts
- * Downloads and runs platform-specific installer from astral.sh
- * @returns {Promise<void>}
- * @throws {Error} If UV installation fails
+ * Install UV package manager
  */
 async function installUV() {
   log('info', 'Installing UV package manager');
 
   try {
     if (proc.IS_WINDOWS) {
-      // Windows: Use PowerShell with official installer script
-      await execFile(
-        'powershell',
-        [
-          '-NoProfile',
-          '-ExecutionPolicy',
-          'Bypass',
-          '-Command',
-          'irm https://astral.sh/uv/install.ps1 | iex',
-        ],
-        { timeout: 120000 },
-      );
+      await execFile('powershell', [
+        '-NoProfile',
+        '-ExecutionPolicy', 'Bypass',
+        '-Command',
+        'irm https://astral.sh/uv/install.ps1 | iex'
+      ], { timeout: 120000 });
     } else {
-      // Unix/Linux/macOS: Use shell with curl installer
       await execFile('sh', ['-c', 'curl -LsSf https://astral.sh/uv/install.sh | sh'], {
-        timeout: 120000,
+        timeout: 120000
       });
     }
-
     log('info', 'UV installation completed');
   } catch (err) {
     throw new Error(`Failed to install UV: ${err.message}`);
   }
 }
 
 /**
- * Install Python using UV package manager
- * Uses UV to download and install Python from astral-sh/python-build-standalone
- * Automatically handles platform detection, download, verification, and extraction
- * @param {string} destinationDir - Target installation directory
- * @param {string} pythonVersion - Python version to install (default: "3.13")
- * @returns {Promise<string>} Path to installed Python directory
- * @throws {Error} If UV installation or Python installation fails
+ * Install Python 3.13 using UV
  */
-async function installPythonWithUV(destinationDir, pythonVersion = '3.13') {
-  log('info', `Installing Python ${pythonVersion} using UV`);
+async function installPython313WithUV(destinationDir) {
+  log('info', `Installing Python ${FALLBACK_PYTHON_VERSION} using UV`);
 
-  // Ensure UV is available, install if necessary
+  // Ensure UV is available
   if (!(await isUVAvailable())) {
     await installUV();
   }
 
-  // Clean up any existing installation to avoid conflicts
+  // Clean and create destination directory
   try {
     await fs.promises.rm(destinationDir, { recursive: true, force: true });
-  } catch (err) {
-    // Ignore cleanup errors (directory might not exist)
+  } catch {
+    // Ignore if directory doesn't exist
   }
-
-  // Create destination directory structure
   await fs.promises.mkdir(destinationDir, { recursive: true });
 
-  try {
-    // Configure environment for UV Python installation
-    const env = {
-      ...process.env,
-      UV_PYTHON_INSTALL_DIR: destinationDir,
-      UV_CACHE_DIR: path.join(core.getTmpDir(), 'uv-cache'),
-    };
+  // Install Python via UV
+  const env = {
+    ...process.env,
+    UV_PYTHON_INSTALL_DIR: destinationDir,
+    UV_CACHE_DIR: path.join(core.getTmpDir(), 'uv-cache'),
+  };
 
-    // Execute UV Python installation command
-    await execFile('uv', ['python', 'install', pythonVersion], {
+  try {
+    await execFile('uv', ['python', 'install', FALLBACK_PYTHON_VERSION], {
       env,
-      timeout: 300000, // 5 minutes timeout for download and installation
+      timeout: 300000, // 5 minutes
       cwd: destinationDir,
     });
 
-    // Verify that Python executable was successfully installed
-    await ensurePythonExeExists(destinationDir, pythonVersion);
-
-    log('info', `Python ${pythonVersion} installation completed: ${destinationDir}`);
+    log('info', `Python ${FALLBACK_PYTHON_VERSION} installation completed: ${destinationDir}`);
     return destinationDir;
   } catch (err) {
     throw new Error(`UV Python installation failed: ${err.message}`);
   }
 }
 
 /**
- * Verify that Python executable exists in the installed directory
- * Searches through common installation paths where UV might place Python executables
- * @param {string} pythonDir - Directory containing Python installation
- * @param {string} pythonVersion - Python version for path construction (default: "3.13")
- * @returns {Promise<boolean>} True if executable exists and is accessible
- * @throws {Error} If no Python executable found in expected locations
+ * Find Python executable in installed directory
  */
-async function ensurePythonExeExists(pythonDir, pythonVersion = '3.13') {
-  // UV typically installs to subdirectories organized by version
-  const possiblePaths = [
-    pythonDir, // Direct installation in target directory
-    path.join(pythonDir, 'python'),
-    path.join(pythonDir, `python-${pythonVersion}`),
-    path.join(pythonDir, pythonVersion),
+function getPythonExecutablePath(pythonDir) {
+  const exeName = proc.IS_WINDOWS ? 'python.exe' : 'python3';
+  
+  // Common UV installation paths
+  const searchPaths = [
+    path.join(pythonDir, exeName),
+    path.join(pythonDir, 'bin', exeName),
+    path.join(pythonDir, FALLBACK_PYTHON_VERSION, exeName),
+    path.join(pythonDir, FALLBACK_PYTHON_VERSION, 'bin', exeName),
   ];
 
-  const executables = proc.IS_WINDOWS ? ['python.exe'] : ['python3', 'python'];
-
-  for (const basePath of possiblePaths) {
-    // Check for executable in root of installation path
-    for (const exeName of executables) {
-      try {
-        await fs.promises.access(path.join(basePath, exeName));
-        return true;
-      } catch (err) {
-        // Continue trying other combinations
-      }
-    }
-
-    // Check for executable in bin subdirectory (Unix-style layout)
-    const binDir = path.join(basePath, 'bin');
-    for (const exeName of executables) {
-      try {
-        await fs.promises.access(path.join(binDir, exeName));
-        return true;
-      } catch (err) {
-        // Continue trying other combinations
-      }
+  for (const execPath of searchPaths) {
+    try {
+      fs.accessSync(execPath, fs.constants.X_OK);
+      log('info', `Found Python executable: ${execPath}`);
+      return execPath;
+    } catch {
+      // Continue searching
     }
   }
 
-  throw new Error('Python executable does not exist after UV installation!');
+  throw new Error(`Could not find Python executable in ${pythonDir}`);
 }
 
 /**
- * Main entry point for installing Python distribution using UV
- * This replaces the legacy complex installation logic with a simple UV-based approach
- * @param {string} destinationDir - Target installation directory
- * @param {object} options - Optional configuration (kept for API compatibility)
- * @returns {Promise<string>} Path to installed Python directory
- * @throws {Error} If Python installation fails for any reason
+ * Main entry point: find existing compatible Python (3.10-3.13) or install Python 3.13 via UV
  */
 export async function installPortablePython(destinationDir) {
-  log('info', 'Starting Python 3.13 installation');
+  log('info', 'Starting Python setup (detecting 3.10-3.13, installing 3.13 if needed)');
 
-  // UV-based installation is now the only supported method
   try {
-    return await installPythonWithUV(destinationDir, '3.13');
-  } catch (uvError) {
-    log('error', `UV installation failed: ${uvError.message}`);
+    // Try to find existing compatible Python first
+    const existingPython = await findPythonExecutable();
+    if (existingPython) {
+      log('info', `Using existing compatible Python: ${existingPython}`);
+      return path.dirname(existingPython);
+    }
+
+    // No compatible Python found, install Python 3.13 via UV
+    log('info', 'No compatible Python installation found, installing Python 3.13');
+    return await installPython313WithUV(destinationDir);
+    
+  } catch (error) {
+    log('error', `Python setup failed: ${error.message}`);
     throw new Error(
-      `Python installation failed: ${uvError.message}. Please ensure UV can be installed and internet connection is available.`,
+      `Python installation failed: ${error.message}. ` +
+      `Please ensure internet connection is available and system supports UV installation.`
     );
   }
 }
 
-/**
- * Locate Python executable in an installed Python directory
- * Searches through common locations where UV might install Python executables
- * @param {string} pythonDir - Python installation directory to search
- * @returns {Promise<string>} Full path to Python executable
- * @throws {Error} If no executable found in the directory
- */
-function getPythonExecutablePath(pythonDir) {
-  const executables = proc.IS_WINDOWS ? ['python.exe'] : ['python3', 'python'];
-
-  // Check common locations where UV might install Python
-  const searchPaths = [
-    pythonDir,
-    path.join(pythonDir, 'bin'),
-    path.join(pythonDir, 'python'),
-    path.join(pythonDir, 'python-3.13'),
-    path.join(pythonDir, '3.13'),
-    path.join(pythonDir, '3.13', 'bin'),
-  ];
-
-  for (const searchPath of searchPaths) {
-    for (const exeName of executables) {
-      const fullPath = path.join(searchPath, exeName);
-      try {
-        fs.accessSync(fullPath, fs.constants.X_OK);
-        log('info', `Found Python executable: ${fullPath}`);
-        return fullPath;
-      } catch (err) {
-        // Continue searching through all combinations
-      }
-    }
-  }
-
-  throw new Error(`Could not find Python executable in ${pythonDir}`);
-}
-
-// Export utility functions for external use
-export { isPythonVersionCompatible, isUVAvailable, installUV, getPythonExecutablePath };
+// Export utility functions
+export { isPythonCompatible, isUVAvailable, installUV, getPythonExecutablePath };