feat(jmap): align API with CalDAV v3 — calendar-scoped search/get/add_event

SashankBhamidi · SashankBhamidi · commit bcdc01411b8e · 2026-02-26T16:03:52.000+05:30
diff --git a/caldav/base_client.py b/caldav/base_client.py
@@ -347,6 +347,9 @@ def get_davclient(
     setup_func = conn_params.pop("_setup", None)
     teardown_func = conn_params.pop("_teardown", None)
     server_name = conn_params.pop("_server_name", None)
+    # Remove protocol field — present when config file has both CalDAV and JMAP sections,
+    # or when the caller passes protocol="jmap"/"caldav". DAVClient doesn't accept it.
+    conn_params.pop("protocol", None)
 
     # Create client
     client = client_class(**conn_params)
diff --git a/caldav/config.py b/caldav/config.py
@@ -179,6 +179,7 @@ def replacer(match: re.Match) -> str:
         "features",
         "enable_rfc6764",
         "require_tls",
+        "protocol",
     ]
 )
 
diff --git a/caldav/jmap/async_client.py b/caldav/jmap/async_client.py
@@ -10,6 +10,7 @@
 import logging
 import uuid
 
+import icalendar
 from niquests import AsyncSession
 
 from caldav.jmap.client import _DEFAULT_USING, _TASK_USING, _JMAPClientBase
@@ -144,7 +145,11 @@ async def get_calendars(self) -> list[JMAPCalendar]:
 
         for method_name, resp_args, _ in responses:
             if method_name == "Calendar/get":
-                return parse_calendar_get(resp_args)
+                calendars = parse_calendar_get(resp_args)
+                for cal in calendars:
+                    cal._client = self
+                    cal._is_async = True
+                return calendars
 
         return []
 
@@ -238,28 +243,13 @@ async def update_event(self, event_id: str, ical_str: str) -> None:
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
 
