Function ensureVenv

packages/python/src/utils.ts:79–143

({
  pythonVersion,
  venvPath,
  uvPath,
  uvCacheDir,
  quiet,
}: {
  pythonVersion: { pythonPath: string; major?: number; minor?: number };
  venvPath: string;
  uvPath?: string | null;
  uvCacheDir?: string;
  quiet?: boolean;
})

}

export async function ensureVenv({
  pythonVersion,
  venvPath,
  uvPath,
  uvCacheDir,
  quiet,
}: {
  pythonVersion: { pythonPath: string; major?: number; minor?: number };
  venvPath: string;
  uvPath?: string | null;
  uvCacheDir?: string;
  quiet?: boolean;
}) {
  const marker = join(venvPath, 'pyvenv.cfg');
  let venvExists = false;

  try {
    await fs.promises.access(marker);
    venvExists = true;
  } catch {
    // venv doesn't exist yet
  }

  // Invalidate if the cached venv was built with a different Python version.
  if (
    venvExists &&
    pythonVersion.major != null &&
    pythonVersion.minor != null
  ) {
    const expected = `${pythonVersion.major}.${pythonVersion.minor}`;
    const cachedVersion = await readVenvPythonVersion(marker);
    if (cachedVersion && cachedVersion !== expected) {
      if (!quiet) {
        console.log(
          `Cached venv Python ${cachedVersion} differs from requested ${expected}, recreating...`
        );
      }
      await fs.promises.rm(venvPath, { recursive: true, force: true });
      venvExists = false;
    }
  }

  if (venvExists) {
    debug(`Refreshing cached virtual environment at "${venvPath}"`);
  } else {
    await fs.promises.mkdir(venvPath, { recursive: true });
    if (!quiet) {
      console.log(`Creating virtual environment at "${venvPath}"...`);
    }
  }

  if (uvPath) {
    // --allow-existing allows uv to reuse a cached venv
    // --seed installs pip into the venv so custom install commands can use it
    const args = ['venv', venvPath, '--allow-existing', '--seed'];
    if (pythonVersion.major != null && pythonVersion.minor != null) {
      args.push('--python', `${pythonVersion.major}.${pythonVersion.minor}`);
    }