updated list_users for scoring

Author: Narek Mkhitaryan

src/superannotate/lib/app/interface/sdk_interface.py

@@ -460,7 +460,7 @@ def list_users(
         **filters,
     ):
         """
-        Search users by filtering criteria
+        Search users, including their scores, by filtering criteria.
 
         :param project:  Project name or ID, if provided, results will be for project-level,
          otherwise results will be for team level.
@@ -470,8 +470,7 @@ def list_users(
 
             Possible values are
 
-            - "custom_fields": Includes the custom fields assigned to each user.
-        :type include: list of str, optional
+            - "custom_fields":  Includes custom fields and scores assigned to each user.
 
         :param filters: Specifies filtering criteria, with all conditions combined using logical AND.
 
@@ -501,18 +500,35 @@ def list_users(
             - email__contains: str
             - email__starts: str
             - email__ends: str
+
+            Following params if project is not selected::
+
             - state: Literal[“Confirmed”, “Pending”]
             - state__in: List[Literal[“Confirmed”, “Pending”]]
             - role: Literal[“admin”, “contributor”]
             - role__in: List[Literal[“admin”, “contributor”]]
 
-            Custom Fields Filtering:
-                - Custom fields must be prefixed with `custom_field__`.
+            Scores and Custom Field Filtering:
+
+                - Scores and other custom fields must be prefixed with `custom_field__` .
                 - Example: custom_field__Due_date__gte="1738281600" (filtering users whose Due date is after the given Unix timestamp).
 
+            - **Text** custom field only works with the following filter params: __in, __notin, __contains
+            - **Numeric** custom field only works with the following filter params: __in, __notin, __ne, __gt, __gte, __lt, __lte
+            - **Single-select** custom field only works with the following filter params: __in, __notin, __contains
+            - **Multi-select** custom field only works with the following filter params: __in, __notin
+            - **Date picker** custom field only works with the following filter params: __gt, __gte, __lt, __lte
+
+            **If score name has a space, please use the following format to filter them**:
+            ::
+
+                user_filters = {"custom_field__accuracy score 30D__lt": 90}
+                client.list_users(include=["custom_fields"], **user_filters)
+
+
         :type filters: UserFilters, optional
 
-        :return: A list of team users metadata that matches the filtering criteria
+        :return: A list of team/project users metadata that matches the filtering criteria
         :rtype: list of dicts
 
         Request Example:
@@ -543,6 +559,82 @@ def list_users(
                     "team_id": 44311,
                 }
             ]
+
+        Request Example:
+        ::
+
+            # Project level scores
+
+            scores = client.list_users(
+                include=["custom_fields"],
+                project="my_multimodal",
+                email__contains="@superannotate.com",
+                custom_field__speed__gte=90,
+                custom_field__weight__lte=1,
+            )
+
+        Response Example:
+        ::
+
+            # Project level scores
+
+            [
+                {
+                    "createdAt": "2025-03-07T13:19:59.000Z",
+                    "updatedAt": "2025-03-07T13:19:59.000Z",
+                    "custom_fields": {"speed": 92, "weight": 0.8},
+                    "email": "example@superannotate.com",
+                    "id": 715121,
+                    "role": "Annotator",
+                    "state": "Confirmed",
+                    "team_id": 1234,
+                }
+            ]
+
+        Request Example:
+        ::
+
+            # Team level scores
+
+            user_filters = {
+                "custom_field__accuracy score 30D__lt": 95,
+                "custom_field__speed score 7D__lt": 15
+            }
+
+            scores = client.list_users(
+                include=["custom_fields"],
+                email__contains="@superannotate.com",
+                role="Contributor",
+                **user_filters
+            )
+
+        Response Example:
+        ::
+
+            # Team level scores
+
+            [
+                {
+                    "createdAt": "2025-03-07T13:19:59.000Z",
+                    "updatedAt": "2025-03-07T13:19:59.000Z",
+                    "custom_fields": {
+                        "Test custom field": 80,
+                        "Tag custom fields": ["Tag1", "Tag2"],
+                        "accuracy score 30D": 95,
+                        "accuracy score 14D": 47,
+                        "accuracy score 7D": 24,
+                        "speed score 30D": 33,
+                        "speed score 14D": 22,
+                        "speed score 7D": 11,
+                    },
+                    "email": "example@superannotate.com",
+                    "id": 715121,
+                    "role": "Contributor",
+                    "state": "Confirmed",
+                    "team_id": 1234,
+                }
+            ]
+
         """
         if project is not None:
             if isinstance(project, int):

tests/integration/work_management/test_user_custom_fields.py

@@ -149,6 +149,18 @@ def test_list_users(self):
         )[0]
         assert scapegoat["custom_fields"]["SDK_test_date_picker"] == value
 
+        # by date_picker with dict **filters
+        value = round(time.time(), 3)
+        filters = {
+            "email": scapegoat["email"],
+            "custom_field__SDK_test_date_picker": value,
+        }
+        scapegoat = sa.list_users(
+            include=["custom_fields"],
+            **filters,
+        )[0]
+        assert scapegoat["custom_fields"]["SDK_test_date_picker"] == value
+
         # by date_picker None case
         sa.set_user_custom_field(
             scapegoat["email"],

tests/integration/work_management/test_user_scoring.py

@@ -131,6 +131,32 @@ def test_set_get_scores(self):
             assert score["createdAt"]
             assert score["updatedAt"]
 
+    def test_list_users_with_scores(self):
+        # list team users
+        team_users = sa.list_users(include=["custom_fields"])
+        for u in team_users:
+            for s in SCORE_TEMPLATES:
+                try:
+                    assert not u["custom_fields"][f"{s['name']} 7D"]
+                    assert not u["custom_fields"][f"{s['name']} 14D"]
+                    assert not u["custom_fields"][f"{s['name']} 30D"]
+                except KeyError as e:
+                    raise AssertionError(str(e))
+
+        # filter team users by score
+        filters = {f"custom_field__{SCORE_TEMPLATES[0]['name']} 7D": None}
+        team_users = sa.list_users(include=["custom_fields"], **filters)
+        assert team_users
+        for u in team_users:
+            try:
+                assert not u["custom_fields"][f"{SCORE_TEMPLATES[0]['name']} 7D"]
+            except KeyError as e:
+                raise AssertionError(str(e))
+
+        filters = {f"custom_field__{SCORE_TEMPLATES[1]['name']} 30D": 5}
+        team_users = sa.list_users(include=["custom_fields"], **filters)
+        assert not team_users
+
     def test_set_get_scores_negative_cases(self):
         item_name = f"test_item_{uuid.uuid4()}"
         self._attach_item(self.PROJECT_NAME, item_name)