[Core] Migrate hf:// URI parsing to centralized parse_hf_uri by Wauplin · Pull Request #4189 · huggingface/huggingface_hub

Wauplin · 2026-05-05T09:54:26Z

Summary

Follow-up to #4158. Replaces all scattered ad-hoc hf:// URI parsers with the centralized parse_hf_uri/parse_hf_mount helpers.

Not touched (as mentioned in #4158): repo_type_and_id_from_hf_id and RepoUrl — these are mixed parsers accepting both hf:// URIs and https://huggingface.co/... URLs and need a separate migration plan.

Breaking changes

BucketUrl.handle → BucketUrl.uri — Attribute renamed and type changed from str to HfUri. Any code accessing bucket_url.handle must switch to bucket_url.uri (use .to_uri() for the string form).
Volume.to_hf_handle() → Volume.to_uri() — Method renamed. Any code calling .to_hf_handle() must switch to .to_uri().
Single-segment repo IDs no longer supported in HfFileSystem — Paths like gpt2, gpt2/file.txt, or gpt2@dev/file.txt no longer resolve. Repo IDs must use the namespace/name format (e.g. username/gpt2).
Single-segment repo IDs rejected in CLI -v flags — hf://gpt2:/data is no longer accepted. Must use hf://namespace/name:/mount form.

Improvements

@ in filenames is now treated as literal (e.g. hf://a/b/file@v1.txt parses correctly instead of erroring).
HfUriError is now caught by the CLI error handler and shows a clean message instead of a raw traceback.
New is_hf_uri public helper for validating hf:// URIs.

🤖 Generated with Claude Code

Note

Medium Risk
Medium risk because this is a cross-cutting refactor of URI parsing that introduces breaking API/CLI behavior changes (renamed fields/methods and stricter URI formats), which could impact downstream integrations and edge-case path resolution.

Overview
Centralizes all hf:// parsing on parse_hf_uri/parse_hf_mount and removes multiple ad-hoc parsers across buckets, copy helpers, CLI volume parsing, and HfFileSystem.

Introduces breaking API/CLI changes: BucketUrl.handle is replaced by BucketUrl.uri (HfUri), Volume.to_hf_handle() is renamed to to_uri(), and CLI output/docs/examples are updated from “handle” wording to canonical “URI” formatting.

Tightens URI validation/semantics: HfFileSystem and CLI -v/--volume now reject single-segment repo IDs (must be namespace/name), CLI errors now format HfUriError cleanly, and URI parsing is improved to treat @ in filenames as literal (while still supporting revision markers where valid).

^{Reviewed by Cursor Bugbot for commit a471279. Bugbot is set up for automated code reviews on this repo. Configure here.}

Replace scattered ad-hoc hf:// URI parsers with the centralized `parse_hf_uri`/`parse_hf_mount` helpers introduced in #4158. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

bot-ci-comment · 2026-05-05T10:00:30Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Add explicit type annotations for `repo_type` and `revision_in_path` to satisfy mypy's narrowing across branches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…object

Wauplin · 2026-05-05T15:08:13Z

+        return False
+
+
+@functools.lru_cache


added since some logic is now parsing multiple time the same URI (once to check if it's an URI, then to check if it's a bucket, then to reuse its parsed values, etc.). Easier to use a LRU cache rather than parsing the value once and passing it everywhere

Wauplin · 2026-05-05T15:08:46Z

    namespace: str = field(init=False)
    bucket_id: str = field(init=False)
-    handle: str = field(init=False)
+    uri: HfUri = field(init=False)


intentional breaking change

IMO ok to break as I don't expect anyone to use it at the moment (and it's nice to consistently use the 'uri' naming)

yes makes sense!

Wauplin · 2026-05-05T15:09:57Z

-        revision = f"@{self.revision}" if self.revision else ""
-        ro = {True: ":ro", False: ":rw", None: ""}.get(self.read_only, "")
-        return f"hf://{self.type}s/{self.source}{revision}{path}:{self.mount_path}{ro}"
+    def to_hf_mount_uri(self) -> str:


intentional breaking change

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The `parsed` variable was reused across two branches with incompatible types (HfUri vs None). Renamed to `parsed_or_none` with an explicit `HfUri | None` annotation in the second branch to satisfy mypy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Wauplin · 2026-05-06T13:02:41Z

PR should finally be ready for review! I tried to account for all possible use cases that were previously handled. This PR is introducing a few breaking changes (see PR description) that are intentional. Hopefully won't impact anyone 🤞 Parsing logic should be must cleaner now 😃

lhoestq · 2026-05-06T13:33:17Z

Could HfUri work like RepoUrl and be a string subclass ? This would avoid bucket.uri.to_uri() which I find a bit weird

Wauplin · 2026-05-06T13:43:35Z

Could HfUri work like RepoUrl and be a string subclass ? This would avoid bucket.uri.to_uri() which I find a bit weird

I'd rather not no. RepoUrl is a str subclass for legacy reasons rather than a desired choice. What we can do is adding an alias method BucketUrl.to_uri() to avoid the BucketUrk.uri.to_uri().

The reason why I don't want to implement something like str(HfUri) is that in the future I'm planning to add a to_url() method to get the url on the Hub of any resource described by a URI (e.g. a repo, a folder in a bucket, a file in a specific revision of a dataset, etc.). That should help simplify some other scattered logic we have + easily print URLs in the CLI.

lhoestq · 2026-05-06T15:40:08Z

I see ! in that case I have a small pref for bucket.uri.to_string() but not a big deal

Wauplin · 2026-05-06T16:45:19Z

I see ! in that case I have a small pref for bucket.uri.to_string() but not a big deal

hmm, but I want to be able to do bucket.uri.to_uri() and bucket.uri.to_url() actually

hanouticelina

Thank you for simplifying the logic here! the PR looks globally good, I left a couple of comments and I will take another look before merging.

up to you if you want to do it in another PR, but let's drop the local try/except ValueError blocks in cli/buckets.py now that the global handler exists, non-URI parse failures still get a reasonable error message.

hanouticelina · 2026-05-12T14:07:38Z

I love the cleaning done here! ❤️

hanouticelina · 2026-05-12T14:23:22Z

    namespace: str = field(init=False)
    bucket_id: str = field(init=False)
-    handle: str = field(init=False)
+    uri: HfUri = field(init=False)


yes makes sense!

Wauplin · 2026-05-18T15:16:11Z

up to you if you want to do it in another PR, but let's drop the local try/except ValueError blocks in cli/buckets.py now that the global handler exists, non-URI parse failures still get a reasonable error message.

yes correct 👍 addressed in c843f32

Wauplin · 2026-05-18T15:29:04Z

@hanouticelina Addressed all of your comments, thanks for the review!

cursor

Cursor Bugbot has reviewed your changes using default mode and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 19cdfc0. Configure here.}

