Improve arguments description

Author: harminius

mergin/client.py

@@ -17,6 +17,8 @@
 import typing
 import warnings
 
+from typing import List
+
 from .common import ClientError, LoginError, WorkspaceRole, ProjectRole
 from .merginproject import MerginProject
 from .client_pull import (
@@ -1243,9 +1245,16 @@ def create_user(
         workspace_role: WorkspaceRole,
         username: str = None,
         notify_user: bool = False,
-    ):
+    ) -> dict:
         """
         Create a new user in a workspace. The username is generated from the email address.
+
+        param email: email of the new user - must be unique
+        param password: password - must meet the requirements
+        param workspace_id: id of the workspace user is created in
+        param workspace_role: workspace role of the user
+        param username: username - will be autogenerated from the email if not provided
+        param notify_user: flag for email notifications - confirmation email will be sent
         """
         params = {
             "email": email,
@@ -1256,16 +1265,17 @@ def create_user(
         }
         if username:
             params["username"] = username
-        self.post("v2/users", params, json_headers)
+        user_info = self.post("v2/users", params, json_headers)
+        return json.load(user_info)
 
-    def get_workspace_member(self, workspace_id: int, user_id: int):
+    def get_workspace_member(self, workspace_id: int, user_id: int) -> dict:
         """
         Get a workspace member detail
         """
         resp = self.get(f"v2/workspaces/{workspace_id}/members/{user_id}")
         return json.load(resp)
 
-    def list_workspace_members(self, workspace_id: int):
+    def list_workspace_members(self, workspace_id: int) -> List[dict]:
         """
         Get a list of workspace members
         """
@@ -1274,41 +1284,47 @@ def list_workspace_members(self, workspace_id: int):
 
     def update_workspace_member(
         self, workspace_id: int, user_id: int, workspace_role: WorkspaceRole, reset_projects_roles: bool = False
-    ):
+    ) -> dict:
         """
         Update workspace role of a workspace member, optionally resets the projects role
+
+        param reset_projects_roles: all project specific roles will be removed
         """
         params = {
             "reset_projects_roles": reset_projects_roles,
             "workspace_role": workspace_role.value,
         }
-        resp = self.patch(f"v2/workspaces/{workspace_id}/members/{user_id}", params, json_headers)
-        return json.load(resp)
+        workspace_member = self.patch(f"v2/workspaces/{workspace_id}/members/{user_id}", params, json_headers)
+        return json.load(workspace_member)
 
     def remove_workspace_member(self, workspace_id: int, user_id: int):
         """
         Remove a user from workspace members
         """
         self.delete(f"v2/workspaces/{workspace_id}/members/{user_id}")
 
-    def list_project_collaborators(self, project_id: int):
+    def list_project_collaborators(self, project_id: int) -> List[dict]:
         """
         Get a list of project collaborators
         """
         project_collaborators = self.get(f"v2/projects/{project_id}/collaborators")
         return json.load(project_collaborators)
 
-    def add_project_collaborator(self, project_id: int, user: str, project_role: ProjectRole):
+    def add_project_collaborator(self, project_id: int, user: str, project_role: ProjectRole) -> dict:
         """
-        Add a user to project collaborators and grant them a project role
+        Add a user to project collaborators and grant them a project role.
+        Fails if user is already a member of the project.
+
+        param user: login (username or email) of the user
         """
         params = {"role": project_role.value, "user": user}
         project_collaborator = self.post(f"v2/projects/{project_id}/collaborators", params, json_headers)
         return json.load(project_collaborator)
 
-    def update_project_collaborator(self, project_id: int, user_id: int, project_role: ProjectRole):
+    def update_project_collaborator(self, project_id: int, user_id: int, project_role: ProjectRole) -> dict:
         """
-        Update project role of the existing project collaborator
+        Update project role of the existing project collaborator.
+        Fails if user is not a member of the project yet.
         """
         params = {"role": project_role.value}
         project_collaborator = self.patch(f"v2/projects/{project_id}/collaborators/{user_id}", params, json_headers)

mergin/test/test_client.py

@@ -2752,7 +2752,10 @@ def test_access_management(mc: MerginClient, mc2: MerginClient):
     email = "create_user" + str(random.randint(1000, 9999)) + "@client.py"
     password = "Il0vemergin"
     ws_role = WorkspaceRole.WRITER
-    mc.create_user(email, password, workspace_id, ws_role)
+    user_info = mc.create_user(email, password, workspace_id, ws_role)
+    assert user_info["email"] == email
+    assert user_info["receive_notifications"] is False
+    # list workspace members
     workspace_members = mc.list_workspace_members(workspace_id)
     new_user = next((m for m in workspace_members if m["email"] == email))
     assert new_user