Add support for dynamic cache keys (#7136)

## Summary

This PR adds a more flexible cache invalidation abstraction for uv, and
uses that new abstraction to improve support for dynamic metadata.

Specifically, instead of relying solely on a timestamp, we now pass
around a `CacheInfo` struct which (as of now) contains
`Option<Timestamp>` and `Option<Commit>`. The `CacheInfo` is saved in
`dist-info` as `uv_cache.json`, so we can test already-installed
distributions for cache validity (along with testing _cached_
distributions for cache validity).

Beyond the defaults (`pyproject.toml`, `setup.py`, and `setup.cfg`
changes), users can also specify additional cache keys, and it's easy
for us to extend support in the future. Right now, cache keys can either
be instructions to include the current commit (for `setuptools_scm` and
similar) or file paths (for `hatch-requirements-txt` and similar):

```toml
[tool.uv]
cache-keys = [{ file = "requirements.txt" }, { git = true }]
```

This change should be fully backwards compatible.

Closes #6964.

Closes #6255.

Closes #6860.

Cargo.toml

@@ -30,6 +30,7 @@ requirements-txt = { path = "crates/requirements-txt" }
 uv-auth = { path = "crates/uv-auth" }
 uv-build = { path = "crates/uv-build" }
 uv-cache = { path = "crates/uv-cache" }
+uv-cache-info = { path = "crates/uv-cache-info" }
 uv-cli = { path = "crates/uv-cli" }
 uv-client = { path = "crates/uv-client" }
 uv-configuration = { path = "crates/uv-configuration" }

crates/distribution-types/Cargo.toml

@@ -19,6 +19,7 @@ pep440_rs = { workspace = true }
 pep508_rs = { workspace = true, features = ["serde"] }
 platform-tags = { workspace = true }
 pypi-types = { workspace = true }
+uv-cache-info = { workspace = true }
 uv-fs = { workspace = true }
 uv-git = { workspace = true }
 uv-normalize = { workspace = true }

crates/distribution-types/src/cached.rs

@@ -5,6 +5,7 @@ use anyhow::{anyhow, Result};
 use distribution_filename::WheelFilename;
 use pep508_rs::VerbatimUrl;
 use pypi_types::{HashDigest, ParsedDirectoryUrl};
+use uv_cache_info::CacheInfo;
 use uv_normalize::PackageName;
 
 use crate::{
@@ -26,6 +27,7 @@ pub struct CachedRegistryDist {
     pub filename: WheelFilename,
     pub path: PathBuf,
     pub hashes: Vec<HashDigest>,
+    pub cache_info: CacheInfo,
 }
 
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
@@ -36,6 +38,7 @@ pub struct CachedDirectUrlDist {
     pub editable: bool,
     pub r#virtual: bool,
     pub hashes: Vec<HashDigest>,
+    pub cache_info: CacheInfo,
 }
 
 impl CachedDist {
@@ -44,18 +47,21 @@ impl CachedDist {
         remote: Dist,
         filename: WheelFilename,
         hashes: Vec<HashDigest>,
+        cache_info: CacheInfo,
         path: PathBuf,
     ) -> Self {
         match remote {
             Dist::Built(BuiltDist::Registry(_dist)) => Self::Registry(CachedRegistryDist {
                 filename,
                 path,
                 hashes,
+                cache_info,
             }),
             Dist::Built(BuiltDist::DirectUrl(dist)) => Self::Url(CachedDirectUrlDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: false,
                 r#virtual: false,
@@ -64,6 +70,7 @@ impl CachedDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: false,
                 r#virtual: false,
@@ -72,11 +79,13 @@ impl CachedDist {
                 filename,
                 path,
                 hashes,
+                cache_info,
             }),
             Dist::Source(SourceDist::DirectUrl(dist)) => Self::Url(CachedDirectUrlDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: false,
                 r#virtual: false,
@@ -85,6 +94,7 @@ impl CachedDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: false,
                 r#virtual: false,
@@ -93,6 +103,7 @@ impl CachedDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: false,
                 r#virtual: false,
@@ -101,6 +112,7 @@ impl CachedDist {
                 filename,
                 url: dist.url,
                 hashes,
+                cache_info,
                 path,
                 editable: dist.editable,
                 r#virtual: dist.r#virtual,
@@ -116,6 +128,14 @@ impl CachedDist {
         }
     }
 
+    /// Return the [`CacheInfo`] of the distribution.
+    pub fn cache_info(&self) -> &CacheInfo {
+        match self {
+            Self::Registry(dist) => &dist.cache_info,
+            Self::Url(dist) => &dist.cache_info,
+        }
+    }
+
     /// Return the [`ParsedUrl`] of the distribution, if it exists.
     pub fn parsed_url(&self) -> Result<Option<ParsedUrl>> {
         match self {
@@ -161,12 +181,14 @@ impl CachedDirectUrlDist {
         filename: WheelFilename,
         url: VerbatimUrl,
         hashes: Vec<HashDigest>,
+        cache_info: CacheInfo,
         path: PathBuf,
     ) -> Self {
         Self {
             filename,
             url,
             hashes,
+            cache_info,
             path,
             editable: false,
             r#virtual: false,

crates/distribution-types/src/installed.rs

@@ -10,6 +10,7 @@ use url::Url;
 use distribution_filename::EggInfoFilename;
 use pep440_rs::Version;
 use pypi_types::DirectUrl;
+use uv_cache_info::CacheInfo;
 use uv_fs::Simplified;
 use uv_normalize::PackageName;
 
@@ -35,6 +36,7 @@ pub struct InstalledRegistryDist {
     pub name: PackageName,
     pub version: Version,
     pub path: PathBuf,
+    pub cache_info: Option<CacheInfo>,
 }
 
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
@@ -45,6 +47,7 @@ pub struct InstalledDirectUrlDist {
     pub url: Url,
     pub editable: bool,
     pub path: PathBuf,
+    pub cache_info: Option<CacheInfo>,
 }
 
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
@@ -90,6 +93,7 @@ impl InstalledDist {
 
             let name = PackageName::from_str(name)?;
             let version = Version::from_str(version).map_err(|err| anyhow!(err))?;
+            let cache_info = Self::cache_info(path)?;
 
             return if let Some(direct_url) = Self::direct_url(path)? {
                 match Url::try_from(&direct_url) {
@@ -100,13 +104,15 @@ impl InstalledDist {
                         direct_url: Box::new(direct_url),
                         url,
                         path: path.to_path_buf(),
+                        cache_info,
                     }))),
                     Err(err) => {
                         warn!("Failed to parse direct URL: {err}");
                         Ok(Some(Self::Registry(InstalledRegistryDist {
                             name,
                             version,
                             path: path.to_path_buf(),
+                            cache_info,
                         })))
                     }
                 }
@@ -115,6 +121,7 @@ impl InstalledDist {
                     name,
                     version,
                     path: path.to_path_buf(),
+                    cache_info,
                 })))
             };
         }
@@ -256,13 +263,27 @@ impl InstalledDist {
     /// Read the `direct_url.json` file from a `.dist-info` directory.
     pub fn direct_url(path: &Path) -> Result<Option<DirectUrl>> {
         let path = path.join("direct_url.json");
-        let Ok(file) = fs_err::File::open(path) else {
-            return Ok(None);
+        let file = match fs_err::File::open(&path) {
+            Ok(file) => file,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+            Err(err) => return Err(err.into()),
         };
         let direct_url = serde_json::from_reader::<fs_err::File, DirectUrl>(file)?;
         Ok(Some(direct_url))
     }
 
+    /// Read the `uv_cache.json` file from a `.dist-info` directory.
+    pub fn cache_info(path: &Path) -> Result<Option<CacheInfo>> {
+        let path = path.join("uv_cache.json");
+        let file = match fs_err::File::open(&path) {
+            Ok(file) => file,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+            Err(err) => return Err(err.into()),
+        };
+        let cache_info = serde_json::from_reader::<fs_err::File, CacheInfo>(file)?;
+        Ok(Some(cache_info))
+    }
+
     /// Read the `METADATA` file from a `.dist-info` directory.
     pub fn metadata(&self) -> Result<pypi_types::Metadata23> {
         match self {

crates/install-wheel-rs/Cargo.toml

@@ -2,7 +2,7 @@
 name = "install-wheel-rs"
 version = "0.0.1"
 publish = false
-description = "Takes a wheel and installs it, either in a venv or for monotrail"
+description = "Takes a wheel and installs it."
 keywords = ["wheel", "python"]
 
 edition = { workspace = true }
@@ -24,6 +24,7 @@ distribution-filename = { workspace = true }
 pep440_rs = { workspace = true }
 platform-tags = { workspace = true }
 pypi-types = { workspace = true }
+uv-cache-info = { workspace = true }
 uv-fs = { workspace = true }
 uv-normalize = { workspace = true }
 uv-warnings = { workspace = true }