-    async def search_events(
+    async def _search(
         self,
         calendar_id: str | None = None,
         start: str | None = None,
         end: str | None = None,
         text: str | None = None,
     ) -> list[str]:
-        """Search for calendar events and return them as iCalendar strings.
-
-        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
-        from ``CalendarEvent/query`` into ``CalendarEvent/get``.
-
-        Args:
-            calendar_id: Limit results to this calendar.
-            start: Only events ending after this datetime (``YYYY-MM-DDTHH:MM:SS``).
-            end: Only events starting before this datetime (``YYYY-MM-DDTHH:MM:SS``).
-            text: Free-text search across title, description, locations, and participants.
-
-        Returns:
-            List of VCALENDAR strings for all matching events.
-        """
         session = await self._get_session()
         filter_dict: dict = {}
         if calendar_id is not None:
@@ -292,6 +282,30 @@ async def search_events(
 
         return []
 
+    async def search_events(
+        self,
+        calendar_id: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        text: str | None = None,
+    ) -> list[str]:
+        """Search for calendar events and return them as iCalendar strings.
+
+        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
+        from ``CalendarEvent/query`` into ``CalendarEvent/get``.
+
+        Args:
+            calendar_id: Limit results to this calendar.
+            start: Only events ending after this datetime (``YYYY-MM-DDTHH:MM:SS``).
+            end: Only events starting before this datetime (``YYYY-MM-DDTHH:MM:SS``).
+            text: Free-text search across title, description, locations, and participants.
+
+        Returns:
+            List of VCALENDAR strings for all matching events.
+        """
+        return await self._search(calendar_id=calendar_id, start=start, end=end, text=text)
+
     async def get_sync_token(self) -> str:
         """Return the current CalendarEvent state string for use as a sync token.
 
@@ -395,6 +409,24 @@ 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
+
+        session = await self._get_session()
+        raise JMAPMethodError(
+            url=session.api_url, reason=f"No calendar object found with UID: {uid}"
+        )
+
     async def get_task_lists(self) -> list[JMAPTaskList]:
         """Fetch all task lists for the authenticated account.
 
diff --git a/caldav/jmap/client.py b/caldav/jmap/client.py
@@ -20,6 +20,8 @@
     import requests  # type: ignore[no-redef]
     from requests.auth import HTTPBasicAuth  # type: ignore[no-redef]
 
+import icalendar
+
 from caldav.jmap.constants import CALENDAR_CAPABILITY, CORE_CAPABILITY, TASK_CAPABILITY
 from caldav.jmap.convert import ical_to_jscal, jscal_to_ical
 from caldav.jmap.error import JMAPAuthError, JMAPMethodError
@@ -223,7 +225,11 @@ def get_calendars(self) -> list[JMAPCalendar]:
 
         for method_name, resp_args, _ in responses:
             if method_name == "Calendar/get":
-                return parse_calendar_get(resp_args)
+                calendars = parse_calendar_get(resp_args)
+                for cal in calendars:
+                    cal._client = self
+                    cal._is_async = False
+                return calendars
 
         return []
 
@@ -317,28 +323,13 @@ def update_event(self, event_id: str, ical_str: str) -> None:
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
 
-    def search_events(
+    def _search(
         self,
         calendar_id: str | None = None,
         start: str | None = None,
         end: str | None = None,
         text: str | None = None,
     ) -> list[str]:
-        """Search for calendar events and return them as iCalendar strings.
-
-        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
-        from ``CalendarEvent/query`` into ``CalendarEvent/get``.
-
-        Args:
-            calendar_id: Limit results to this calendar.
-            start: Only events ending after this datetime (``YYYY-MM-DDTHH:MM:SS``).
-            end: Only events starting before this datetime (``YYYY-MM-DDTHH:MM:SS``).
-            text: Free-text search across title, description, locations, and participants.
-
-        Returns:
-            List of VCALENDAR strings for all matching events.
-        """
         session = self._get_session()
         filter_dict: dict = {}
         if calendar_id is not None:
@@ -371,6 +362,30 @@ def search_events(
 
         return []
 
+    def search_events(
+        self,
+        calendar_id: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        text: str | None = None,
+    ) -> list[str]:
+        """Search for calendar events and return them as iCalendar strings.
+
+        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
+        from ``CalendarEvent/query`` into ``CalendarEvent/get``.
+
+        Args:
+            calendar_id: Limit results to this calendar.
+            start: Only events ending after this datetime (``YYYY-MM-DDTHH:MM:SS``).
+            end: Only events starting before this datetime (``YYYY-MM-DDTHH:MM:SS``).
+            text: Free-text search across title, description, locations, and participants.
+
+        Returns:
+            List of VCALENDAR strings for all matching events.
+        """
+        return self._search(calendar_id=calendar_id, start=start, end=end, text=text)
+
     def get_sync_token(self) -> str:
         """Return the current CalendarEvent state string for use as a sync token.
 
@@ -472,6 +487,23 @@ def delete_event(self, event_id: str) -> None:
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
 
+    def _get_object_by_uid(self, uid: str, calendar_id: str | None = None) -> str:
+        for event_ical in 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
+
+        raise JMAPMethodError(
+            url=self._get_session().api_url, reason=f"No calendar object found with UID: {uid}"
+        )
+
     def get_task_lists(self) -> list[JMAPTaskList]:
         """Fetch all task lists for the authenticated account.
 
diff --git a/caldav/jmap/objects/calendar.py b/caldav/jmap/objects/calendar.py
@@ -8,6 +8,12 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from caldav.jmap.async_client import AsyncJMAPClient
+    from caldav.jmap.client import JMAPClient
 
 
 @dataclass
@@ -34,6 +40,12 @@ class JMAPCalendar:
     sort_order: int = 0
     is_visible: bool = True
 
+    # Injected by JMAPClient.get_calendars() / AsyncJMAPClient.get_calendars()
+    _client: JMAPClient | AsyncJMAPClient | None = field(
+        default=None, init=False, repr=False, compare=False
+    )
+    _is_async: bool = field(default=False, init=False, repr=False, compare=False)
+
     @classmethod
     def from_jmap(cls, data: dict) -> JMAPCalendar:
         """Construct a JMAPCalendar from a raw JMAP Calendar JSON dict.
@@ -70,3 +82,103 @@ def to_jmap(self) -> dict:
         if self.color is not None:
             d["color"] = self.color
         return d
+
+    def search(self, **searchargs) -> list[str]:
+        """Search for calendar objects and return them as iCalendar strings.
+
+        Mirrors :meth:`caldav.collection.Calendar.search`. When called on an
+        async-backed calendar, returns a coroutine that must be awaited.
+
+        Accepted keyword arguments (all optional):
+
+        - ``event`` (bool): search for events (VEVENT components).
+        - ``todo`` (bool): search for tasks (VTODO). Note: requires server
+          JMAP Task capability; raises :class:`NotImplementedError` if absent.
+        - ``start`` (datetime or str): only events ending after this time
+          (maps to JMAP ``after`` filter).
+        - ``end`` (datetime or str): only events starting before this time
+          (maps to JMAP ``before`` filter).
+        - ``text`` (str): free-text search across title, description,
+          locations, and participants.
+
+        Unknown searchargs keys are silently ignored for forward compatibility.
+
+        Returns:
+            List of VCALENDAR strings for all matching objects.
+        """
+        if self._is_async:
+            return self._async_search(**searchargs)
+        start = searchargs.get("start")
+        end = searchargs.get("end")
+        if isinstance(start, datetime):
+            start = start.isoformat()
+        if isinstance(end, datetime):
+            end = end.isoformat()
+        return self._client._search(
+            calendar_id=self.id,
+            start=start,
+            end=end,
+            text=searchargs.get("text"),
+        )
+
+    async def _async_search(self, **searchargs) -> list[str]:
+        start = searchargs.get("start")
+        end = searchargs.get("end")
+        if isinstance(start, datetime):
+            start = start.isoformat()
+        if isinstance(end, datetime):
+            end = end.isoformat()
+        return await self._client._search(
+            calendar_id=self.id,
+            start=start,
+            end=end,
+            text=searchargs.get("text"),
+        )
+
+    def get_object_by_uid(self, uid: str, comp_class=None) -> str:
+        """Get a calendar object by its iCalendar UID.
+
+        Mirrors :meth:`caldav.collection.Calendar.get_object_by_uid`. When
+        called on an async-backed calendar, returns a coroutine that must be
+        awaited.
+
+        Args:
+            uid: The iCalendar UID to search for.
+            comp_class: Accepted for API compatibility with the CalDAV interface;
+                JMAP ``CalendarEvent/query`` has no native component-type filter,
+                so this argument is currently ignored.
+
+        Returns:
+            A VCALENDAR string for the matching object.
+
+        Raises:
+            JMAPMethodError: If no object with this UID is found.
+        """
+        if self._is_async:
+            return self._async_get_object_by_uid(uid)
+        return self._client._get_object_by_uid(uid, calendar_id=self.id)
+
+    async def _async_get_object_by_uid(self, uid: str) -> str:
+        return await self._client._get_object_by_uid(uid, calendar_id=self.id)
+
+    def add_event(self, ical_str: str) -> str:
+        """Add an event to this calendar from an iCalendar string.
+
+        Mirrors :meth:`caldav.collection.Calendar.add_event`. When called on
+        an async-backed calendar, returns a coroutine that must be awaited.
+
+        Args:
+            ical_str: A VCALENDAR string representing the event.
+
+        Returns:
+            The server-assigned JMAP event ID.
+
+        Raises:
+            JMAPMethodError: If the server rejects the create request.
+        """
+        if self._is_async:
+            return self._async_add_event(ical_str)
+        return self._client.create_event(self.id, ical_str)
+
+    async def _async_add_event(self, ical_str: str) -> str:
+        return await self._client.create_event(self.id, ical_str)
diff --git a/docs/source/jmap.rst b/docs/source/jmap.rst
diff --git a/tests/test_jmap_unit.py b/tests/test_jmap_unit.py

Original file line number	Diff line number	Diff line change
`@@ -179,6 +179,7 @@ def replacer(match: re.Match) -> str:`
`179`	`179`	`"features",`
`180`	`180`	`"enable_rfc6764",`
`181`	`181`	`"require_tls",`
	`182`	`+ "protocol",`
`182`	`183`	`]`
`183`	`184`	`)`
`184`	`185`