fix: discover free-threaded Python executables (Fixes #569)

The executable-name patterns accepted `python3.13` but not the free-threaded
`python3.13t`, so a distro build such as Fedora's /usr/bin/python3.13t
(python3.13-freethreading) was never discovered. Accept a `t` suffix after
the version.

CPython's `make install` of a free-threaded build hard-links `python3.13` to
`python3.13t`. Hard links resolve to different paths, so treat files with the
same device and inode as the same interpreter (new `pet_fs::path::is_same_file`)
in the Linux global locator and in `find_symlinks`; otherwise those builds
would now be reported twice.

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

Author: karthiknadig

crates/pet-fs/src/path.rs

@@ -413,6 +413,31 @@ pub fn resolve_symlink<T: AsRef<Path>>(exe: &T) -> Option<PathBuf> {
     }
 }
 
+/// Returns `true` when both paths refer to the same file, following symlinks.
+///
+/// On Unix this compares the device and inode, so hard links to the same file match even though
+/// their paths and resolved paths differ. For example, CPython's `make install` of a free-threaded
+/// build hard-links `python3.13` to `python3.13t`. Elsewhere the canonical paths are compared.
+///
+/// Returns `false` when either path cannot be read.
+pub fn is_same_file<A: AsRef<Path>, B: AsRef<Path>>(first: A, second: B) -> bool {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt;
+        match (std::fs::metadata(first), std::fs::metadata(second)) {
+            (Ok(first), Ok(second)) => first.dev() == second.dev() && first.ino() == second.ino(),
+            _ => false,
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        match (std::fs::canonicalize(first), std::fs::canonicalize(second)) {
+            (Ok(first), Ok(second)) => first == second,
+            _ => false,
+        }
+    }
+}
+
 /// Expands `~` (home directory) and environment variables in a path.
 ///
 /// This function handles:
@@ -991,4 +1016,30 @@ mod tests {
         let _ = std::fs::remove_file(&symlink_path);
         let _ = std::fs::remove_file(&target_file);
     }
+
+    // ==================== is_same_file tests ====================
+
+    #[test]
+    fn test_is_same_file_matches_hard_links_and_symlinks() {
+        let dir = tempfile::tempdir().unwrap();
+        let original = dir.path().join("python3.13t");
+        let hard_link = dir.path().join("python3.13");
+        let other = dir.path().join("python3.12");
+        std::fs::write(&original, "python").unwrap();
+        std::fs::write(&other, "python").unwrap();
+        std::fs::hard_link(&original, &hard_link).unwrap();
+
+        assert!(is_same_file(&original, &original));
+        #[cfg(unix)]
+        assert!(is_same_file(&original, &hard_link));
+        assert!(!is_same_file(&original, &other));
+        assert!(!is_same_file(&original, dir.path().join("missing")));
+
+        #[cfg(unix)]
+        {
+            let symlink = dir.path().join("python3");
+            std::os::unix::fs::symlink(&hard_link, &symlink).unwrap();
+            assert!(is_same_file(&symlink, &original));
+        }
+    }
 }

crates/pet-linux-global-python/src/lib.rs

@@ -17,7 +17,7 @@ use pet_core::{
     reporter::Reporter,
     Locator, LocatorKind, RefreshStatePersistence,
 };
-use pet_fs::path::resolve_symlink;
+use pet_fs::path::{is_same_file, resolve_symlink};
 use pet_python_utils::{env::ResolvedPythonEnv, executable::find_executables};
 use pet_virtualenv::is_virtualenv;
 
@@ -244,6 +244,13 @@ fn get_python_in_bin(env: &PythonEnv, is_64bit: bool) -> Option<PythonEnvironmen
                 symlinks.push(possible_symlink.to_owned());
             }
         }
+
+        // A hard link to the executable in the same folder is the same interpreter under another
+        // name. CPython's `make install` of a free-threaded build hard-links `python3.13` to
+        // `python3.13t`.
+        if !possible_symlink.is_symlink() && is_same_file(possible_symlink, &executable) {
+            symlinks.push(possible_symlink.to_owned());
+        }
     }
     symlinks.sort();
     symlinks.dedup();
