Fix and deprecate get_token_permission

[Wauplin]

As reported by @CISC in gradio-app/gradio#9820 (comment), using get_token_permission with an OAuth token is broken:

...
  File "/home/user/app/app.py", line 985, in template_data_from_model_files
    if info and oauth_token and hfapi.get_token_permission(oauth_token.token) == "write":
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/huggingface_hub/hf_api.py", line 1691, in get_token_permission
    return self.whoami(token=token)["auth"]["accessToken"]["role"]
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
KeyError: 'accessToken'

This is because the whoami response for an OAuth token doesn't contain the detailed permission for that token.

This PR fixes get_token_permission to not raise an error when a OAuth token is passed but return None instead. This is a half-satisfying fix but at least it won't break things in the wild (same output as if no token is passed). What I also did is to fully deprecate this method as it doesn't make any sense to have it anymore. Deprecation cycle runs until v1.0.0. Tokens are not just "read" or "write". OAuth and fine-grained tokens have much more complex permissions depending on the user choices.

---

In a follow-up PR, I'll make sure to remove all internal use of get_token_permission. This doesn't have to be done in the same PR.

[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.

[CISC]

Aha, that explains it, thank you for picking this up! :)

[hanouticelina]

LGTM! thanks

[hanouticelina]

is there a particular reason why the deprecation runs until 1.0.0 and not in three minor versions? except maybe the fact that it may lead to some frictions if we remove it too soon 😅

[Wauplin]

Got too shy to remove it in 3 minor versions 😄
TBH, also because it's 4 lines of code so not a big deal if kept for a longer time. Permissions is a quite sensitive topic.