Add support for Python version requests in uv python list

Author: zanieb

crates/uv-cli/src/lib.rs

@@ -4557,6 +4557,11 @@ pub enum PythonCommand {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct PythonListArgs {
+    /// A Python request to filter by.
+    ///
+    /// See `uv help python` to view supported request formats.
+    pub request: Option<String>,
+
     /// List all Python versions, including old patch versions.
     ///
     /// By default, only the latest patch version is shown for each minor version.

crates/uv/src/commands/python/list.rs

@@ -52,6 +52,7 @@ struct PrintData {
 /// List available Python installations.
 #[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
 pub(crate) async fn list(
+    request: Option<String>,
     kinds: PythonListKinds,
     all_versions: bool,
     all_platforms: bool,
@@ -63,23 +64,31 @@ pub(crate) async fn list(
     cache: &Cache,
     printer: Printer,
 ) -> Result<ExitStatus> {
+    let request = request.as_deref().map(PythonRequest::parse);
+    let base_download_request = if python_preference == PythonPreference::OnlySystem {
+        None
+    } else {
+        // If the user request cannot be mapped to a download request, we won't show any downloads
+        PythonDownloadRequest::from_request(request.as_ref().unwrap_or(&PythonRequest::Any))
+    };
+
     let mut output = BTreeSet::new();
-    if python_preference != PythonPreference::OnlySystem {
+    if let Some(base_download_request) = base_download_request {
         let download_request = match kinds {
             PythonListKinds::Installed => None,
             PythonListKinds::Downloads => Some(if all_platforms {
-                PythonDownloadRequest::default()
+                base_download_request
             } else {
-                PythonDownloadRequest::from_env()?
+                base_download_request.fill()?
             }),
             PythonListKinds::Default => {
                 if python_downloads.is_automatic() {
                     Some(if all_platforms {
-                        PythonDownloadRequest::default()
+                        base_download_request
                     } else if all_arches {
-                        PythonDownloadRequest::from_env()?.with_any_arch()
+                        base_download_request.fill()?.with_any_arch()
                     } else {
-                        PythonDownloadRequest::from_env()?
+                        base_download_request.fill()?
                     })
                 } else {
                     // If fetching is not automatic, then don't show downloads as available by default
@@ -109,7 +118,7 @@ pub(crate) async fn list(
         match kinds {
             PythonListKinds::Installed | PythonListKinds::Default => {
                 Some(find_python_installations(
-                &PythonRequest::Any,
+                request.as_ref().unwrap_or(&PythonRequest::Any),
                 EnvironmentPreference::OnlySystem,
                 python_preference,
                 cache,

crates/uv/src/lib.rs

@@ -1244,6 +1244,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
             let cache = cache.init()?;
 
             commands::python_list(
+                args.request,
                 args.kinds,
                 args.all_versions,
                 args.all_platforms,

crates/uv/src/settings.rs

@@ -820,6 +820,7 @@ pub(crate) enum PythonListKinds {
 #[allow(clippy::struct_excessive_bools)]
 #[derive(Debug, Clone)]
 pub(crate) struct PythonListSettings {
+    pub(crate) request: Option<String>,
     pub(crate) kinds: PythonListKinds,
     pub(crate) all_platforms: bool,
     pub(crate) all_arches: bool,
@@ -833,6 +834,7 @@ impl PythonListSettings {
     #[allow(clippy::needless_pass_by_value)]
     pub(crate) fn resolve(args: PythonListArgs, _filesystem: Option<FilesystemOptions>) -> Self {
         let PythonListArgs {
+            request,
             all_versions,
             all_platforms,
             all_arches,
@@ -851,6 +853,7 @@ impl PythonListSettings {
         };
 
         Self {
+            request,
             kinds,
             all_platforms,
             all_arches,

crates/uv/tests/it/python_list.rs

@@ -30,103 +30,75 @@ fn python_list() {
 
     // Request Python 3.12
     uv_snapshot!(context.filters(), context.python_list().arg("3.12"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.12.[X]-[PLATFORM]    [PYTHON-3.12]
 
     ----- stderr -----
-    error: unexpected argument '3.12' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request Python 3.11
     uv_snapshot!(context.filters(), context.python_list().arg("3.11"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.11.[X]-[PLATFORM]    [PYTHON-3.11]
 
     ----- stderr -----
-    error: unexpected argument '3.11' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request CPython
     uv_snapshot!(context.filters(), context.python_list().arg("cpython"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.12.[X]-[PLATFORM]     [PYTHON-3.12]
+    cpython-3.11.[X]-[PLATFORM]    [PYTHON-3.11]
 
     ----- stderr -----
-    error: unexpected argument 'cpython' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request CPython 3.12
     uv_snapshot!(context.filters(), context.python_list().arg("[email protected]"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.12.[X]-[PLATFORM]    [PYTHON-3.12]
 
     ----- stderr -----
-    error: unexpected argument '[email protected]' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request CPython 3.12 via partial key syntax
     uv_snapshot!(context.filters(), context.python_list().arg("cpython-3.12"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.12.[X]-[PLATFORM]    [PYTHON-3.12]
 
     ----- stderr -----
-    error: unexpected argument 'cpython-3.12' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request CPython 3.12 for the current platform
     let os = Os::from_env();
     let arch = Arch::from_env();
 
     uv_snapshot!(context.filters(), context.python_list().arg(format!("cpython-3.12-{os}-{arch}")), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.12.[X]-[PLATFORM]    [PYTHON-3.12]
 
     ----- stderr -----
-    error: unexpected argument 'cpython-3.12-macos-aarch64' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request PyPy (which should be missing)
     uv_snapshot!(context.filters(), context.python_list().arg("pypy"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument 'pypy' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Swap the order of the Python versions
@@ -144,16 +116,12 @@ fn python_list() {
 
     // Request Python 3.11
     uv_snapshot!(context.filters(), context.python_list().arg("3.11"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
+    cpython-3.11.[X]-[PLATFORM]    [PYTHON-3.11]
 
     ----- stderr -----
-    error: unexpected argument '3.11' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 }
 
@@ -251,11 +219,7 @@ fn python_list_unsupported_version() {
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '3.6' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
+    error: Invalid version request: Python <3.7 is not supported but 3.6 was requested.
     ");
 
     // Request a low version with a patch
@@ -265,11 +229,7 @@ fn python_list_unsupported_version() {
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '3.6.9' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
+    error: Invalid version request: Python <3.7 is not supported but 3.6.9 was requested.
     ");
 
     // Request a really low version
@@ -279,11 +239,7 @@ fn python_list_unsupported_version() {
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '2.6' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
+    error: Invalid version request: Python <3.7 is not supported but 2.6 was requested.
     ");
 
     // Request a really low version with a patch
@@ -293,39 +249,25 @@ fn python_list_unsupported_version() {
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '2.6.8' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
+    error: Invalid version request: Python <3.7 is not supported but 2.6.8 was requested.
     ");
 
     // Request a future version
     uv_snapshot!(context.filters(), context.python_list().arg("4.2"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '4.2' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request a low version with a range
     uv_snapshot!(context.filters(), context.python_list().arg("<3.0"), @r"
-    success: false
-    exit_code: 2
+    success: true
+    exit_code: 0
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '<3.0' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
     ");
 
     // Request free-threaded Python on unsupported version
@@ -335,10 +277,6 @@ fn python_list_unsupported_version() {
     ----- stdout -----
 
     ----- stderr -----
-    error: unexpected argument '3.12t' found
-
-    Usage: uv python list [OPTIONS]
-
-    For more information, try '--help'.
+    error: Invalid version request: Python <3.13 does not support free-threading but 3.12t was requested.
     ");
 }