@@ -389,6 +396,44 @@ mod tests {
         assert!(!symlinks.contains(&real_executable));
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn get_python_in_bin_collects_hard_linked_free_threaded_executable() {
+        // CPython's `make install` of a free-threaded build hard-links python3.13 to python3.13t.
+        let dir = tempdir().unwrap();
+        let bin = dir.path().join("bin");
+        fs::create_dir(&bin).unwrap();
+        let free_threaded = bin.join("python3.13t");
+        let executable = bin.join("python3.13");
+        create_executable(&free_threaded);
+        fs::hard_link(&free_threaded, &executable).unwrap();
+        let env = create_env(executable.clone(), dir.path().to_path_buf());
+
+        let symlinks = get_python_in_bin(&env, true).unwrap().symlinks.unwrap();
+
+        assert!(symlinks.contains(&executable));
+        assert!(symlinks.contains(&free_threaded));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn get_python_in_bin_keeps_separate_free_threaded_binary_separate() {
+        // Distributions such as Fedora ship the free-threaded build as a separate binary.
+        let dir = tempdir().unwrap();
+        let bin = dir.path().join("bin");
+        fs::create_dir(&bin).unwrap();
+        let free_threaded = bin.join("python3.13t");
+        let executable = bin.join("python3.13");
+        create_executable(&free_threaded);
+        create_executable(&executable);
+        let env = create_env(executable.clone(), dir.path().to_path_buf());
+
+        let symlinks = get_python_in_bin(&env, true).unwrap().symlinks.unwrap();
+
+        assert!(symlinks.contains(&executable));
+        assert!(!symlinks.contains(&free_threaded));
+    }
+
     #[test]
     fn try_from_returns_none_without_version_before_cache_lookup() {
         let locator = LinuxGlobalPython::new();

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

@@ -11,10 +11,11 @@ use std::{
 };
 
 lazy_static! {
-    static ref WINDOWS_EXE: Regex =
-        Regex::new(r"python(\d+\.?)*\.exe$").expect("error parsing Windows executable regex");
+    // `python`, `python3`, `python3.13`, and free-threaded builds such as `python3.13t`.
+    static ref WINDOWS_EXE: Regex = Regex::new(r"python(\d+(\.\d+)*t?)?\.exe$")
+        .expect("error parsing Windows executable regex");
     static ref UNIX_EXE: Regex =
-        Regex::new(r"python(\d+\.?)*$").expect("error parsing Unix executable regex");
+        Regex::new(r"python(\d+(\.\d+)*t?)?$").expect("error parsing Unix executable regex");
 }
 
 /// Checks if a path is a broken symlink (symlink that points to a non-existent target).
@@ -301,6 +302,15 @@ mod tests {
         assert!(is_python_executable_name(
             PathBuf::from("python4.10").as_path()
         ));
+        // Free-threaded builds.
+        #[cfg(unix)]
+        assert!(is_python_executable_name(
+            PathBuf::from("python3.13t").as_path()
+        ));
+        #[cfg(unix)]
+        assert!(is_python_executable_name(
+            PathBuf::from("python3t").as_path()
+        ));
 
         #[cfg(windows)]
         assert!(is_python_executable_name(
@@ -322,6 +332,11 @@ mod tests {
         assert!(is_python_executable_name(
             PathBuf::from("python4.10.exe").as_path()
         ));
+        // Free-threaded builds.
+        #[cfg(windows)]
+        assert!(is_python_executable_name(
+            PathBuf::from("python3.14t.exe").as_path()
+        ));
     }
     #[test]
     fn is_not_python_executable_test() {
@@ -333,6 +348,18 @@ mod tests {
         assert!(!is_python_executable_name(
             PathBuf::from("pythonw3").as_path()
         ));
+        #[cfg(unix)]
+        assert!(!is_python_executable_name(
+            PathBuf::from("pythont").as_path()
+        ));
+        #[cfg(unix)]
+        assert!(!is_python_executable_name(
+            PathBuf::from("python3.13t-config").as_path()
+        ));
+        #[cfg(unix)]
+        assert!(!is_python_executable_name(
+            PathBuf::from("python3.13-config").as_path()
+        ));
 
         #[cfg(windows)]
         assert!(!is_python_executable_name(
@@ -343,6 +370,10 @@ mod tests {
             PathBuf::from("pythonw3.exe").as_path()
         ));
         #[cfg(windows)]
+        assert!(!is_python_executable_name(
+            PathBuf::from("pythonw3.14t.exe").as_path()
+        ));
+        #[cfg(windows)]
         assert!(!is_python_executable_name(
             PathBuf::from("python.exe.__target__").as_path()
         ));

crates/pet/src/locators.rs

@@ -232,7 +232,7 @@ fn find_symlinks(executable: &PathBuf) -> Option<Vec<PathBuf>> {
     // We use canonicalize to get the real path of the symlink.
     // Only used in this case, see notes for resolve_symlink.
 
-    use pet_fs::path::resolve_symlink;
+    use pet_fs::path::{is_same_file, resolve_symlink};
     use pet_python_utils::executable::find_executables;
     use std::fs;
 
@@ -248,7 +248,9 @@ fn find_symlinks(executable: &PathBuf) -> Option<Vec<PathBuf>> {
     let mut symlinks = vec![];
     for exe in find_executables(bin) {
         let symlink = resolve_symlink(&exe).or(fs::canonicalize(&exe).ok());
-        if symlink == real_exe {
+        // Hard links resolve to different paths but are the same file, for example python3.13 and
+        // the free-threaded python3.13t from CPython's `make install`.
+        if symlink == real_exe || is_same_file(&exe, executable) {
             symlinks.push(exe);
         }
     }
@@ -291,4 +293,29 @@ mod tests {
         assert!(result.is_none());
         assert_eq!(calls.get(), 1);
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn find_symlinks_includes_hard_linked_free_threaded_executable() {
+        // CPython's `make install` of a free-threaded build hard-links python3.13 to python3.13t
+        // and symlinks python3 to python3.13.
+        let dir = tempfile::tempdir().unwrap();
+        let bin = dir.path().join("bin");
+        std::fs::create_dir(&bin).unwrap();
+        let free_threaded = bin.join("python3.13t");
+        let versioned = bin.join("python3.13");
+        let python3 = bin.join("python3");
+        let other = bin.join("python3.12");
+        std::fs::write(&free_threaded, "").unwrap();
+        std::fs::write(&other, "").unwrap();
+        std::fs::hard_link(&free_threaded, &versioned).unwrap();
+        std::os::unix::fs::symlink("python3.13", &python3).unwrap();
+
+        let symlinks = find_symlinks(&python3).unwrap();
+
+        assert!(symlinks.contains(&python3));
+        assert!(symlinks.contains(&versioned));
+        assert!(symlinks.contains(&free_threaded));
+        assert!(!symlinks.contains(&other));
+    }
 }