feat: implement export_timeline in client (#240)

* feat: implement export_timeline in client

* fix: use enum instead of literal

* fix: use literal from typing_extensions

docs/api_coverage.md

@@ -20,7 +20,7 @@
 | `export_responses`             | Yes         | Export responses in base64 encoded string                                         |
 | `export_responses_by_token`    | Yes         | Export token response in a survey.                                                |
 | `export_statistics`            | Yes         | Export survey statistics (RPC function)                                           |
-| `export_timeline`              | No          | Export submission timeline (RPC function)                                         |
+| `export_timeline`              | Yes         | Export submission timeline (RPC function)                                         |
 | `get_group_properties`         | Yes         | Get the properties of a group of a survey .                                       |
 | `get_language_properties`      | Yes         | Get survey language properties (RPC function)                                     |
 | `get_participant_properties`   | Yes         | Get settings of a survey participant (RPC function)                               |

src/citric/client.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import base64
+import datetime
+import sys
 from os import PathLike
 from pathlib import Path
 from types import TracebackType
@@ -13,6 +15,12 @@
 from citric import enums
 from citric.session import Session
 
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+
 _T = TypeVar("_T", bound="Client")
 
 
@@ -485,6 +493,31 @@ def save_statistics(
                 )
             )
 
+    def export_timeline(
+        self,
+        survey_id: int,
+        period: Literal["day", "hour"],
+        start: datetime.datetime,
+        end: datetime.datetime | None = None,
+    ) -> dict[str, int]:
+        """Export survey submission timeline.
+
+        Args:
+            survey_id: ID of the Survey.
+            period: Granularity level for aggregation submission counts.
+            start: Start datetime.
+            end: End datetime.
+
+        Returns:
+            Mapping of days/hours to submission counts.
+        """
+        return self.session.export_timeline(
+            survey_id,
+            enums.TimelineAggregationPeriod(period),
+            start.isoformat(),
+            end.isoformat() if end else datetime.datetime.utcnow().isoformat(),
+        )
+
     def get_group_properties(
         self,
         group_id: int,

src/citric/enums.py

@@ -68,3 +68,10 @@ class ResponseType(str, enum.Enum):
 
     LONG = "long"
     SHORT = "short"
+
+
+class TimelineAggregationPeriod(str, enum.Enum):
+    """Timeline aggregation level."""
+
+    HOUR = "hour"
+    DAY = "day"

tests/test_client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import base64
+import datetime
 import random
 import sys
 from pathlib import Path
@@ -109,6 +110,10 @@ def export_statistics(self, *args: Any) -> bytes:
         """Mock statistics file content."""
         return base64.b64encode(b"FILE CONTENTS")
 
+    def export_timeline(self, *args: Any) -> dict[str, int]:
+        """Mock submission timeline."""
+        return {"2022-01-01": 4, "2022-01-02": 2}
+
     def get_site_settings(self, setting_name: str) -> str:
         """Return the setting value or an empty string."""
         return self.settings.get(setting_name, "")
@@ -326,6 +331,14 @@ def test_delete_participants(client: MockClient):
     assert_client_session_call(client, "delete_participants", 1, participants)
 
 
+def test_export_timeline(client: MockClient):
+    """Test export_timeline client method."""
+    assert client.export_timeline(1, "hour", datetime.datetime(2020, 1, 1)) == {
+        "2022-01-01": 4,
+        "2022-01-02": 2,
+    }
+
+
 def test_participant_properties(client: MockClient):
     """Test get_participant_properties client method."""
     assert_client_session_call(client, "get_participant_properties", 1, 1, None)