[Utils] Fix HfUri round-trip for revisions with '/' and hyphenated convert refs

Wauplin · Wauplin · commit 63df6900ae8c · 2026-04-28T12:55:24.000+02:00
- to_uri() now URL-encodes '/' in non-special revisions so 'feature/foo' round-trips correctly.
- _SPECIAL_REFS_REVISION_REGEX accepts '-' and '.' in convert ref names (e.g. 'refs/convert/parquet-v2').
diff --git a/src/huggingface_hub/utils/_hf_uris.py b/src/huggingface_hub/utils/_hf_uris.py
@@ -49,7 +49,9 @@
 # Special revisions that contain a '/'. They take precedence when splitting
 # the part after '@' into '<revision>/<path-in-repo>'. Matches 'refs/pr/N'
 # (Pull Request refs) and 'refs/convert/<name>' (e.g. parquet conversions).
-_SPECIAL_REFS_REVISION_REGEX = re.compile(r"^refs/(?:convert/\w+|pr/\d+)")
+# The conversion name allows the typical git ref characters '[a-zA-Z0-9_.-]'
+# so names like 'parquet-v2' or 'duckdb.v1' round-trip correctly.
+_SPECIAL_REFS_REVISION_REGEX = re.compile(r"^refs/(?:convert/[\w.-]+|pr/\d+)")
 
 
 @dataclass(frozen=True)
diff --git a/tests/test_utils_hf_uris.py b/tests/test_utils_hf_uris.py
@@ -139,6 +139,27 @@
         ),
         "hf://datasets/foo/bar@refs/convert/parquet/data.parquet",
     ),
+    # Convert ref name with hyphen (and dot) — must not be split at the hyphen.
+    (
+        "hf://datasets/foo/bar@refs/convert/parquet-v2/data.parquet",
+        HfUri(
+            type="dataset",
+            id="foo/bar",
+            revision="refs/convert/parquet-v2",
+            path_in_repo="data.parquet",
+        ),
+        "hf://datasets/foo/bar@refs/convert/parquet-v2/data.parquet",
+    ),
+    (
+        "hf://datasets/foo/bar@refs/convert/duckdb.v1/data.db",
+        HfUri(
+            type="dataset",
+            id="foo/bar",
+            revision="refs/convert/duckdb.v1",
+            path_in_repo="data.db",
+        ),
+        "hf://datasets/foo/bar@refs/convert/duckdb.v1/data.db",
+    ),
     # URL-encoded special revision
     (
         "hf://datasets/foo/bar@refs%2Fpr%2F10/file.csv",
