feat: Enhance Python environment handling with error reporting for broken environments

Author: karthiknadig

crates/pet-core/src/python_environment.rs

@@ -70,6 +70,11 @@ pub struct PythonEnvironment {
     // Some of the known symlinks for the environment.
     // E.g. in the case of Homebrew there are a number of symlinks that are created.
     pub symlinks: Option<Vec<PathBuf>>,
+    /// An error message if the environment is known to be in a bad state.
+    /// For example, when the Python executable is a broken symlink.
+    /// If None, no known issues have been detected (but this doesn't guarantee
+    /// the environment is fully functional - we don't spawn Python to verify).
+    pub error: Option<String>,
 }
 
 impl Ord for PythonEnvironment {
@@ -176,6 +181,9 @@ impl std::fmt::Display for PythonEnvironment {
                 }
             }
         }
+        if let Some(error) = &self.error {
+            writeln!(f, "   Error       : {error}").unwrap_or_default();
+        }
         Ok(())
     }
 }
@@ -194,6 +202,7 @@ pub struct PythonEnvironmentBuilder {
     project: Option<PathBuf>,
     arch: Option<Architecture>,
     symlinks: Option<Vec<PathBuf>>,
+    error: Option<String>,
 }
 
 impl PythonEnvironmentBuilder {
@@ -209,6 +218,7 @@ impl PythonEnvironmentBuilder {
             project: None,
             arch: None,
             symlinks: None,
+            error: None,
         }
     }
     pub fn from_environment(env: PythonEnvironment) -> Self {
@@ -223,6 +233,7 @@ impl PythonEnvironmentBuilder {
             project: env.project,
             arch: env.arch,
             symlinks: env.symlinks,
+            error: env.error,
         }
     }
 
@@ -285,6 +296,11 @@ impl PythonEnvironmentBuilder {
         self
     }
 
+    pub fn error(mut self, error: Option<String>) -> Self {
+        self.error = error;
+        self
+    }
+
     fn update_symlinks_and_exe(&mut self, symlinks: Option<Vec<PathBuf>>) {
         let mut all = self.symlinks.clone().unwrap_or_default();
         if let Some(ref exe) = self.executable {
@@ -340,6 +356,7 @@ impl PythonEnvironmentBuilder {
             project: self.project,
             arch: self.arch,
             symlinks,
+            error: self.error,
         }
     }
 }

crates/pet-python-utils/src/executable.rs

@@ -17,6 +17,31 @@ lazy_static! {
         Regex::new(r"python(\d+\.?)*$").expect("error parsing Unix executable regex");
 }
 
