refactor: return typed role assignemnts for easier management

Author: mariajgrimaldi

openedx_authz/api/roles.py

@@ -34,7 +34,7 @@
     "unassign_role_from_subject_in_scope",
     "batch_unassign_role_from_subjects_in_scope",
     "get_subject_role_assignments_in_scope",
-    "get_role_assignments_for_role_in_scope",
+    "get_subjects_role_assignments_for_role_in_scope",
     "get_subject_role_assignments",
 ]
 
@@ -293,7 +293,7 @@ def get_subject_role_assignments_in_scope(
     return role_assignments
 
 
-def get_role_assignments_for_role_in_scope(
+def get_subjects_role_assignments_for_role_in_scope(
     role: RoleData, scope: ScopeData
 ) -> list[RoleAssignmentData]:
     """Get the subjects assigned to a specific role in a specific scope.
@@ -307,7 +307,7 @@ def get_role_assignments_for_role_in_scope(
     """
     role_assignments = []
     for subject in enforcer.get_users_for_role_in_domain(role.role_id, scope.scope_id):
-        if subject.startswith("role@"):
+        if subject.startswith(RoleData.NAMESPACE):
             # Skip roles that are also subjects
             continue
         role_assignments.append(

openedx_authz/api/users.py

@@ -9,13 +9,14 @@
 (e.g., 'user@john_doe').
 """
 
-from openedx_authz.api.data import RoleData, ScopeData, SubjectData, UserData
+from openedx_authz.api.data import RoleAssignmentData, RoleData, ScopeData, SubjectData, UserData
 from openedx_authz.api.roles import (
     assign_role_to_subject_in_scope,
     batch_assign_role_to_subjects_in_scope,
     batch_unassign_role_from_subjects_in_scope,
     get_subject_role_assignments,
     get_subject_role_assignments_in_scope,
+    get_subjects_role_assignments_for_role_in_scope,
     unassign_role_from_subject_in_scope,
 )
 
@@ -29,102 +30,102 @@
 ]
 
 
-def assign_role_to_user_in_scope(username: str, role_name: str, scope_id: str) -> bool:
+def assign_role_to_user_in_scope(username: str, role_name: str, scope: str) -> bool:
     """Assign a role to a user in a specific scope.
 
     Args:
         user (str): ID of the user (e.g., 'john_doe').
         role_name (str): Name of the role to assign.
         scope (str): Scope in which to assign the role.
-
-    Returns:
-        bool: True if the assignment was successful, False otherwise.
     """
-    return assign_role_to_subject_in_scope(
+    assign_role_to_subject_in_scope(
         UserData(username=username),
         RoleData(name=role_name),
-        ScopeData(scope_id=scope_id),
+        ScopeData(name=scope),
     )
 
 
 def batch_assign_role_to_users(
-    users: list[str], role_name: str, scope_id: str
+    users: list[str], role_name: str, scope: str
 ) -> dict[str, bool]:
     """Assign a role to multiple users in a specific scope.
 
     Args:
         users (list of str): List of user IDs (e.g., ['john_doe', 'jane_smith']).
         role_name (str): Name of the role to assign.
         scope (str): Scope in which to assign the role.
-
-    Returns:
-        dict: A dictionary mapping user IDs to assignment success status (True/False).
     """
     namespaced_users = [UserData(username=username) for username in users]
-    return batch_assign_role_to_subjects_in_scope(
-        namespaced_users, RoleData(name=role_name), ScopeData(scope_id=scope_id)
+    batch_assign_role_to_subjects_in_scope(
+        namespaced_users, RoleData(name=role_name), ScopeData(name=scope)
     )
 
 
-def unassign_role_from_user(user: str, role_name: str, scope_id: str) -> bool:
+def unassign_role_from_user(user: str, role_name: str, scope: str) -> bool:
     """Unassign a role from a user in a specific scope.
 
     Args:
         user (str): ID of the user (e.g., 'john_doe').
         role_name (str): Name of the role to unassign.
         scope (str): Scope in which to unassign the role.
-
-    Returns:
-        bool: True if the unassignment was successful, False otherwise.
     """
-    return unassign_role_from_subject_in_scope(
+    unassign_role_from_subject_in_scope(
         UserData(username=user),
         RoleData(name=role_name),
-        ScopeData(scope_id=scope_id),
+        ScopeData(name=scope),
     )
 
 
 def batch_unassign_role_from_users(
-    users: list[str], role_name: str, scope_id: str
+    users: list[str], role_name: str, scope: str
 ) -> dict[str, bool]:
     """Unassign a role from multiple users in a specific scope.
 
     Args:
         users (list of str): List of user IDs (e.g., ['john_doe', 'jane_smith']).
         role_name (str): Name of the role to unassign.
         scope (str): Scope in which to unassign the role.
-
-    Returns:
-        dict: A dictionary mapping user IDs to unassignment success status (True/False).
     """
     namespaced_users = [UserData(username=user) for user in users]
-    return batch_unassign_role_from_subjects_in_scope(
-        namespaced_users, RoleData(name=role_name), ScopeData(scope_id=scope_id)
+    batch_unassign_role_from_subjects_in_scope(
+        namespaced_users, RoleData(name=role_name), ScopeData(name=scope)
     )
 
 
-def get_user_role_assignments(username: str) -> list[dict]:
+def get_user_role_assignments(username: str) -> list[RoleAssignmentData]:
     """Get all roles for a user across all scopes.
 
     Args:
         user (str): ID of the user (e.g., 'john_doe').
 
     Returns:
-        list[dict]: A list of role names and all their metadata assigned to the user.
+        list[dict]: A list of role assignments and all their metadata assigned to the user.
     """
     return get_subject_role_assignments(UserData(username=username))
 
 
-def get_user_role_assignments_in_scope(username: str, scope_id: str) -> list[str]:
+def get_user_role_assignments_in_scope(username: str, scope: str) -> list[RoleAssignmentData]:
     """Get the roles assigned to a user in a specific scope.
 
     Args:
         user (str): ID of the user (e.g., 'john_doe').
         scope (str): Scope in which to retrieve the roles.
 
     Returns:
-        list: A list of role names assigned to the user in the specified scope.
+        list: A list of role assignments assigned to the user in the specified scope.
     """
     return get_subject_role_assignments_in_scope(
-        UserData(username=username), ScopeData(scope_id=scope_id)
+        UserData(username=username), ScopeData(name=scope)
     )
+
+def get_user_role_assignments_for_role_in_scope(role_name:str, scope:str) -> list[RoleAssignmentData]:
+    """Get all users assigned to a specific role across all scopes.
+
+    Args:
+        role_name (str): Name of the role (e.g., 'instructor').
+        scope (str): Scope in which to retrieve the role assignments.
+
+    Returns:
+        list[dict]: A list of user names and all their metadata assigned to the role.
+    """
+    return get_subjects_role_assignments_for_role_in_scope(RoleData(name=role_name), ScopeData(name=scope))

openedx_authz/tests/api/test_roles.py

@@ -851,7 +851,7 @@ def test_get_role_assignments_in_scope(self, role_name, scope_name, expected_cou
         Expected result:
             - The number of role assignments in the given scope is correctly retrieved.
         """
-        role_assignments = get_role_assignments_for_role_in_scope(
+        role_assignments = get_subject_role_assignments_for_role_in_scope(
             RoleData(name=role_name), ScopeData(name=scope_name)
         )