add dataclass docstring; turn filter_by_state to be required; edit test

Author: Lingling Peng

synapseclient/models/form.py

@@ -21,6 +21,8 @@
 @dataclass
 @async_to_sync
 class FormGroup(FormGroupMixin, FormGroupProtocol):
+    """Dataclass representing a FormGroup."""
+
     async def create_async(
         self,
         *,
@@ -68,9 +70,11 @@ async def create_my_form_group():
 @dataclass
 @async_to_sync
 class FormData(FormDataMixin, FormDataProtocol):
+    """Dataclass representing a FormData."""
+
     def _validate_filter_by_state(
         self,
-        filter_by_state: Optional[List["StateEnum"]] = None,
+        filter_by_state: List["StateEnum"],
         allow_waiting_submission: bool = True,
     ) -> None:
         """
@@ -79,13 +83,7 @@ def _validate_filter_by_state(
         Arguments:
             filter_by_state: List of StateEnum values to validate.
             allow_waiting_submission: If False, raises error if WAITING_FOR_SUBMISSION is present.
-
-        Raises:
-            ValueError: If filter_by_state is empty or contains invalid values.
         """
-        if not filter_by_state:
-            raise ValueError("filter_by_state cannot be None or empty.")
-
         # Define valid states based on whether WAITING_FOR_SUBMISSION is allowed
         valid_states = {
             StateEnum.SUBMITTED_WAITING_FOR_REVIEW,
@@ -179,16 +177,15 @@ async def create_my_form_data():
     async def list_async(
         self,
         *,
+        filter_by_state: List["StateEnum"],
         synapse_client: Optional["Synapse"] = None,
-        filter_by_state: Optional[List["StateEnum"]] = None,
         as_reviewer: bool = False,
     ) -> AsyncGenerator["FormData", None]:
         """
         List FormData objects in a FormGroup.
 
         Arguments:
-            synapse_client: The Synapse client to use for the request.
-            filter_by_state: Optional list of StateEnum to filter the results.
+            filter_by_state: list of StateEnum to filter the results.
                 When as_reviewer=False (default), valid values are:
                 - StateEnum.WAITING_FOR_SUBMISSION
                 - StateEnum.SUBMITTED_WAITING_FOR_REVIEW
@@ -200,6 +197,7 @@ async def list_async(
                 - StateEnum.ACCEPTED
                 - StateEnum.REJECTED
                 Note: WAITING_FOR_SUBMISSION is NOT allowed when as_reviewer=True.
+            synapse_client: The Synapse client to use for the request.
 
             as_reviewer: If True, uses the reviewer endpoint (requires READ_PRIVATE_SUBMISSION
                 permission). If False (default), lists only FormData owned by the caller.
@@ -286,15 +284,14 @@ async def list_for_review():
     def list(
         self,
         *,
+        filter_by_state: List["StateEnum"],
         synapse_client: Optional["Synapse"] = None,
-        filter_by_state: Optional[List["StateEnum"]] = None,
         as_reviewer: bool = False,
     ) -> Generator["FormData", None, None]:
         """
         List FormData objects in a FormGroup.
 
         Arguments:
-            synapse_client: The Synapse client to use for the request.
             filter_by_state: Optional list of StateEnum to filter the results.
                 When as_reviewer=False (default), valid values are:
                 - StateEnum.WAITING_FOR_SUBMISSION
@@ -310,6 +307,7 @@ def list(
 
             as_reviewer: If True, uses the reviewer endpoint (requires READ_PRIVATE_SUBMISSION
                 permission). If False (default), lists only FormData owned by the caller.
+            synapse_client: The Synapse client to use for the request.
 
         Yields:
             FormData objects matching the request.

synapseclient/models/mixins/form.py

@@ -5,6 +5,8 @@
 
 @dataclass
 class FormGroup:
+    """Dataclass representing a FormGroup.s"""
+
     group_id: Optional[str] = None
     """Unique identifier provided by the system."""
 
@@ -29,6 +31,8 @@ def fill_from_dict(self, synapse_response: dict[str, Any]) -> "FormGroup":
 
 @dataclass
 class FormChangeRequest:
+    """Dataclass representing a FormChangeRequest."""
+
     name: Optional[str] = None
     """The name of the form. Required for FormData create. Optional for FormData update. Between 3 and 256 characters"""
 

tests/unit/synapseclient/models/async/unit_test_form_async.py

@@ -222,10 +222,8 @@ async def mock_generator():
     @pytest.mark.parametrize(
         "as_reviewer,filter_by_state, expected",
         [
-            # Test for non-reviewers - empty filter
-            (False, [], ValueError),
-            # Test for reviewers - empty filter
-            (True, [], ValueError),
+            # Test for non-reviewers - WAITING_FOR_SUBMISSION is allowed
+            (False, [StateEnum.WAITING_FOR_SUBMISSION, StateEnum.ACCEPTED], None),
             # Test for reviewers - invalid state filter
             (True, [StateEnum.WAITING_FOR_SUBMISSION], ValueError),
         ],

tests/unit/synapseclient/models/synchronous/unit_test_form.py

@@ -220,10 +220,8 @@ async def mock_generator():
     @pytest.mark.parametrize(
         "as_reviewer,filter_by_state, expected",
         [
-            # Test for non-reviewers - empty filter
-            (False, [], ValueError),
-            # Test for reviewers - empty filter
-            (True, [], ValueError),
+            # Test for non-reviewers - WAITING_FOR_SUBMISSION is allowed
+            (False, [StateEnum.WAITING_FOR_SUBMISSION, StateEnum.ACCEPTED], None),
             # Test for reviewers - invalid state filter
             (True, [StateEnum.WAITING_FOR_SUBMISSION], ValueError),
         ],