Allow dependency metadata entires for direct URL requirements

Author: charliermarsh

crates/distribution-types/src/dependency_metadata.rs

@@ -3,6 +3,7 @@ use pep508_rs::Requirement;
 use pypi_types::{ResolutionMetadata, VerbatimParsedUrl};
 use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
+use tracing::debug;
 use uv_normalize::{ExtraName, PackageName};
 
 /// Pre-defined [`StaticMetadata`] entries, indexed by [`PackageName`] and [`Version`].
@@ -20,22 +21,58 @@ impl DependencyMetadata {
     }
 
     /// Retrieve a [`StaticMetadata`] entry by [`PackageName`] and [`Version`].
-    pub fn get(&self, package: &PackageName, version: &Version) -> Option<ResolutionMetadata> {
+    pub fn get(
+        &self,
+        package: &PackageName,
+        version: Option<&Version>,
+    ) -> Option<ResolutionMetadata> {
         let versions = self.0.get(package)?;
 
-        // Search for an exact, then a global match.
-        let metadata = versions
-            .iter()
-            .find(|v| v.version.as_ref() == Some(version))
-            .or_else(|| versions.iter().find(|v| v.version.is_none()))?;
-
-        Some(ResolutionMetadata {
-            name: metadata.name.clone(),
-            version: version.clone(),
-            requires_dist: metadata.requires_dist.clone(),
-            requires_python: metadata.requires_python.clone(),
-            provides_extras: metadata.provides_extras.clone(),
-        })
+        if let Some(version) = version {
+            // If a specific version was requested, search for an exact match, then a global match.
+            let metadata = versions
+                .iter()
+                .find(|v| v.version.as_ref() == Some(version))
+                .map(|metadata| {
+                    debug!("Found dependency metadata entry for `{package}=={version}`",);
+                    metadata
+                })
+                .or_else(|| versions.iter().find(|v| v.version.is_none()))
+                .map(|metadata| {
+                    debug!("Found global metadata entry for `{package}`",);
+                    metadata
+                });
+            let Some(metadata) = metadata else {
+                debug!("No dependency metadata entry found for `{package}=={version}`");
+                return None;
+            };
+            Some(ResolutionMetadata {
+                name: metadata.name.clone(),
+                version: version.clone(),
+                requires_dist: metadata.requires_dist.clone(),
+                requires_python: metadata.requires_python.clone(),
+                provides_extras: metadata.provides_extras.clone(),
+            })
+        } else {
+            // If no version was requested (i.e., it's a direct URL dependency), allow a single
+            // versioned match.
+            let [metadata] = versions.as_slice() else {
+                debug!("Multiple dependency metadata entries found for `{package}`");
+                return None;
+            };
+            let Some(version) = metadata.version.clone() else {
+                debug!("No version found in dependency metadata entry for `{package}`");
+                return None;
+            };
+            debug!("Found dependency metadata entry for `{package}` (assuming: `{version}`)");
+            Some(ResolutionMetadata {
+                name: metadata.name.clone(),
+                version,
+                requires_dist: metadata.requires_dist.clone(),
+                requires_python: metadata.requires_python.clone(),
+                provides_extras: metadata.provides_extras.clone(),
+            })
+        }
     }
 
     /// Retrieve all [`StaticMetadata`] entries.

crates/uv-distribution/src/distribution_database.rs

@@ -363,7 +363,7 @@ impl<'a, Context: BuildContext> DistributionDatabase<'a, Context> {
         if let Some(metadata) = self
             .build_context
             .dependency_metadata()
-            .get(dist.name(), dist.version())
+            .get(dist.name(), Some(dist.version()))
         {
             return Ok(ArchiveMetadata::from_metadata23(metadata.clone()));
         }
@@ -425,14 +425,12 @@ impl<'a, Context: BuildContext> DistributionDatabase<'a, Context> {
     ) -> Result<ArchiveMetadata, Error> {
         // If the metadata was provided by the user directly, prefer it.
         if let Some(dist) = source.as_dist() {
-            if let Some(version) = dist.version() {
-                if let Some(metadata) = self
-                    .build_context
-                    .dependency_metadata()
-                    .get(dist.name(), version)
-                {
-                    return Ok(ArchiveMetadata::from_metadata23(metadata.clone()));
-                }
+            if let Some(metadata) = self
+                .build_context
+                .dependency_metadata()
+                .get(dist.name(), dist.version())
+            {
+                return Ok(ArchiveMetadata::from_metadata23(metadata.clone()));
             }
         }
 

crates/uv/tests/lock.rs

@@ -13007,6 +13007,131 @@ fn lock_dependency_metadata() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn lock_dependency_metadata_url() -> Result<()> {
+    let context = TestContext::new("3.12");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(
+        r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = ["anyio"]
+
+        [tool.uv.sources]
+        anyio = { git = "https://github.com/agronholm/anyio", rev = "bd36d3a5e5319dec71728c517d5e04cefb95650e" }
+
+        [build-system]
+        requires = ["setuptools>=42"]
+        build-backend = "setuptools.build_meta"
+
+        [[tool.uv.dependency-metadata]]
+        name = "anyio"
+        version = "4.6.0.post2"
+        requires-dist = ["iniconfig"]
+        "#,
+    )?;
+
+    uv_snapshot!(context.filters(), context.lock(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 3 packages in [TIME]
+    "###);
+
+    let lock = context.read("uv.lock");
+
+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        assert_snapshot!(
+            lock, @r###"
+        version = 1
+        requires-python = ">=3.12"
+
+        [options]
+        exclude-newer = "2024-03-25T00:00:00Z"
+
+        [manifest]
+
+        [[manifest.dependency-metadata]]
+        name = "anyio"
+        version = "4.6.0.post2"
+        requires-dist = ["iniconfig"]
+
+        [[package]]
+        name = "anyio"
+        version = "4.6.0.post2"
+        source = { git = "https://github.com/agronholm/anyio?rev=bd36d3a5e5319dec71728c517d5e04cefb95650e#bd36d3a5e5319dec71728c517d5e04cefb95650e" }
+        dependencies = [
+            { name = "iniconfig" },
+        ]
+
+        [[package]]
+        name = "iniconfig"
+        version = "2.0.0"
+        source = { registry = "https://pypi.org/simple" }
+        sdist = { url = "https://files.pythonhosted.org/packages/d7/4b/cbd8e699e64a6f16ca3a8220661b5f83792b3017d0f79807cb8708d33913/iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3", size = 4646 }
+        wheels = [
+            { url = "https://files.pythonhosted.org/packages/ef/a6/62565a6e1cf69e10f5727360368e451d4b7f58beeac6173dc9db836a5b46/iniconfig-2.0.0-py3-none-any.whl", hash = "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374", size = 5892 },
+        ]
+
+        [[package]]
+        name = "project"
+        version = "0.1.0"
+        source = { editable = "." }
+        dependencies = [
+            { name = "anyio" },
+        ]
+
+        [package.metadata]
+        requires-dist = [{ name = "anyio", git = "https://github.com/agronholm/anyio?rev=bd36d3a5e5319dec71728c517d5e04cefb95650e" }]
+        "###
+        );
+    });
+
+    // Re-run with `--locked`.
+    uv_snapshot!(context.filters(), context.lock().arg("--locked"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 3 packages in [TIME]
+    "###);
+
+    // Re-run with `--offline`. We shouldn't need a network connection to validate an
+    // already-correct lockfile with immutable metadata.
+    uv_snapshot!(context.filters(), context.lock().arg("--locked").arg("--offline").arg("--no-cache"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 3 packages in [TIME]
+    "###);
+
+    // Install from the lockfile.
+    uv_snapshot!(context.filters(), context.sync().arg("--frozen"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Prepared 3 packages in [TIME]
+    Installed 3 packages in [TIME]
+     + anyio==4.6.0.post2 (from git+https://github.com/agronholm/anyio@bd36d3a5e5319dec71728c517d5e04cefb95650e)
+     + iniconfig==2.0.0
+     + project==0.1.0 (from file://[TEMP_DIR]/)
+    "###);
+
+    Ok(())
+}
+
 #[test]
 fn lock_strip_fragment() -> Result<()> {
     let context = TestContext::new("3.12");

docs/concepts/projects.md

@@ -797,3 +797,9 @@ You could run the following sequence of commands to sync `flash-attn`:
 $ uv sync --extra build
 $ uv sync --extra build --extra compile
 ```
+
+!!! note
+
+    The `version` field in `tool.uv.dependency-metadata` is optional for registry-based
+    dependencies (when omitted, uv will assume the metadata applies to all versions of the package),
+    but _required_ for direct URL dependencies.

docs/concepts/resolution.md

@@ -313,6 +313,12 @@ package's metadata is incorrect or incomplete, or when a package is not availabl
 index. While dependency overrides allow overriding the allowed versions of a package globally,
 metadata overrides allow overriding the declared metadata of a _specific package_.
 
+!!! note
+
+    The `version` field in `tool.uv.dependency-metadata` is optional for registry-based
+    dependencies (when omitted, uv will assume the metadata applies to all versions of the package),
+    but _required_ for direct URL dependencies.
+
 Entries in the `tool.uv.dependency-metadata` table follow the
 [Metadata 2.3](https://packaging.python.org/en/latest/specifications/core-metadata/) specification,
 though only `name`, `version`, `requires-dist`, `requires-python`, and `provides-extra` are read by