feat(jmap): return JMAPCalendarObject from search/get; deduplicate set-response parsing

Author: SashankBhamidi

caldav/jmap/__init__.py

@@ -35,6 +35,8 @@
     JMAPError,
     JMAPMethodError,
 )
+from caldav.jmap.objects.calendar import JMAPCalendar
+from caldav.jmap.objects.calendar_object import JMAPCalendarObject
 
 _JMAP_KEYS = {"url", "username", "password", "auth", "auth_type", "timeout"}
 
@@ -95,4 +97,6 @@ def get_async_jmap_client(**kwargs) -> AsyncJMAPClient | None:
     "JMAPCapabilityError",
     "JMAPAuthError",
     "JMAPMethodError",
+    "JMAPCalendar",
+    "JMAPCalendarObject",
 ]

caldav/jmap/_methods/__init__.py

@@ -0,0 +1,12 @@
+def parse_set_response(response_args: dict) -> tuple[dict, dict, list[str], dict, dict, dict]:
+    """Parse the arguments dict from any JMAP ``*/set`` method response.
+
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    """
+    created: dict = response_args.get("created") or {}
+    updated: dict = response_args.get("updated") or {}
+    destroyed: list[str] = response_args.get("destroyed") or []
+    not_created: dict = response_args.get("notCreated") or {}
+    not_updated: dict = response_args.get("notUpdated") or {}
+    not_destroyed: dict = response_args.get("notDestroyed") or {}
+    return created, updated, destroyed, not_created, not_updated, not_destroyed

caldav/jmap/_methods/event.py

@@ -12,6 +12,8 @@
 
 from __future__ import annotations
 
