Add optional cache to whoami

[Wauplin]

Suggested by @abidlabs on private slack after gradio-app/trackio#344 being opened to fix rate limits errors while dealing with whoami.

The root problem is that /whoami-v2 is heavily IP-rate-limited to avoid abuse. This is usually not a problem since user needs to do it only once to check if they are logged in. But in some subsequent libraries, the whoami endpoint is used to determine what will be the default namespace for a newly create repo (default to user's username). If the library calls that endpoint too often, it will lead to a HTTP 429 rate limit that could have been easily prevented. PR gradio-app/trackio#344 introduced a cache in trackio but let's make it available at huggingface_hub level directly. Note that we do not want to cache the result by default as this would not be consistent with any other methods in HfApi. HfApi remains a simple HTTP client and by default, someone calling a method expects an HTTP endpoint to be actually called.

With this PR:

• whoami(..., cache=True) to cache results from /whoami-v2 endpoint
• cache is isolated per HfApi instance
• cache is in-memory and lives for the duration of the Python process
• no way to reset the cache (let's reassess in the future if requested, but I doubt it)
• I did not set a max size limit, in any case one would be rate limited before getting out of memory 😄
• if user gets rate-limited 429, an explicit message nudge them to use caching

Also added some tests + docs.

[HuggingFaceDocBuilderDev]

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.

[abidlabs]

This is a change in behavior, right? Previously, if token=False, we could still get the token from get_token(), but now we raise an exception?

[Wauplin]

No, since token=False explicitly means "do not retrieve the token locally". The breaking change is that previously it would raise an HTTP 401 unauthorized issue, and now a ValueError. I don't believe though that it's better like this to fail early.

[abidlabs]

Sorry I had to step away earlier but to clarify, I do agree that this change is the way to go and is inline with the docstring. But what I was saying was that previously, you would actually use the locally-saved token, even if a user passed token=False, because token or self.token or get_token() would keep going until a truthy value was found, so the logic would still fall back to a local token via get_token().

Unless I'm misunderstanding something, this would be a breaking change -- although I do agree that this is the right way to go. In fact, maybe a nit but I'd say we go even farther, and replace token = self.token with token = self.token if token is None else token, because again, this would mean that if a user does whoami(token=False), but has a token saved to the class would end up using that token, which is contrary to the docstring.

[hanouticelina]

^agree that we should do token = self.token if token is None else token since token can be False (as we do in _build_hf_headers).

[Wauplin]

Oh wow yes, agree with the above. Thanks for flagging!

I've fixed it in 0de490b and added a regression test in e3471ff. I would not consider this as a breaking change but as a bug fix 😄

[julien-c]

nice

[abidlabs]

Small comment but otherwise LGTM, thanks @Wauplin!

[hanouticelina]

thanks! this is a nice addition 👍

[hanouticelina]

^agree that we should do token = self.token if token is None else token since token can be False (as we do in _build_hf_headers).

[Wauplin]

Thanks for the review! I've addressed all comments so PR should be good to merge :)