feat(python): rework python.uv_venv_auto setting

[halms]

Context

With the current python.uv_venv_auto behavior, there are two annoying things:

1. it always creates venvs if they not exist
   This is not needed for uv, since that usually creates/updates it's venvs transparently (when doing uv run or uv sync, ...).
   And it breaks mise prepare for uv since it creates the .venv folder but does not install any deps. So mise prepare thinks everything is up-to-date when it isn't. (the uv-native venv creation appears to not have been covered by fix(prepare): handle freshness check for auto-created venvs #7770)
2. it exports the mise python version to the env var UV_PYTHON, which forces uv to use that version.

Changes

• Upfront, some reworking of the schema of settings.toml, specifically the type and enum definitions.
  Added the BooleanOrString type needed for this and also made the enum definitions more flexible (e.g. with mixed types)
• Introducing new values for python.uv_venv_auto
  • "source" only sources existing venvs
  • "create|source" creates if not exists and sources venvs (but does not set UV_PYTHON anymore)
  • false does nothing – like now
  • true (legacy, will be deprecated in 6 months) – like now, also sets UV_PYTHON
• Unified the code creating/sourcing venvs between settings.python.uv_venv_auto and env._.python.venv, which should now also mark these as stale at creation.

I think with this changes, python.uv_venv_auto becomes much more useful.

[gemini-code-assist]

Summary of Changes

Hello @halms, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines how mise integrates with uv virtual environments, addressing issues where the previous automatic venv creation was incomplete. It introduces a dedicated setting for sourcing existing uv venvs and clarifies that venv creation should be managed through mise prepare or uv sync. This change improves the robustness and predictability of Python environment management within mise when using uv.

Highlights

• New Setting for UV Venv Sourcing: Introduced python.uv_venv_auto_source to automatically source existing uv virtual environments without creating them.
• Deprecation of Old Setting: The python.uv_venv_auto setting has been deprecated, and a warning will be issued when it is used.
• Clarified Venv Creation vs. Sourcing: Both the new and deprecated settings now only source existing virtual environments. Automatic creation of uv venvs is now explicitly handled by enabling [prepare.uv] and running mise prep.
• Code Refactoring: The internal logic for uv virtual environment handling has been refactored to remove automatic creation, add checks for existing venvs, and provide guidance for creation via mise prepare.
• Documentation and Test Updates: Documentation, schema, and end-to-end tests have been updated to reflect the new setting and behavior.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively introduces the python.uv_venv_auto_source setting to only source existing uv virtual environments, and correctly deprecates the old python.uv_venv_auto setting. The logic is sound, and the changes across documentation, tests, and schema are consistent. The move to guide users towards mise prep for venv creation is a good one. I have one suggestion to enhance the warning messages for a better user experience when a venv is missing.

[Copilot]

Pull request overview

Adds a new setting to auto-source existing uv virtual environments (without creating them) and deprecates the previous auto-create behavior, aligning with the new prepare workflow.

Changes:

• Add python.uv_venv_auto_source and deprecate python.uv_venv_auto.
• Update uv venv integration to only load an existing .venv (and emit guidance when missing).
• Update schema/docs and adjust e2e tests to cover the new behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/uv.rs	Switches from “create or load” to “load only”, adds deprecation + missing-venv guidance, and checks for [prepare.uv].
settings.toml	Marks python.uv_venv_auto deprecated and introduces python.uv_venv_auto_source.
schema/mise.json	Updates JSON schema for deprecation and new setting.
e2e/core/test_python_uv_venv_x_tiny	Uses the new setting and ensures a .venv exists for the test via uv venv.
e2e/core/test_python_uv_venv	Updates commented example to the new setting name.
e2e-win/uv.Tests.ps1	Switches Windows e2e to python.uv_venv_auto_source.
docs/mise-cookbook/python.md	Updates docs to recommend the new setting and explain prepare.uv + mise prep flow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[halms]

/gemini review

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request effectively reworks the python.uv_venv_auto setting, introducing more granular control over virtual environment handling with uv. The changes are well-structured, with significant refactoring to improve modularity, such as extracting venv creation logic. The updates to documentation, tests, and schemas are comprehensive and align with the new functionality.

I've identified a couple of areas for improvement. One is a potential discrepancy between the implemented behavior and the description for the legacy true value of python.uv_venv_auto. Another is a suggestion to further refactor a large function to improve maintainability. Overall, this is a great enhancement.

[halms]

/gemini review

[jdx]

if this ends up being too much of a pain we could have a replacement env var maybe. That said, I've needed this before so it will come in handy in the future I'm sure.

[halms]

It took a bit of back and forth, but I think I got it now.

Also tried allowing the type description in settings.toml already being an array, like

type = ["Boolean", "String"]

But that led to more complications, so I went with the predefined type instead.

[halms]

/gemini review

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request is a well-executed feature enhancement that reworks the python.uv_venv_auto setting for better flexibility and usability with uv. The introduction of new string-based options ("source", "create|source") and the deprecation of the legacy boolean true value are clear improvements. The refactoring of venv creation logic into a shared, centralized function in src/config/env_directive/venv.rs significantly improves code structure and maintainability. The changes are consistently applied across the codebase, including configuration, schemas, documentation, and tests. I've noted a couple of minor maintainability improvements in the build script to make it more robust for future changes. Overall, this is an excellent contribution.

[jdx]

bugbot run

[jdx]

I think you need to handle "true" so MISE_PYTHON_UV_VENV_AUTO=true works correctly too

[halms]

I think you need to handle "true" so MISE_PYTHON_UV_VENV_AUTO=true works correctly too
Aaah, yes was only thinking about the toml file (which is typed) and not the env vars.

Should be fixed now.

I've copied what confique does (which is used for the purely boolean env vars) and treat "true" | "yes" | "1" as true and "false" | "no" | "0" as false (both case-insensitive).