refactor(jmap): eliminate duplication and shadow-builtin parameter names

Author: SashankBhamidi

caldav/jmap/_methods/event.py

@@ -105,7 +105,7 @@ def parse_event_changes(
 
 def build_event_query(
     account_id: str,
-    filter: dict | None = None,
+    filter_condition: dict | None = None,
     sort: list[dict] | None = None,
     position: int = 0,
     limit: int | None = None,
@@ -114,7 +114,7 @@ def build_event_query(
 
     Args:
         account_id: The JMAP accountId to query.
-        filter: A ``FilterCondition`` or ``FilterOperator`` dict, e.g.
+        filter_condition: A ``FilterCondition`` or ``FilterOperator`` dict, e.g.
             ``{"after": "2024-01-01T00:00:00Z", "before": "2024-12-31T23:59:59Z"}``.
             ``None`` means no filter (return all events).
         sort: List of ``Comparator`` dicts, e.g.
@@ -127,8 +127,8 @@ def build_event_query(
         A 3-tuple ``("CalendarEvent/query", arguments_dict, call_id)``.
     """
     args: dict = {"accountId": account_id, "position": position}
-    if filter is not None:
-        args["filter"] = filter
+    if filter_condition is not None:
+        args["filter"] = filter_condition
     if sort is not None:
         args["sort"] = sort
     if limit is not None:
@@ -161,7 +161,7 @@ def parse_event_query(response_args: dict) -> tuple[list[str], str, int]:
 def build_event_query_changes(
     account_id: str,
     since_query_state: str,
-    filter: dict | None = None,
+    filter_condition: dict | None = None,
     sort: list[dict] | None = None,
     max_changes: int | None = None,
 ) -> tuple:
@@ -171,16 +171,16 @@ def build_event_query_changes(
         account_id: The JMAP accountId to query.
         since_query_state: The ``queryState`` string from a previous
             ``CalendarEvent/query`` or ``CalendarEvent/queryChanges`` response.
-        filter: Same filter as the original ``CalendarEvent/query`` call.
+        filter_condition: Same filter as the original ``CalendarEvent/query`` call.
         sort: Same sort as the original ``CalendarEvent/query`` call.
         max_changes: Optional upper bound on the number of changes returned.
 
     Returns:
         A 3-tuple ``("CalendarEvent/queryChanges", arguments_dict, call_id)``.
     """
     args: dict = {"accountId": account_id, "sinceQueryState": since_query_state}
-    if filter is not None:
-        args["filter"] = filter
+    if filter_condition is not None:
+        args["filter"] = filter_condition
     if sort is not None:
         args["sort"] = sort
     if max_changes is not None:

caldav/jmap/async_client.py

@@ -16,9 +16,11 @@
 from caldav.jmap._methods.event import (
     build_event_changes,
     build_event_get,
+    build_event_set_create,
     build_event_set_destroy,
     build_event_set_update,
     parse_event_changes,
+    parse_event_get,
     parse_event_set,
 )
 from caldav.jmap._methods.task import (
@@ -166,11 +168,7 @@ async def create_event(self, calendar_id: str, ical_str: str) -> str:
         """
         session = await self._get_session()
         jscal = ical_to_jscal(ical_str, calendar_id=calendar_id)
-        call = (
-            "CalendarEvent/set",
-            {"accountId": session.account_id, "create": {"new-0": jscal}},
-            "ev-set-create-0",
-        )
+        call = build_event_set_create(session.account_id, {"new-0": jscal})
         responses = await self._request([call])
 
         for method_name, resp_args, _ in responses:
@@ -208,7 +206,7 @@ async def get_event(self, event_id: str) -> JMAPCalendarObject:
 
         for method_name, resp_args, _ in responses:
             if method_name == "CalendarEvent/get":
-                items = resp_args.get("list", [])
+                items = parse_event_get(resp_args)
                 if not items:
                     raise JMAPMethodError(
                         url=session.api_url,
@@ -260,7 +258,7 @@ async def _search(
             if method_name == "CalendarEvent/get":
                 return [
                     JMAPCalendarObject(data=item, parent=parent)
-                    for item in resp_args.get("list", [])
+                    for item in parse_event_get(resp_args)
                 ]
 
         return []
@@ -366,7 +364,7 @@ async def get_objects_by_sync_token(
         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", []):
+                for item in parse_event_get(resp_args):
                     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]

caldav/jmap/client.py

@@ -25,9 +25,11 @@
     build_event_changes,
     build_event_get,
     build_event_query,
+    build_event_set_create,
     build_event_set_destroy,
     build_event_set_update,
     parse_event_changes,
+    parse_event_get,
     parse_event_set,
 )
 from caldav.jmap._methods.task import (
@@ -139,7 +141,7 @@ def _build_event_search_calls(
             filter_dict["before"] = end
         if text is not None:
             filter_dict["text"] = text
-        query_call = build_event_query(account_id, filter=filter_dict or None)
+        query_call = build_event_query(account_id, filter_condition=filter_dict or None)
         get_call = (
             "CalendarEvent/get",
             {
@@ -279,11 +281,7 @@ def create_event(self, calendar_id: str, ical_str: str) -> str:
         """
         session = self._get_session()
         jscal = ical_to_jscal(ical_str, calendar_id=calendar_id)
-        call = (
-            "CalendarEvent/set",
-            {"accountId": session.account_id, "create": {"new-0": jscal}},
-            "ev-set-create-0",
-        )
+        call = build_event_set_create(session.account_id, {"new-0": jscal})
         responses = self._request([call])
 
         for method_name, resp_args, _ in responses:
@@ -321,7 +319,7 @@ def get_event(self, event_id: str) -> JMAPCalendarObject:
 
         for method_name, resp_args, _ in responses:
             if method_name == "CalendarEvent/get":
-                items = resp_args.get("list", [])
+                items = parse_event_get(resp_args)
                 if not items:
                     raise JMAPMethodError(
                         url=session.api_url,
@@ -373,7 +371,7 @@ def _search(
             if method_name == "CalendarEvent/get":
                 return [
                     JMAPCalendarObject(data=item, parent=parent)
-                    for item in resp_args.get("list", [])
+                    for item in parse_event_get(resp_args)
                 ]
 
         return []
@@ -481,7 +479,7 @@ def get_objects_by_sync_token(
         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", []):
+                for item in parse_event_get(resp_args):
                     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]
@@ -513,6 +511,7 @@ def delete_event(self, event_id: str) -> None:
     def _get_object_by_uid(
         self, uid: str, calendar_id: str | None = None, parent: JMAPCalendar | None = None
     ) -> JMAPCalendarObject:
+        # RFC 8984 FilterCondition has no uid field; UID matching is done client-side.
         for obj in self._search(calendar_id=calendar_id, parent=parent):
             if obj.data.get("uid") == uid:
                 return obj

caldav/jmap/objects/calendar.py

@@ -85,7 +85,7 @@ def to_jmap(self) -> dict:
             d["color"] = self.color
         return d
 
-    def search(self, **searchargs) -> list[JMAPCalendarObject]:
+    def search(self, **searchargs):
         """Search for calendar objects in this calendar.
 
         Mirrors :meth:`caldav.collection.Calendar.search`. When called on an
@@ -137,7 +137,7 @@ async def _async_search(self, **searchargs) -> list[JMAPCalendarObject]:
             parent=self,
         )
 
-    def get_object_by_uid(self, uid: str, comp_class=None) -> JMAPCalendarObject:
+    def get_object_by_uid(self, uid: str, comp_class=None):
         """Get a calendar object by its iCalendar UID.
 
         Mirrors :meth:`caldav.collection.Calendar.get_object_by_uid`. When

tests/test_jmap_unit.py

@@ -772,7 +772,7 @@ def test_build_event_query_structure(self):
 
     def test_build_event_query_with_filter(self):
         f = {"after": "2024-01-01T00:00:00Z", "before": "2024-12-31T23:59:59Z"}
-        _, args, _ = build_event_query("u1", filter=f)
+        _, args, _ = build_event_query("u1", filter_condition=f)
         assert args["filter"] == f
 
     def test_build_event_query_with_sort(self):
@@ -822,7 +822,7 @@ def test_build_event_query_changes_structure(self):
     def test_build_event_query_changes_with_filter_and_sort(self):
         f = {"calendarIds": {"cal1": True}}
         s = [{"property": "start", "isAscending": True}]
-        _, args, _ = build_event_query_changes("u1", "qstate-1", filter=f, sort=s)
+        _, args, _ = build_event_query_changes("u1", "qstate-1", filter_condition=f, sort=s)
         assert args["filter"] == f
         assert args["sort"] == s