+/// Checks if a path is a broken symlink (symlink that points to a non-existent target).
+/// Returns true if the path is a symlink and its target does not exist.
+pub fn is_broken_symlink(path: &Path) -> bool {
+    // First check if it's a symlink using symlink_metadata (doesn't follow symlinks)
+    if let Ok(metadata) = fs::symlink_metadata(path) {
+        if metadata.file_type().is_symlink() {
+            // Now check if the target exists using regular metadata (follows symlinks)
+            // If this fails or returns false for exists(), then it's broken
+            return !path.exists();
+        }
+    }
+    false
+}
+
+/// Result of looking for an executable in an environment path.
+#[derive(Debug, Clone)]
+pub enum ExecutableResult {
+    /// A valid executable was found
+    Found(PathBuf),
+    /// An executable path exists but is broken (e.g., broken symlink)
+    Broken(PathBuf),
+    /// No executable was found
+    NotFound,
+}
+
 #[cfg(windows)]
 pub fn find_executable(env_path: &Path) -> Option<PathBuf> {
     [
@@ -43,6 +68,56 @@ pub fn find_executable(env_path: &Path) -> Option<PathBuf> {
     .find(|path| path.is_file())
 }
 
+/// Finds an executable in the environment path, including broken symlinks.
+/// This is useful for detecting virtual environments that have broken Python executables.
+#[cfg(windows)]
+pub fn find_executable_or_broken(env_path: &Path) -> ExecutableResult {
+    let candidates = [
+        env_path.join("Scripts").join("python.exe"),
+        env_path.join("Scripts").join("python3.exe"),
+        env_path.join("bin").join("python.exe"),
+        env_path.join("bin").join("python3.exe"),
+        env_path.join("python.exe"),
+        env_path.join("python3.exe"),
+    ];
+
+    // First try to find a valid executable
+    if let Some(path) = candidates.iter().find(|path| path.is_file()) {
+        return ExecutableResult::Found(path.clone());
+    }
+
+    // Then check for broken symlinks
+    if let Some(path) = candidates.iter().find(|path| is_broken_symlink(path)) {
+        return ExecutableResult::Broken(path.clone());
+    }
+
+    ExecutableResult::NotFound
+}
+
+/// Finds an executable in the environment path, including broken symlinks.
+/// This is useful for detecting virtual environments that have broken Python executables.
+#[cfg(unix)]
+pub fn find_executable_or_broken(env_path: &Path) -> ExecutableResult {
+    let candidates = [
+        env_path.join("bin").join("python"),
+        env_path.join("bin").join("python3"),
+        env_path.join("python"),
+        env_path.join("python3"),
+    ];
+
+    // First try to find a valid executable
+    if let Some(path) = candidates.iter().find(|path| path.is_file()) {
+        return ExecutableResult::Found(path.clone());
+    }
+
+    // Then check for broken symlinks
+    if let Some(path) = candidates.iter().find(|path| is_broken_symlink(path)) {
+        return ExecutableResult::Broken(path.clone());
+    }
+
+    ExecutableResult::NotFound
+}
+
 pub fn find_executables<T: AsRef<Path>>(env_path: T) -> Vec<PathBuf> {
     let mut env_path = env_path.as_ref().to_path_buf();
     // Never find exes in pyenv shims folder, they are not valid exes.

crates/pet-venv/src/lib.rs

@@ -10,7 +10,7 @@ use pet_core::{
     reporter::Reporter,
     Locator, LocatorKind,
 };
-use pet_python_utils::executable::find_executables;
+use pet_python_utils::executable::{find_executable_or_broken, find_executables, ExecutableResult};
 use pet_python_utils::version;
 
 fn is_venv_internal(env: &PythonEnv) -> Option<bool> {
@@ -26,6 +26,56 @@ pub fn is_venv(env: &PythonEnv) -> bool {
 pub fn is_venv_dir(path: &Path) -> bool {
     PyVenvCfg::find(path).is_some()
 }
+
+/// Tries to create a PythonEnvironment from a directory that might be a venv.
+/// This function can detect broken environments (e.g., with broken symlinks)
+/// and will return them with an error field set.
+pub fn try_environment_from_venv_dir(path: &Path) -> Option<PythonEnvironment> {
+    // Check if this is a venv directory
+    let cfg = PyVenvCfg::find(path)?;
+
+    let prefix = path.to_path_buf();
+    let version = version::from_creator_for_virtual_env(&prefix).or(Some(cfg.version.clone()));
+    let name = cfg.prompt;
+
+    match find_executable_or_broken(path) {
+        ExecutableResult::Found(executable) => {
+            let symlinks = find_executables(&prefix);
+            Some(
+                PythonEnvironmentBuilder::new(Some(PythonEnvironmentKind::Venv))
+                    .name(name)
+                    .executable(Some(executable))
+                    .version(version)
+                    .prefix(Some(prefix))
+                    .symlinks(Some(symlinks))
+                    .build(),
+            )
+        }
+        ExecutableResult::Broken(executable) => Some(
+            PythonEnvironmentBuilder::new(Some(PythonEnvironmentKind::Venv))
+                .name(name)
+                .executable(Some(executable))
+                .version(version)
+                .prefix(Some(prefix))
+                .error(Some(
+                    "Python executable is a broken symlink".to_string(),
+                ))
+                .build(),
+        ),
+        ExecutableResult::NotFound => {
+            // pyvenv.cfg exists but no Python executable found at all
+            Some(
+                PythonEnvironmentBuilder::new(Some(PythonEnvironmentKind::Venv))
+                    .name(name)
+                    .version(version)
+                    .prefix(Some(prefix))
+                    .error(Some("Python executable not found".to_string()))
+                    .build(),
+            )
+        }
+    }
+}
+
 pub struct Venv {}
 
 impl Venv {

crates/pet/src/find.rs

@@ -14,6 +14,7 @@ use pet_pixi::is_pixi_env;
 use pet_python_utils::executable::{
     find_executable, find_executables, should_search_for_environments_in_path,
 };
+use pet_venv::try_environment_from_venv_dir;
 use pet_virtualenv::is_virtualenv_dir;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
@@ -374,6 +375,13 @@ fn find_python_environments_in_paths_with_locators(
             if let Some(executable) = find_executable(path) {
                 vec![executable]
             } else {
+                // No valid executable found. Check if this is a broken venv.
+                // If so, report it with an error instead of silently skipping.
+                if let Some(broken_env) = try_environment_from_venv_dir(path) {
+                    if broken_env.error.is_some() {
+                        reporter.report_environment(&broken_env);
+                    }
+                }
                 vec![]
             }
         } else {

docs/JSONRPC.md

@@ -242,6 +242,13 @@ interface Environment {
    * Thats because there could be multiple conda installations on the system, hence we try not to make any assumptions.
    */
   manager?: Manager;
+  /**
+   * An error message if the environment is known to be in a bad state.
+   * For example: "Python executable is a broken symlink"
+   * If undefined, no known issues have been detected (but this doesn't guarantee
+   * the environment is fully functional - we don't spawn Python to verify).
+   */
+  error?: string;
 }
 
 interface Manager {