fix(relevance): keep an empty HF cache variable, as huggingface_hub does

huggingface_hub reads its cache variables with os.getenv(name, default), so a
variable that is set but empty still counts: HF_HUB_CACHE='' is the working
directory, HF_HOME='' is `hub` and XDG_CACHE_HOME='' is `huggingface/hub`
under it. The Rust resolver treated an empty value as unset and fell through
to the next variable, so with HF_HUB_CACHE='' and HF_HOME set it looked up
and loaded a snapshot from HF_HOME/hub, a cache Python never reads.

- hf_hub_cache_dir() reads every path-valued variable as set when it is
  present, empty or not; expansion and precedence are unchanged.
- tests/parity/fixtures/hf_hub_cache/cases.json gains the empty cases for
  HF_HUB_CACHE, HUGGINGFACE_HUB_CACHE, HF_HOME and XDG_CACHE_HOME, checked
  against huggingface_hub.constants in Python and against the port in Rust.
This commit is contained in:
Kenneth Wong
2026-11-03 17:02:02 +08:00
parent 70afece87c
commit 62b792f05c
2 changed files with 54 additions and 9 deletions
@@ -119,16 +119,14 @@ fn default_model_revision() -> &'static str {
/// a `~` that only appears once a variable is expanded stays literal, as it
/// does in Python. The home directory comes from `std::env::home_dir`, which
/// falls back to the user database when `HOME` is unset, as `expanduser`
/// does. An empty variable counts as unset; Python would treat it as a path
/// relative to the working directory. `tests/parity/fixtures/hf_hub_cache/`
/// does. A variable that is set but empty still counts, as with `os.getenv`:
/// `HF_HUB_CACHE=''` is the working directory itself, `HF_HOME=''` is `hub`
/// and `XDG_CACHE_HOME=''` is `huggingface/hub` under it, and none of them
/// falls through to a lower-priority cache. `tests/parity/fixtures/hf_hub_cache/`
/// holds the cases both languages are checked against.
#[cfg(feature = "ml")]
fn hf_hub_cache_dir() -> Option<PathBuf> {
let var = |name: &str| {
std::env::var_os(name)
.filter(|v| !v.is_empty())
.map(PathBuf::from)
};
let var = |name: &str| std::env::var_os(name).map(PathBuf::from);
let home = std::env::home_dir();
let expand = |path: PathBuf| expand_vars(&expand_user(path, home.as_deref()));
let hub = match var("HF_HUB_CACHE").or_else(|| var("HUGGINGFACE_HUB_CACHE")) {
@@ -932,13 +930,21 @@ mod tests {
Some(p("home").join(".cache").join("huggingface").join("hub"))
);
// An empty variable counts as unset, and a leading `~` expands.
std::env::set_var("HF_HUB_CACHE", "");
// A leading `~` expands.
std::env::set_var("HF_HOME", "~/models");
assert_eq!(
hf_hub_cache_dir(),
Some(p("home").join("models").join("hub"))
);
// A set but empty variable is the working directory, as in Python,
// and still wins over every variable after it.
std::env::set_var("HF_HUB_CACHE", "");
assert_eq!(hf_hub_cache_dir(), Some(PathBuf::new()));
std::env::remove_var("HF_HUB_CACHE");
std::env::set_var("HF_HOME", "");
std::env::set_var("XDG_CACHE_HOME", p("xdg"));
assert_eq!(hf_hub_cache_dir(), Some(PathBuf::from("hub")));
}
/// Cases checked against Python itself (`posixpath`, `ntpath` and
@@ -230,6 +230,45 @@
"nt": "{root}/hub"
}
},
{
"name": "an empty HF_HUB_CACHE is the working directory, not HF_HOME (the #4438 review case)",
"env": {
"HF_HUB_CACHE": "",
"HF_HOME": "{root}/fallback-home"
},
"expected": ""
},
{
"name": "an empty legacy HUGGINGFACE_HUB_CACHE is the working directory",
"env": {
"HUGGINGFACE_HUB_CACHE": "",
"HF_HOME": "{root}/fallback-home"
},
"expected": ""
},
{
"name": "an empty HF_HUB_CACHE still wins over a set legacy HUGGINGFACE_HUB_CACHE",
"env": {
"HF_HUB_CACHE": "",
"HUGGINGFACE_HUB_CACHE": "{root}/legacy"
},
"expected": ""
},
{
"name": "an empty HF_HOME is hub under the working directory, not XDG_CACHE_HOME",
"env": {
"HF_HOME": "",
"XDG_CACHE_HOME": "{root}/xdg"
},
"expected": "hub"
},
{
"name": "an empty XDG_CACHE_HOME is huggingface/hub under the working directory, not the home default",
"env": {
"XDG_CACHE_HOME": ""
},
"expected": "huggingface/hub"
},
{
"name": "nothing set: the default under the home directory",
"env": {},