Add support for explicit variants and `--all-variants` flag with `uv python list` by shaanmajid · Pull Request #16002 · astral-sh/uv

shaanmajid · 2025-09-23T14:46:02Z

Adds --all-variants flag to uv python list to show debug Python builds that are normally hidden.

Functional Requirements Met:

Default behavior: Only default variants shown (hides debug/freethreaded)
--all-variants flag: Shows all variants including debug, freethreaded, freethreaded+debug
Explicit requests: 3.13+debug works without needing the flag
Flag compatibility: Works with --all-versions, --only-downloads, etc.

Key Behavior:

# Default - only shows default variant
uv python list 3.13  # → cpython-3.13.7-platform

# Show all variants for specific version  
uv python list 3.13 --all-variants  # → default, debug, freethreaded, freethreaded+debug

# Explicit variant request (works without flag)
uv python list 3.13+debug  # → cpython-3.13.7+debug-platform

Fixes #15983

zanieb · 2025-09-23T14:55:14Z

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

+            // When --all-variants is used with a specific request, use Any to get all variants
+            // The filtering logic will ensure only matching downloads are shown
+            PythonDownloadRequest::from_request(&PythonRequest::Any)


This looks wrong — we shouldn't drop the original request from the user. Though I see you filter using it later, then we'll need to duplicate a bunch of logic that happens in discovery. We'll also do a bunch of work querying interpreters that do not match the request. I'm not quite sure how best to achieve what you're trying to do here though.

yeah that was pretty troll mb :/

Reworked the implementation based on your feedback

zanieb · 2025-09-23T14:57:00Z

I think this issue may be harder than it looks. Maybe it'd be a good place to start just adjusting the downloads we show based on an --all-variants flag?

zanieb · 2025-09-23T15:09:24Z

Oh it looks like you are only changing the download listing logic here, so perhaps disregard that part (though we'll need to figure out how to show all variants we discover too at some point)

zanieb · 2025-09-23T15:11:17Z

Maybe you need to add something like

uv/crates/uv-python/src/downloads.rs

Lines 163 to 165 in dea1700

    
               /// Whether to allow pre-releases or not. If not set, defaults to true if [`Self::version`] is 
        
               /// not None, and false otherwise. 
        
               pub(crate) prereleases: Option<bool>,

for variants?

shaanmajid · 2025-09-24T21:36:58Z

Testing was a bit annoying ; I didn't realize debug variants were not supported on Windows at first. Last minute split up a lot of test-cases based off target, but lmk if you think it's worth organizing this better

shaanmajid · 2025-09-29T17:25:07Z

Hey @zanieb, just wanted to check whether there’s anything else you’d like me to do on this PR. Happy to rebase or tweak if needed :)

zanieb · 2025-10-07T18:59:03Z

crates/uv-python/src/discovery.rs

+        match self {
+            Self::Version(version) => version.variant(),
+            Self::ImplementationVersion(_, version) => version.variant(),
+            _ => None,


We generally prefer to list all the variants so if we add a new one we're forced to revisit this and see if it needs to be updated.

Updated to use explicit listing.

zanieb · 2025-10-07T18:59:22Z

crates/uv-python/src/downloads.rs

    /// not None, and false otherwise.
    pub(crate) prereleases: Option<bool>,
+
+    /// Whether to allow all variants, or to filter by the requested variant.


What does "to filter by the requested variant" mean here?

You mean like, one in the VersionRequest?

Yeah, that was the intent. Sorry, the conflicting terminology / overload between Python's "variants" and Rust variants is a bit unfortunate here haha. Updated the comment a bit to further elaborate.

zanieb · 2025-10-07T19:01:09Z

crates/uv-python/src/downloads.rs

-                if variant != key.variant {
-                    return false;
+            // Only filter by variant if `all_variants` is not requested
+            if self.all_variants.is_none() {


I'm confused that this is an Option if we're not using the inner boolean value?

Fixed to use an explicit boolean

zanieb · 2025-10-07T19:01:57Z

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

+    #[diagnostic(
+        code(uv::python::list::conflicting_arguments),
+        help(
+            "Use `--all-variants` to show all variants for a Python version, or specify an exact variant like `3.10+debug`, but not both."
+        )
+    )]


I don't think we should use this — we're moving away from miette. You can see other hint formatting to see how we're handling this for now.

Switched to use standard hint formatting

zanieb · 2025-10-07T19:05:11Z

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

    } 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))
+            .map(|request| request.with_all_variants(all_variants))


Leaving a note for https://github.com/astral-sh/uv/pull/16002/files#r2411619048

zanieb · 2025-10-07T19:05:30Z

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

+                all_variants
+                    || request
+                        .as_ref()
+                        .and_then(uv_python::PythonRequest::variant)
+                        .unwrap_or(uv_python::PythonVariant::Default)
+                        == *download.key().variant()