+from caldav.jmap._methods import parse_set_response
+
 
 def build_event_get(
     account_id: str,
@@ -260,24 +262,7 @@ def parse_event_set(
 ) -> tuple[dict, dict, list[str], dict, dict, dict]:
     """Parse the arguments dict from a ``CalendarEvent/set`` method response.
 
-    Args:
-        response_args: The second element of a ``methodResponses`` entry
-            whose method name is ``"CalendarEvent/set"``.
-
-    Returns:
-        A 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``:
-
-        - ``created``: Map of creation ID → server-assigned event dict.
-        - ``updated``: Map of event ID → null or partial server-updated object.
-        - ``destroyed``: List of successfully destroyed event IDs.
-        - ``not_created``: Map of creation ID → SetError dict for failed creates.
-        - ``not_updated``: Map of event ID → SetError dict for failed updates.
-        - ``not_destroyed``: Map of event ID → SetError dict for failed destroys.
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    See :func:`caldav.jmap._methods.parse_set_response` for field semantics.
     """
-    created: dict = response_args.get("created") or {}
-    updated: dict = response_args.get("updated") or {}
-    destroyed: list[str] = response_args.get("destroyed") or []
-    not_created: dict = response_args.get("notCreated") or {}
-    not_updated: dict = response_args.get("notUpdated") or {}
-    not_destroyed: dict = response_args.get("notDestroyed") or {}
-    return created, updated, destroyed, not_created, not_updated, not_destroyed
+    return parse_set_response(response_args)

caldav/jmap/_methods/task.py

@@ -11,6 +11,8 @@
 
 from __future__ import annotations
 
+from caldav.jmap._methods import parse_set_response
+
 
 def build_task_list_get(
     account_id: str,
@@ -151,24 +153,7 @@ def parse_task_set(
 ) -> tuple[dict, dict, list[str], dict, dict, dict]:
     """Parse the arguments dict from a ``Task/set`` method response.
 
-    Args:
-        response_args: The second element of a ``methodResponses`` entry
-            whose method name is ``"Task/set"``.
-
-    Returns:
-        A 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``:
-
-        - ``created``: Map of creation ID → server-assigned task dict.
-        - ``updated``: Map of task ID → null or partial server-updated object.
-        - ``destroyed``: List of successfully destroyed task IDs.
-        - ``not_created``: Map of creation ID → SetError dict for failed creates.
-        - ``not_updated``: Map of task ID → SetError dict for failed updates.
-        - ``not_destroyed``: Map of task ID → SetError dict for failed destroys.
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    See :func:`caldav.jmap._methods.parse_set_response` for field semantics.
     """
-    created: dict = response_args.get("created") or {}
-    updated: dict = response_args.get("updated") or {}
-    destroyed: list[str] = response_args.get("destroyed") or []
-    not_created: dict = response_args.get("notCreated") or {}
-    not_updated: dict = response_args.get("notUpdated") or {}
-    not_destroyed: dict = response_args.get("notDestroyed") or {}
-    return created, updated, destroyed, not_created, not_updated, not_destroyed
+    return parse_set_response(response_args)

caldav/jmap/async_client.py

@@ -10,14 +10,12 @@
 import logging
 import uuid
 
-import icalendar
 from niquests import AsyncSession
 
 from caldav.jmap._methods.calendar import build_calendar_get, parse_calendar_get
 from caldav.jmap._methods.event import (
     build_event_changes,
     build_event_get,
-    build_event_query,
     build_event_set_destroy,
     build_event_set_update,
     parse_event_changes,
@@ -33,9 +31,10 @@
     parse_task_set,
 )
 from caldav.jmap.client import _DEFAULT_USING, _TASK_USING, _JMAPClientBase
-from caldav.jmap.convert import ical_to_jscal, jscal_to_ical
+from caldav.jmap.convert import ical_to_jscal
 from caldav.jmap.error import JMAPAuthError, JMAPMethodError
 from caldav.jmap.objects.calendar import JMAPCalendar
+from caldav.jmap.objects.calendar_object import JMAPCalendarObject
 from caldav.jmap.session import Session, async_fetch_session
 
 log = logging.getLogger("caldav.jmap")
@@ -188,14 +187,17 @@ async def create_event(self, calendar_id: str, ical_str: str) -> str:
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
 
-    async def get_event(self, event_id: str) -> str:
+    async def get_event(self, event_id: str) -> JMAPCalendarObject:
         """Fetch a calendar event as an iCalendar string.
 
         Args:
             event_id: The JMAP event ID to retrieve.
 
         Returns:
-            A VCALENDAR string for the event.
+            A :class:`~caldav.jmap.objects.calendar_object.JMAPCalendarObject`
+            wrapping the raw JSCalendar dict.  ``parent`` is ``None`` since
+            no :class:`~caldav.jmap.objects.calendar.JMAPCalendar` is available
+            at the client level.
 
         Raises:
             JMAPMethodError: If the event is not found.
@@ -213,7 +215,7 @@ async def get_event(self, event_id: str) -> str:
                         reason=f"Event not found: {event_id}",
                         error_type="notFound",
                     )
-                return jscal_to_ical(items[0])
+                return JMAPCalendarObject(data=items[0], parent=None)
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/get response")
 
@@ -248,36 +250,18 @@ async def _search(
         start: str | None = None,
         end: str | None = None,
         text: str | None = None,
-    ) -> list[str]:
+        parent: JMAPCalendar | None = None,
+    ) -> list[JMAPCalendarObject]:
         session = await self._get_session()
-        filter_dict: dict = {}
-        if calendar_id is not None:
-            filter_dict["inCalendars"] = [calendar_id]
-        if start is not None:
-            filter_dict["after"] = start
-        if end is not None:
-            filter_dict["before"] = end
-        if text is not None:
-            filter_dict["text"] = text
-
-        query_call = build_event_query(session.account_id, filter=filter_dict or None)
-        get_call = (
-            "CalendarEvent/get",
-            {
-                "accountId": session.account_id,
-                "#ids": {
-                    "resultOf": "ev-query-0",
-                    "name": "CalendarEvent/query",
-                    "path": "/ids",
-                },
-            },
-            "ev-get-1",
-        )
-        responses = await self._request([query_call, get_call])
+        calls = self._build_event_search_calls(session.account_id, calendar_id, start, end, text)
+        responses = await self._request(calls)
 
         for method_name, resp_args, _ in responses:
             if method_name == "CalendarEvent/get":
-                return [jscal_to_ical(item) for item in resp_args.get("list", [])]
+                return [
+                    JMAPCalendarObject(data=item, parent=parent)
+                    for item in resp_args.get("list", [])
+                ]
 
         return []
 
@@ -287,8 +271,8 @@ async def search_events(
         start: str | None = None,
         end: str | None = None,
         text: str | None = None,
-    ) -> list[str]:
-        """Search for calendar events and return them as iCalendar strings.
+    ) -> list[JMAPCalendarObject]:
+        """Search for calendar events.
 
         All parameters are optional; omitting all returns every event in the account.
         Results are fetched in a single batched JMAP request using a result reference
@@ -301,7 +285,9 @@ async def search_events(
             text: Free-text search across title, description, locations, and participants.
 
         Returns:
-            List of VCALENDAR strings for all matching events.
+            List of :class:`~caldav.jmap.objects.calendar_object.JMAPCalendarObject`
+            instances.  ``parent`` is ``None`` on these objects; use
+            :meth:`JMAPCalendar.search` if you need ``parent`` set.
         """
         return await self._search(calendar_id=calendar_id, start=start, end=end, text=text)
 
@@ -325,13 +311,14 @@ async def get_sync_token(self) -> str:
 
     async def get_objects_by_sync_token(
         self, sync_token: str
-    ) -> tuple[list[str], list[str], list[str]]:
+    ) -> tuple[list[JMAPCalendarObject], list[JMAPCalendarObject], list[str]]:
         """Fetch events changed since a previous sync token.
 
         Calls ``CalendarEvent/changes`` to discover which events were created,
         modified, or destroyed since ``sync_token`` was issued. Created and
-        modified events are returned as iCalendar strings; destroyed events are
-        returned as IDs (the objects no longer exist on the server).
+        modified events are returned as
+        :class:`~caldav.jmap.objects.calendar_object.JMAPCalendarObject` instances;
+        destroyed events are returned as IDs (the objects no longer exist on the server).
 
         Args:
             sync_token: A state string previously returned by :meth:`get_sync_token`
@@ -340,8 +327,8 @@ async def get_objects_by_sync_token(
         Returns:
             A 3-tuple ``(added, modified, deleted)``:
 
-            - ``added``: iCalendar strings for newly created events.
-            - ``modified``: iCalendar strings for updated events.
+            - ``added``: objects for newly created events (``parent`` is ``None``).
+            - ``modified``: objects for updated events (``parent`` is ``None``).
             - ``deleted``: Event IDs that were destroyed.
 
         Raises:
@@ -376,11 +363,11 @@ async def get_objects_by_sync_token(
         get_call = build_event_get(session.account_id, ids=fetch_ids)
         get_responses = await self._request([get_call])
 
-        events_by_id: dict[str, str] = {}
+        events_by_id: dict[str, JMAPCalendarObject] = {}
         for method_name, resp_args, _ in get_responses:
             if method_name == "CalendarEvent/get":
                 for item in resp_args.get("list", []):
-                    events_by_id[item["id"]] = jscal_to_ical(item)
+                    events_by_id[item["id"]] = JMAPCalendarObject(data=item, parent=None)
 
         added = [events_by_id[i] for i in created_ids if i in events_by_id]
         modified = [events_by_id[i] for i in updated_ids if i in events_by_id]
@@ -408,19 +395,12 @@ async def delete_event(self, event_id: str) -> None:
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
 
-    async def _get_object_by_uid(self, uid: str, calendar_id: str | None = None) -> str:
-        for event_ical in await self._search(calendar_id=calendar_id):
-            try:
-                cal = icalendar.Calendar.from_ical(event_ical)
-                for component in cal.walk():
-                    if component.name in ("VEVENT", "VTODO", "VJOURNAL"):
-                        component_uid = component.get("UID")
-                        if component_uid is not None and str(component_uid) == uid:
-                            return event_ical
-            except ValueError:
-                log.debug("Skipping unparseable iCalendar string during UID lookup")
-                continue
-
+    async def _get_object_by_uid(
+        self, uid: str, calendar_id: str | None = None, parent: JMAPCalendar | None = None
+    ) -> JMAPCalendarObject:
+        for obj in await self._search(calendar_id=calendar_id, parent=parent):
+            if obj.data.get("uid") == uid:
+                return obj
         session = await self._get_session()
         raise JMAPMethodError(
             url=session.api_url, reason=f"No calendar object found with UID: {uid}"