chore: correct type-hints for ban() and unban()

JohnVillalovos · JohnVillalovos · commit d4c2b57b43dc · 2022-07-23T00:08:50.000-07:00
The functions return Optional[bool].

Add tests for their behavior
diff --git a/gitlab/v4/objects/users.py b/gitlab/v4/objects/users.py
@@ -326,7 +326,7 @@ def reject(self, **kwargs: Any) -> gitlab.client.HttpResponseType:
 
     @cli.register_custom_action("User")
     @exc.on_http_error(exc.GitlabBanError)
-    def ban(self, **kwargs: Any) -> gitlab.client.HttpResponseType:
+    def ban(self, **kwargs: Any) -> bool:
         """Ban the user.
 
         Args:
@@ -340,14 +340,16 @@ def ban(self, **kwargs: Any) -> gitlab.client.HttpResponseType:
             Whether the user has been banned
         """
         path = f"/users/{self.encoded_id}/ban"
-        server_data = self.manager.gitlab.http_post(path, **kwargs)
-        if server_data:
+        # NOTE: Undocumented behavior of the GitLab API is that it returns True
+        # on success.
+        server_data = cast(bool, self.manager.gitlab.http_post(path, **kwargs))
+        if server_data is True:
             self._attrs["state"] = "banned"
         return server_data
 
     @cli.register_custom_action("User")
     @exc.on_http_error(exc.GitlabUnbanError)
-    def unban(self, **kwargs: Any) -> gitlab.client.HttpResponseType:
+    def unban(self, **kwargs: Any) -> bool:
         """Unban the user.
 
         Args:
@@ -361,8 +363,10 @@ def unban(self, **kwargs: Any) -> gitlab.client.HttpResponseType:
             Whether the user has been unbanned
         """
         path = f"/users/{self.encoded_id}/unban"
-        server_data = self.manager.gitlab.http_post(path, **kwargs)
-        if server_data:
+        # NOTE: Undocumented behavior of the GitLab API is that it returns True
+        # on success.
+        server_data = cast(bool, self.manager.gitlab.http_post(path, **kwargs))
+        if server_data is True:
             self._attrs["state"] = "active"
         return server_data
 
diff --git a/tests/functional/api/test_users.py b/tests/functional/api/test_users.py
@@ -3,8 +3,11 @@
 https://docs.gitlab.com/ee/api/users.html
 https://docs.gitlab.com/ee/api/users.html#delete-authentication-identity-from-user
 """
+import pytest
 import requests
 
+import gitlab.exceptions
+
 
 def test_create_user(gl, fixture_dir):
     user = gl.users.create(
@@ -45,19 +48,29 @@ def test_block_user(gl, user):
 
     # unblock again
     result = user.unblock()
-    # Trying to unblock an already blocked user returns False
+    # Trying to unblock an already un-blocked user returns False
     assert result is False
 
 
 def test_ban_user(gl, user):
-    user.ban()
+    result = user.ban()
+    assert result is True
     retrieved_user = gl.users.get(user.id)
     assert retrieved_user.state == "banned"
 
-    user.unban()
+    # ban an already banned user raises an exception
+    with pytest.raises(gitlab.exceptions.GitlabBanError):
+        user.ban()
+
+    result = user.unban()
+    assert result is True
     retrieved_user = gl.users.get(user.id)
     assert retrieved_user.state == "active"
 
+    # unban an already un-banned user raises an exception
+    with pytest.raises(gitlab.exceptions.GitlabUnbanError):
+        user.unban()
+
 
 def test_delete_user(gl, wait_for_sidekiq):
     new_user = gl.users.create(