I'm confused that we're changing the filtering here and at https://github.com/astral-sh/uv/pull/16002/files#r2411618419

Why do we need both?

Updated and consolidated.

shaanmajid · 2025-10-08T23:12:51Z

@zanieb Wanted to quickly double-check about pre-existing behavior with the display of freethreaded variants.

Currently:

uv python list (i.e. no explicit request) shows both default and free-threaded variants (i.e. all non-debug variants)
uv python list 3.13 (i.e. explicit request) shows only the default variant

This seems intentional and aligns with treating freethreaded as non-experimental in Python 3.14+ and uv 0.9+ (per #16142). Just wanted to confirm this is the intended behavior, since this PR makes the variant filtering more explicit.

shaanmajid · 2025-11-03T22:49:41Z

Hey @zanieb, just wanted to check back on this. Is there anything else you would like changed? Also happy to just close the PR if you don't think y'all have time for it.

Python list now supports explicit variant requests (e.g. `3.10+debug`, `3.13t`) to show specific debug or free-threaded builds. A new `--all-variants` flag lists every available variant for a version (e.g. `uv python list 3.10 --all-variants`). By default, only standard builds are shown, matching previous behavior. The `--all-variants` flag can't be combined with explicit variant requests (e.g. `uv python list 3.10+debug --all-variants`) to avoid ambiguity. Fixes astral-sh#15983

Adds comprehensive test coverage for variant functionality in python list.

Add example usage for --all-variants flag showing how to list debug and freethreaded Python builds alongside other uv python list options.

- Add missing `all_variants: false` argument to `TryFrom<&PythonInstallationKey>` impl that was missed during rebase - Update test snapshots for cpython 3.10.18 → 3.10.19 version bump

Use Python 3.9 (EOL Oct 2025, final version 3.9.25) for variant tests to avoid snapshot churn from new patch releases. Also use cpython@ prefix to filter out PyPy/GraalPy which have different version availability per platform. Remove overly verbose --all-versions combined test that added complexity without testing new behavior.

zanieb reviewed Sep 23, 2025

View reviewed changes

shaanmajid force-pushed the add-all-variants-flag branch 2 times, most recently from 72a0645 to 2921685 Compare September 23, 2025 15:03

shaanmajid force-pushed the add-all-variants-flag branch 5 times, most recently from 6cc18a0 to 70b7741 Compare September 24, 2025 21:25

shaanmajid requested a review from zanieb September 24, 2025 21:35

shaanmajid force-pushed the add-all-variants-flag branch from 70b7741 to 740f872 Compare September 24, 2025 21:41

zanieb reviewed Oct 7, 2025

View reviewed changes

shaanmajid force-pushed the add-all-variants-flag branch 5 times, most recently from b602f77 to aa9842b Compare October 8, 2025 22:46

shaanmajid changed the title ~~feat: add --all-variants flag to uv python list~~ Add support for explicit variants and --all-variants flag with uv python list Oct 8, 2025

shaanmajid requested a review from zanieb October 8, 2025 23:13

shaanmajid force-pushed the add-all-variants-flag branch 2 times, most recently from 7d9cd90 to 999ca39 Compare December 16, 2025 00:33

shaanmajid added 5 commits December 15, 2025 19:40

test: add tests for --all-variants and variant requests

b33b67d

Adds comprehensive test coverage for variant functionality in python list.

docs: document --all-variants flag in python-versions guide

833fcd4

Add example usage for --all-variants flag showing how to list debug and freethreaded Python builds alongside other uv python list options.

fix: add missing all_variants parameter and update snapshots

081275d

- Add missing `all_variants: false` argument to `TryFrom<&PythonInstallationKey>` impl that was missed during rebase - Update test snapshots for cpython 3.10.18 → 3.10.19 version bump

shaanmajid force-pushed the add-all-variants-flag branch from c845da5 to 67ce198 Compare December 16, 2025 01:41

Conversation

shaanmajid commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Functional Requirements Met:

Key Behavior:

Uh oh!

zanieb Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaanmajid Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb commented Sep 23, 2025

Uh oh!

zanieb commented Sep 23, 2025

Uh oh!

zanieb commented Sep 23, 2025

Uh oh!

shaanmajid commented Sep 24, 2025

Uh oh!

shaanmajid commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaanmajid Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaanmajid Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaanmajid commented Oct 8, 2025

Uh oh!

shaanmajid commented Nov 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shaanmajid commented Sep 23, 2025 •

edited

Loading

zanieb Sep 23, 2025 •

edited

Loading

shaanmajid Sep 24, 2025 •

edited

Loading

shaanmajid Oct 8, 2025 •

edited

Loading

zanieb Oct 7, 2025 •

edited

Loading

shaanmajid Oct 8, 2025 •

edited

Loading