Improve interactions between .python-version files and project requires-python

Author: zanieb

crates/uv/src/commands/project/mod.rs

@@ -14,7 +14,7 @@ use uv_client::{BaseClientBuilder, Connectivity, FlatIndexClient, RegistryClient
 use uv_configuration::{Concurrency, ExtrasSpecification, Reinstall, Upgrade};
 use uv_dispatch::BuildDispatch;
 use uv_distribution::DistributionDatabase;
-use uv_fs::Simplified;
+use uv_fs::{Simplified, CWD};
 use uv_installer::{SatisfiesResult, SitePackages};
 use uv_normalize::PackageName;
 use uv_python::{
@@ -27,7 +27,7 @@ use uv_resolver::{
 };
 use uv_types::{BuildIsolation, EmptyInstalledPackages, HashStrategy};
 use uv_warnings::{warn_user, warn_user_once};
-use uv_workspace::Workspace;
+use uv_workspace::{DiscoveryOptions, VirtualProject, Workspace, WorkspaceError};
 
 use crate::commands::pip::loggers::{InstallLogger, ResolveLogger};
 use crate::commands::pip::operations::{Changelog, Modifications};
@@ -36,6 +36,8 @@ use crate::commands::{pip, SharedState};
 use crate::printer::Printer;
 use crate::settings::{InstallerSettingsRef, ResolverInstallerSettings, ResolverSettingsRef};
 
+use super::python::pin::pep440_version_from_request;
+
 pub(crate) mod add;
 pub(crate) mod environment;
 pub(crate) mod init;
@@ -1048,3 +1050,114 @@ fn warn_on_requirements_txt_setting(
         warn_user_once!("Ignoring `--no-binary` setting from requirements file. Instead, use the `--no-build` command-line argument, or set `no-build` in a `uv.toml` or `pyproject.toml` file.");
     }
 }
+
+/// Determine the [`PythonRequest`] to use in a command, if any.
+pub(crate) async fn find_python_request(
+    user_request: Option<String>,
+    no_project: bool,
+    no_config: bool,
+) -> Result<Option<PythonRequest>, ProjectError> {
+    // (1) Explicit request from user
+    let mut request = user_request.map(|request| PythonRequest::parse(&request));
+
+    let (project, requires_python) = if no_project {
+        (None, None)
+    } else {
+        let project = match VirtualProject::discover(&CWD, &DiscoveryOptions::default()).await {
+            Ok(project) => Some(project),
+            Err(WorkspaceError::MissingProject(_)) => None,
+            Err(WorkspaceError::MissingPyprojectToml) => None,
+            Err(WorkspaceError::NonWorkspace(_)) => None,
+            Err(err) => {
+                warn_user_once!("{err}");
+                None
+            }
+        };
+
+        let requires_python = if let Some(project) = project.as_ref() {
+            find_requires_python(project.workspace())?
+        } else {
+            None
+        };
+
+        (project, requires_python)
+    };
+
+    // (2) Request from a `.python-version` file
+    if request.is_none() {
+        let version_file = PythonVersionFile::discover(&*CWD, no_config, false).await?;
+
+        if should_use_version_file(
+            version_file.as_ref(),
+            requires_python.as_ref(),
+            project.as_ref(),
+        ) {
+            request = version_file.and_then(PythonVersionFile::into_version);
+        }
+    }
+
+    // (3) The `requires-python` defined in `pyproject.toml`
+    if request.is_none() && !no_project {
+        request = requires_python
+            .as_ref()
+            .map(RequiresPython::specifiers)
+            .map(|specifiers| PythonRequest::Version(VersionRequest::Range(specifiers.clone())));
+    }
+
+    Ok(request)
+}
+
+/// Determine if a version file should be used, w.r.t, a Python requirement.
+///
+/// If the version file is incompatible,
+fn should_use_version_file(
+    version_file: Option<&PythonVersionFile>,
+    requires_python: Option<&RequiresPython>,
+    project: Option<&VirtualProject>,
+) -> bool {
+    // If there's no file, it's moot
+    let Some(version_file) = version_file else {
+        return false;
+    };
+
+    // If there's no request in the file, there's nothing to do
+    let Some(request) = version_file.version() else {
+        return false;
+    };
+
+    // If there's no project Python requirement, it's compatible
+    let Some(requires_python) = &requires_python else {
+        return true;
+    };
+
+    // If the request can't be parsed as a version, we can't check compatibility
+    let Some(version) = pep440_version_from_request(request) else {
+        return true;
+    };
+
+    // If it's compatible with the requirement, we can definitely use it
+    if requires_python.specifiers().contains(&version) {
+        return true;
+    };
+
+    let path = version_file.path();
+
+    // If there's no known project, we're not sure where the Python requirement came from and it's
+    // not safe to use the pin
+    let Some(project) = project else {
+        debug!("Ignoring pinned Python version ({version}) at `{}`, it does not meet the Python requirement of `{requires_python}`.", path.user_display().cyan());
+        return false;
+    };
+
+    // Otherwise, whether or not we should use it depends if it's declared inside or outside of the
+    // project.
+    if path.starts_with(project.root()) {
+        // It's the pin is declared _inside_ the project, just warn... but use the version
+        warn_user_once!("The pinned Python version ({version}) in `{}` does not meet the project's Python requirement of `{requires_python}`.", path.user_display().cyan());
+        true
+    } else {
+        // Otherwise, we can just ignore the pin — it's outside the project
+        debug!("Ignoring pinned Python version ({version}) at `{}`, it does not meet the project's Python requirement of `{requires_python}`.", path.user_display().cyan());
+        false
+    }
+}

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

@@ -2,16 +2,10 @@ use anstream::println;
 use anyhow::Result;
 
 use uv_cache::Cache;
-use uv_fs::{Simplified, CWD};
-use uv_python::{
-    EnvironmentPreference, PythonInstallation, PythonPreference, PythonRequest, PythonVersionFile,
-    VersionRequest,
-};
-use uv_resolver::RequiresPython;
-use uv_warnings::warn_user_once;
-use uv_workspace::{DiscoveryOptions, VirtualProject, WorkspaceError};
+use uv_fs::Simplified;
+use uv_python::{EnvironmentPreference, PythonInstallation, PythonPreference};
 
-use crate::commands::{project::find_requires_python, ExitStatus};
+use crate::commands::{project::find_python_request, ExitStatus};
 
 /// Find a Python interpreter.
 pub(crate) async fn find(
@@ -21,38 +15,7 @@ pub(crate) async fn find(
     python_preference: PythonPreference,
     cache: &Cache,
 ) -> Result<ExitStatus> {
-    // (1) Explicit request from user
-    let mut request = request.map(|request| PythonRequest::parse(&request));
-
-    // (2) Request from `.python-version`
-    if request.is_none() {
-        request = PythonVersionFile::discover(&*CWD, no_config, false)
-            .await?
-            .and_then(PythonVersionFile::into_version);
-    }
-
-    // (3) `Requires-Python` in `pyproject.toml`
-    if request.is_none() && !no_project {
-        let project = match VirtualProject::discover(&CWD, &DiscoveryOptions::default()).await {
-            Ok(project) => Some(project),
-            Err(WorkspaceError::MissingProject(_)) => None,
-            Err(WorkspaceError::MissingPyprojectToml) => None,
-            Err(WorkspaceError::NonWorkspace(_)) => None,
-            Err(err) => {
-                warn_user_once!("{err}");
-                None
-            }
-        };
-
-        if let Some(project) = project {
-            request = find_requires_python(project.workspace())?
-                .as_ref()
-                .map(RequiresPython::specifiers)
-                .map(|specifiers| {
-                    PythonRequest::Version(VersionRequest::Range(specifiers.clone()))
-                });
-        }
-    }
+    let request = find_python_request(request, no_project, no_config).await?;
 
     let python = PythonInstallation::find(
         &request.unwrap_or_default(),

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

@@ -153,7 +153,7 @@ pub(crate) async fn pin(
     Ok(ExitStatus::Success)
 }
 
-fn pep440_version_from_request(request: &PythonRequest) -> Option<pep440_rs::Version> {
+pub(crate) fn pep440_version_from_request(request: &PythonRequest) -> Option<pep440_rs::Version> {
     let version_request = match request {
         PythonRequest::Version(ref version)
         | PythonRequest::ImplementationVersion(_, ref version) => version,

crates/uv/tests/python_find.rs

@@ -232,15 +232,15 @@ fn python_find_pin() {
 
 #[test]
 fn python_find_project() {
-    let context: TestContext = TestContext::new_with_versions(&["3.11", "3.12"]);
+    let context: TestContext = TestContext::new_with_versions(&["3.10", "3.11", "3.12"]);
 
     let pyproject_toml = context.temp_dir.child("pyproject.toml");
     pyproject_toml
         .write_str(indoc! {r#"
         [project]
         name = "project"
         version = "0.1.0"
-        requires-python = ">=3.12"
+        requires-python = ">=3.11"
         dependencies = ["anyio==3.7.0"]
     "#})
         .unwrap();
@@ -250,17 +250,17 @@ fn python_find_project() {
     success: true
     exit_code: 0
     ----- stdout -----
-    [PYTHON-3.12]
+    [PYTHON-3.11]
 
     ----- stderr -----
     "###);
 
     // Unless explicitly requested
-    uv_snapshot!(context.filters(), context.python_find().arg("3.11"), @r###"
+    uv_snapshot!(context.filters(), context.python_find().arg("3.10"), @r###"
     success: true
     exit_code: 0
     ----- stdout -----
-    [PYTHON-3.11]
+    [PYTHON-3.10]
 
     ----- stderr -----
     "###);
@@ -270,6 +270,69 @@ fn python_find_project() {
     success: true
     exit_code: 0
     ----- stdout -----
+    [PYTHON-3.10]
+
+    ----- stderr -----
+    "###);
+
+    // But a pin should take precedence
+    uv_snapshot!(context.filters(), context.python_pin().arg("3.12"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Pinned `.python-version` to `3.12`
+
+    ----- stderr -----
+    "###);
+    uv_snapshot!(context.filters(), context.python_find(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    [PYTHON-3.12]
+
+    ----- stderr -----
+    "###);
+
+    // Create a pin that's incompatible with the project
+    uv_snapshot!(context.filters(), context.python_pin().arg("3.10").arg("--no-workspace"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Updated `.python-version` from `3.12` -> `3.10`
+
+    ----- stderr -----
+    "###);
+
+    // We should warn on subsequent uses, but respect the version?
+    uv_snapshot!(context.filters(), context.python_find(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    [PYTHON-3.10]
+
+    ----- stderr -----
+    warning: The pinned Python version (3.10) in `.python-version` does not meet the project's Python requirement of `>=3.11`.
+    "###);
+
+    // Unless the pin file is outside the project, in which case we just ignore it
+    let child_dir = context.temp_dir.child("child");
+    child_dir.create_dir_all().unwrap();
+
+    let pyproject_toml = child_dir.child("pyproject.toml");
+    pyproject_toml
+        .write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.11"
+        dependencies = ["anyio==3.7.0"]
+    "#})
+        .unwrap();
+
+    uv_snapshot!(context.filters(), context.python_find().current_dir(&child_dir), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
     [PYTHON-3.11]
 
     ----- stderr -----