hanouticelina

Awesome 🔥 thanks again!

Wauplin · 2026-05-19T12:49:46Z

Youhou! Merging 🙌

huggingface-hub-bot · 2026-05-21T12:26:30Z

This PR has been shipped as part of the v1.16.0 release.

[Core] Migrate hf:// URI parsing to centralized parse_hf_uri

76f1e98

Replace scattered ad-hoc hf:// URI parsers with the centralized `parse_hf_uri`/`parse_hf_mount` helpers introduced in #4158. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Wauplin marked this pull request as draft May 5, 2026 09:55

Fix mypy type errors in hf_file_system.py

9302915

Add explicit type annotations for `repo_type` and `revision_in_path` to satisfy mypy's narrowing across branches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/_cli_utils.py

pass revision in Volume parsing

24ee993

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/_space_api.py

better

35754d2

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/_cli_utils.py

Merge branch 'main' into use-parse-hf-uri

5fc5e2b

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/buckets.py

Wauplin added 2 commits May 5, 2026 16:31

rename everything to hf uri instaed of hf handle

4300132

also in markdown

dbc6164

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/_buckets.py Outdated

Wauplin added 2 commits May 5, 2026 17:01

no more _split_bucket_id_and_prefix + _parse_bucket_uri return HfUri …

70bc6f8

…object

unslop

378704d

Wauplin commented May 5, 2026

View reviewed changes

Wauplin added 2 commits May 5, 2026 17:11

add back comment

7b48701

no @ in filenames for buckets

ca73113

cursor Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/huggingface_hub/hf_file_system.py

Wauplin and others added 8 commits May 5, 2026 17:30

allow '@' in filenames for both repo and bucket URIs

0430b7a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'main' into use-parse-hf-uri

daa4a44

changed my mind

0a8b4b2

remove legacy testss

85bbbe4

Merge branch 'main' into use-parse-hf-uri

5119892

fix tests

e78341b

fix merge

9621b84

Wauplin marked this pull request as ready for review May 6, 2026 12:59

Wauplin requested review from hanouticelina and lhoestq May 6, 2026 13:00

Merge branch 'main' into use-parse-hf-uri

89eea34

Wauplin mentioned this pull request May 7, 2026

[Copy] Support cross-repo file copies #4203

Merged

hanouticelina reviewed May 12, 2026

View reviewed changes

davanstrien mentioned this pull request May 13, 2026

Support hf://buckets/... URIs for reads (scan_* / read_*) pola-rs/polars#27611

Open

Wauplin added 2 commits May 18, 2026 17:13

Merge branch 'main' into use-parse-hf-uri

9ab2d7c

remove the useless try/except ValueError

c843f32

Wauplin added 3 commits May 18, 2026 17:21

feedback

ca7929a

feedback

f8f2d8d

address feedback

19cdfc0

cursor Bot reviewed May 18, 2026

View reviewed changes

Comment thread src/huggingface_hub/hf_file_system.py

Wauplin added 2 commits May 18, 2026 17:40

fix tests

4714739

better

a471279

Wauplin requested a review from hanouticelina May 19, 2026 09:17

Wauplin mentioned this pull request May 19, 2026

[CLI] Allow hf cache rm repo:path for file/variant deletions #4226

Closed

hanouticelina approved these changes May 19, 2026

View reviewed changes

Wauplin merged commit 70e6fd9 into main May 19, 2026
21 checks passed

Wauplin deleted the use-parse-hf-uri branch May 19, 2026 12:49

abhinavgautam01 mentioned this pull request May 19, 2026

[CLI] Support hf:// URIs in cache rm #4235

Merged

Conversation

Wauplin commented May 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes

Improvements

Uh oh!

bot-ci-comment Bot commented May 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hanouticelina May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Wauplin commented May 6, 2026

Uh oh!

lhoestq commented May 6, 2026

Uh oh!

Wauplin commented May 6, 2026

Uh oh!

lhoestq commented May 6, 2026

Uh oh!

Wauplin commented May 6, 2026

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

hanouticelina May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hanouticelina May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin commented May 18, 2026

Uh oh!

Wauplin commented May 18, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Wauplin commented May 19, 2026

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Wauplin commented May 5, 2026 •

edited by cursor Bot

Loading

Wauplin May 5, 2026 •

edited

Loading