Fix and deprecate get_token_permission (#2631)

src/huggingface_hub/hf_api.py

@@ -1661,10 +1661,28 @@ def whoami(self, token: Union[bool, str, None] = None) -> Dict:
             ) from e
         return r.json()
 
-    def get_token_permission(self, token: Union[bool, str, None] = None) -> Literal["read", "write", None]:
+    @_deprecate_method(
+        version="1.0",
+        message=(
+            "Permissions are more complex than when `get_token_permission` was first introduced. "
+            "OAuth and fine-grain tokens allows for more detailed permissions. "
+            "If you need to know the permissions associated with a token, please use `whoami` and check the `'auth'` key."
+        ),
+    )
+    def get_token_permission(
+        self, token: Union[bool, str, None] = None
+    ) -> Literal["read", "write", "fineGrained", None]:
         """
         Check if a given `token` is valid and return its permissions.
 
+        <Tip warning={true}>
+
+        This method is deprecated and will be removed in version 1.0. Permissions are more complex than when
+        `get_token_permission` was first introduced. OAuth and fine-grain tokens allows for more detailed permissions.
+        If you need to know the permissions associated with a token, please use `whoami` and check the `'auth'` key.
+
+        </Tip>
+
         For more details about tokens, please refer to https://huggingface.co/docs/hub/security-tokens#what-are-user-access-tokens.
 
         Args:
@@ -1675,12 +1693,12 @@ def get_token_permission(self, token: Union[bool, str, None] = None) -> Literal[
                 To disable authentication, pass `False`.
 
         Returns:
-            `Literal["read", "write", None]`: Permission granted by the token ("read" or "write"). Returns `None` if no
-            token passed or token is invalid.
+            `Literal["read", "write", "fineGrained", None]`: Permission granted by the token ("read" or "write"). Returns `None` if no
+            token passed, if token is invalid or if role is not returned by the server. This typically happens when the token is an OAuth token.
         """
         try:
             return self.whoami(token=token)["auth"]["accessToken"]["role"]
-        except (LocalTokenNotFoundError, HTTPError):
+        except (LocalTokenNotFoundError, HTTPError, KeyError):
             return None
 
     def get_model_tags(self) -> Dict:

tests/test_hf_api.py

@@ -298,6 +298,17 @@ def test_update_dataset_repo_settings(self, repo_url: RepoUrl):
                 assert info.gated == gated_value
                 assert info.private == private_value
 
+    @expect_deprecation("get_token_permission")
+    def test_get_token_permission_on_oauth_token(self):
+        whoami = {
+            "type": "user",
+            "auth": {"type": "oauth", "expiresAt": "2024-10-24T19:43:43.000Z"},
+            # ...
+            # other values are ignored as we only need to check the "auth" value
+        }
+        with patch.object(self._api, "whoami", return_value=whoami):
+            assert self._api.get_token_permission() is None
+
 
 class CommitApiTest(HfApiCommonTest):
     def setUp(self) -> None: