feat(rpc): Added survey group ID input parameter to list_surveys

.changes/unreleased/Added-20241226-180149.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: Added survey group ID input parameter to `list_surveys`
+time: 2024-12-26T18:01:49.207724-06:00
+custom:
+    Issue: "1242"

src/citric/client.py

@@ -878,9 +878,11 @@ def export_timeline(
             survey_id,
             enums.TimelineAggregationPeriod(period),
             start.isoformat(),
-            end.isoformat()
-            if end
-            else datetime.datetime.now(tz=datetime.timezone.utc).isoformat(),
+            (
+                end.isoformat()
+                if end
+                else datetime.datetime.now(tz=datetime.timezone.utc).isoformat()
+            ),
         )
 
     def get_group_properties(
@@ -1486,20 +1488,30 @@ def list_quotas(self, survey_id: int) -> list[types.QuotaListElement]:
         """
         return self.session.list_quotas(survey_id)
 
-    def list_surveys(self, username: str | None = None) -> list[dict[str, t.Any]]:
+    def list_surveys(
+        self,
+        username: str | None = None,
+        *,
+        survey_group_id: int | None = None,
+    ) -> list[dict[str, t.Any]]:
         """Get all surveys or only those owned by a user.
 
         Calls :rpc_method:`list_surveys`.
 
         Args:
             username: Owner of the surveys to retrieve.
+            survey_group_id: ID of the survey group to retrieve surveys from.
 
         Returns:
             List of surveys with basic information.
 
         .. versionadded:: 0.0.1
+           This method.
+
+        .. versionadded:: NEXT_VERSION
+           The *survey_group_id* parameter.
         """
-        return self.session.list_surveys(username)
+        return self.session.list_surveys(username, survey_group_id)
 
     def list_survey_groups(
         self,

tests/integration/test_rpc_client.py

@@ -120,7 +120,11 @@ def test_language(client: citric.Client, survey_id: int, subtests: SubTests):
 
 
 @pytest.mark.integration_test
-def test_survey(client: citric.Client):
+def test_survey(
+    client: citric.Client,
+    server_version: semver.VersionInfo,
+    subtests: SubTests,
+):
     """Test survey methods."""
     # Try to get a survey that doesn't exist
     with pytest.raises(LimeSurveyStatusError, match="Error: Invalid survey"):
@@ -150,6 +154,17 @@ def test_survey(client: citric.Client):
     matched = next(s for s in client.list_surveys() if int(s["sid"]) == survey_id)
     assert matched["surveyls_title"] == NEW_SURVEY_NAME
 
+    with subtests.test(msg="survey group ID"):
+        if server_version < (6, 8, 3):
+            pytest.xfail(
+                "The gsid field is not available as input nor output of the RPC "
+                "list_surveys method in LimeSurvey < 6.8.3"
+            )
+
+        gsid = matched["gsid"]
+        surveys_in_group = client.list_surveys(survey_group_id=gsid)
+        assert all(s["gsid"] == gsid for s in surveys_in_group)
+
     # Update survey properties
     response = client.set_survey_properties(
         survey_id,

tests/test_client.py

@@ -291,7 +291,7 @@ def test_list_groups(client: MockClient):
 
 def test_list_surveys(client: MockClient):
     """Test list_surveys client method."""
-    assert_client_session_call(client, "list_surveys", None)
+    assert_client_session_call(client, "list_surveys", None, survey_group_id=None)
 
 
 def test_list_survey_groups(client: MockClient):