fix(python): align python_binary schema with argument support (#7415)

.github/config-schema.json

@@ -5668,7 +5668,7 @@
       "type": "object",
       "properties": {
         "pixi_binary": {
-          "$ref": "#/$defs/Either2",
+          "$ref": "#/$defs/VecOr_string",
           "default": [
             "pixi"
           ]
@@ -5724,7 +5724,7 @@
       },
       "additionalProperties": false
     },
-    "Either2": {
+    "VecOr_string": {
       "anyOf": [
         {
           "type": "string"
@@ -5832,7 +5832,7 @@
           "default": "pyenv "
         },
         "python_binary": {
-          "$ref": "#/$defs/Either2",
+          "$ref": "#/$defs/VecOr_VecOr_string",
           "default": [
             [
               "python"
@@ -5916,6 +5916,19 @@
       },
       "additionalProperties": false
     },
+    "VecOr_VecOr_string": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/VecOr_string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/VecOr_string"
+          }
+        }
+      ]
+    },
     "QuartoConfig": {
       "type": "object",
       "properties": {
@@ -6449,7 +6462,7 @@
           "default": "S "
         },
         "compiler": {
-          "$ref": "#/$defs/Either2",
+          "$ref": "#/$defs/VecOr_string",
           "default": [
             "solc"
           ]
@@ -7146,7 +7159,7 @@
           "default": ""
         },
         "when": {
-          "$ref": "#/$defs/Either3",
+          "$ref": "#/$defs/Either2",
           "default": false
         },
         "require_repo": {
@@ -7154,7 +7167,7 @@
           "default": false
         },
         "shell": {
-          "$ref": "#/$defs/Either2",
+          "$ref": "#/$defs/VecOr_string",
           "default": []
         },
         "description": {
@@ -7213,7 +7226,7 @@
       },
       "additionalProperties": false
     },
-    "Either3": {
+    "Either2": {
       "anyOf": [
         {
           "type": "boolean"

docs/config/README.md

@@ -4031,10 +4031,16 @@ By default, the module will be shown if any of the following conditions are met:
 | `disabled`           | `false`                                                                                                      | Disables the `python` module.                                                         |
 
 > [!TIP]
-> The `python_binary` variable accepts either a string or a list of strings.
+> The `python_binary` variable accepts either:
-> Starship will try executing each binary until it gets a result. Note you can
+>
-> only change the binary that Starship executes to get the version of Python not
+> - a string (e.g. `'python3'`),
-> the arguments that are used.
+> - a list of strings (e.g. `['python', 'python3']`)
+> - a list of lists of strings, representing commands with optional arguments (e.g.
+>   `[['mise', 'exec', '--', 'python'], ['python3']]`)
+>
+> Starship will try executing each configured command until it gets a result.
+> Note you can only change the binary that Starship executes to get the version
+> of Python not the arguments that are used.
 >
 > The default values and order for `python_binary` was chosen to first identify
 > the Python version in a virtualenv/conda environments (which currently still
@@ -4076,6 +4082,22 @@ python_binary = 'python3'
 ```toml
 # ~/.config/starship.toml
 
+[python]
+# Use `mise` to get the version.
+python_binary = [['mise', 'exec', '--', 'python']]
+```
+
+```toml
+# ~/.config/starship.toml
+
+[python]
+# Potentially dangerous: `uv` can run any binary at `.venv/bin/python` without interaction
+python_binary = [['uv', 'run', '--no-python-downloads', '--no-project', 'python']]
+```
+
+```toml
+# ~/.config/starship.toml
+
 [python]
 # Don't trigger for files with the py extension
 detect_extensions = []

src/config.rs

@@ -103,12 +103,12 @@ where
     T: schemars::JsonSchema + Sized,
 {
     fn schema_name() -> Cow<'static, str> {
-        Either::<T, Vec<T>>::schema_name()
+        // `Either::<T, Vec<T>>::schema_name()` is not unique per `T`; nested `VecOr`s must not share a `$defs` entry.
+        Cow::Owned(format!("VecOr_{}", T::schema_name()))
     }
 
     fn schema_id() -> Cow<'static, str> {
-        let mod_path = module_path!();
+        Cow::Owned(format!("{}::VecOr<{}>", module_path!(), T::schema_id()))
-        Cow::Owned(format!("{mod_path}::{}", Self::schema_name()))
     }
 
     fn json_schema(generator: &mut schemars::generate::SchemaGenerator) -> schemars::Schema {
@@ -1059,4 +1059,20 @@ mod tests {
             "if the platform doesn't have utils::home_dir(), it should return None"
         );
     }
+
+    /// Guard against schemars `$defs` collisions by requiring distinct IDs for nested `VecOr` types.
+    #[cfg(feature = "config-schema")]
+    #[test]
+    fn vec_or_schema_ids_distinguish_nesting() {
+        use schemars::JsonSchema;
+
+        assert_ne!(
+            VecOr::<VecOr<&str>>::schema_id(),
+            VecOr::<&str>::schema_id(),
+        );
+        assert_ne!(
+            VecOr::<VecOr<&str>>::schema_name(),
+            VecOr::<&str>::schema_name(),
+        );
+    }
 }