fix: async support for uncomplete(), set_relation(), get_relatives(), invite methods

Similar to the save()/complete() fix in e819a3a, these methods called
self.save() or self.parent.get_object_by_uid() without awaiting, so in
async mode the returned coroutines were silently discarded.

Changes:
- uncomplete(): delegate to new _async_uncomplete() when is_async_client
- set_relation(): refactor uid/other resolution to share between sync and
  async paths; delegate to new _async_set_relation() when is_async_client;
  extract _add_relation_to_ical() helper to avoid duplicating ical logic
- get_relatives(): extract _parse_relatives_from_ical() helper (pure, no I/O)
  to avoid duplicating ical-parsing logic; delegate to new
  _async_get_relatives() when is_async_client
- _reply_to_invite_request() / accept_invite() / decline_invite() /
  tentatively_accept_invite(): raise NotImplementedError for async clients
  (the entire invite reply flow uses load/save/add_event/schedule_outbox
  which all require async-aware wiring not yet implemented)

Tests: add TestAsyncCalendarObjectResource with 6 unit tests that verify
each fixed method returns a coroutine for async clients and that awaiting
it produces the expected side-effects.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tobixen

caldav/calendarobjectresource.py

@@ -283,16 +283,27 @@ def set_relation(
             else:
                 # Use cheap accessor to avoid format conversion (issue #613)
                 uid = other._get_uid_cheap() or other.icalendar_component["uid"]
+            other_obj = other
         else:
             uid = other
-            if set_reverse:
-                other = self.parent.get_object_by_uid(uid)
+            other_obj = None  # Resolved below (possibly async)
+
+        if self.is_async_client:
+            return self._async_set_relation(uid, other_obj, reltype, set_reverse)
+
+        if other_obj is None and set_reverse:
+            other_obj = self.parent.get_object_by_uid(uid)
         if set_reverse:
             ## TODO: special handling of NEXT/FIRST.
             ## STARTTOFINISH does not have any equivalent "reverse".
             reltype_reverse = self.RELTYPE_REVERSE_MAP[reltype]
-            other.set_relation(other=self, reltype=reltype_reverse, set_reverse=False)
+            other_obj.set_relation(other=self, reltype=reltype_reverse, set_reverse=False)
+
+        self._add_relation_to_ical(uid, reltype)
+        self.save()
 
+    def _add_relation_to_ical(self, uid, reltype) -> None:
+        """Add a RELATED-TO property to the icalendar component (no-op if already present)."""
         existing_relation = self.icalendar_component.get("related-to", None)
         existing_relations = (
             existing_relation if isinstance(existing_relation, list) else [existing_relation]
@@ -306,16 +317,45 @@ def set_relation(
         #  then Component._encode does miss adding properties
         #  see https://github.com/collective/icalendar/issues/557
         #  workaround should be safe to remove if issue gets fixed
-        uid = str(uid)
         self.icalendar_component.add(
-            "related-to", uid, parameters={"RELTYPE": reltype}, encode=True
+            "related-to", str(uid), parameters={"RELTYPE": reltype}, encode=True
         )
 
-        self.save()
+    async def _async_set_relation(self, uid, other_obj, reltype, set_reverse) -> None:
+        """Async implementation of set_relation() for async clients."""
+        if other_obj is None and set_reverse:
+            other_obj = await self.parent.get_object_by_uid(uid)
+        if set_reverse:
+            ## TODO: special handling of NEXT/FIRST.
+            reltype_reverse = self.RELTYPE_REVERSE_MAP[reltype]
+            # set_relation() returns a coroutine when is_async_client, so await it
+            await other_obj.set_relation(other=self, reltype=reltype_reverse, set_reverse=False)
+
+        self._add_relation_to_ical(uid, reltype)
+        await self.save()
 
     ## TODO: this method is undertested in the caldav library.
     ## However, as this consolidated and eliminated quite some duplicated code in the
     ## plann project, it is extensively tested in plann.
+    def _parse_relatives_from_ical(
+        self,
+        reltypes: "Container[str] | None",
+        relfilter: "Callable[[Any], bool] | None",
+    ) -> "defaultdict[str, set[str]]":
+        """Extract RELATED-TO properties as a {reltype: {uid, ...}} dict (pure, no I/O)."""
+        ret: defaultdict[str, set[str]] = defaultdict(set)
+        relations = self.icalendar_component.get("RELATED-TO", [])
+        if not isinstance(relations, list):
+            relations = [relations]
+        for rel in relations:
+            if relfilter and not relfilter(rel):
+                continue
+            reltype = rel.params.get("RELTYPE", "PARENT")
+            if reltypes and reltype not in reltypes:
+                continue
+            ret[reltype].add(str(rel))
+        return ret
+
     def get_relatives(
         self,
         reltypes: Container[str] | None = None,
@@ -340,24 +380,17 @@ def get_relatives(
         (but due to backward compatibility requirement, such an object should behave like
         the current dict)
         """
+        if self.is_async_client:
+            return self._async_get_relatives(reltypes, relfilter, fetch_objects, ignore_missing)
+
         from .collection import Calendar  ## late import to avoid cycling imports
 
-        ret = defaultdict(set)
-        relations = self.icalendar_component.get("RELATED-TO", [])
-        if not isinstance(relations, list):
-            relations = [relations]
-        for rel in relations:
-            if relfilter and not relfilter(rel):
-                continue
-            reltype = rel.params.get("RELTYPE", "PARENT")
-            if reltypes and reltype not in reltypes:
-                continue
-            ret[reltype].add(str(rel))
+        ret = self._parse_relatives_from_ical(reltypes, relfilter)
 
         if fetch_objects:
             for reltype in ret:
                 uids = ret[reltype]
-                reltype_set = set()
+                reltype_set: set = set()
 
                 if self.parent is None:
                     raise ValueError("Unexpected value None for self.parent")
@@ -376,6 +409,37 @@ def get_relatives(
 
         return ret
 
+    async def _async_get_relatives(
+        self,
+        reltypes: "Container[str] | None",
+        relfilter: "Callable[[Any], bool] | None",
+        fetch_objects: bool,
+        ignore_missing: bool,
+    ) -> "defaultdict[str, set]":
+        """Async implementation of get_relatives() for async clients."""
+        from .collection import Calendar  ## late import to avoid cycling imports
+
+        ret = self._parse_relatives_from_ical(reltypes, relfilter)
+
+        if fetch_objects:
+            if self.parent is None:
+                raise ValueError("Unexpected value None for self.parent")
+            if not isinstance(self.parent, Calendar):
+                raise ValueError("self.parent expected to be of type Calendar but it is not")
+
+            for reltype in ret:
+                uids = ret[reltype]
+                reltype_set: set = set()
+                for obj in uids:
+                    try:
+                        reltype_set.add(await self.parent.get_object_by_uid(obj))
+                    except error.NotFoundError:
+                        if not ignore_missing:
+                            raise
+                ret[reltype] = reltype_set
+
+        return ret
+
     def _set_reverse_relation(self, other, reltype):
         ## TODO: handle RFC9253 better!  Particularly next/first-lists
         reverse_reltype = self.RELTYPE_REVERSE_MAP.get(reltype)
@@ -621,6 +685,11 @@ def tentatively_accept_invite(self, calendar: Any | None = None) -> None:
     ## partstat can also be set to COMPLETED and IN-PROGRESS.
 
     def _reply_to_invite_request(self, partstat, calendar) -> None:
+        if self.is_async_client:
+            raise NotImplementedError(
+                "accept_invite/decline_invite/tentatively_accept_invite are not yet supported "
+                "for async clients"
+            )
         error.assert_(self.is_invite_request())
         if not calendar:
             calendar = self.client.principal().get_calendars()[0]
@@ -1966,8 +2035,14 @@ def uncomplete(self) -> None:
         self.icalendar_component.add("status", "NEEDS-ACTION")
         if "completed" in self.icalendar_component:
             self.icalendar_component.pop("completed")
+        if self.is_async_client:
+            return self._async_uncomplete()
         self.save()
 
+    async def _async_uncomplete(self) -> None:
+        """Async implementation of uncomplete() for async clients."""
+        await self.save()
+
     ## TODO: should be moved up to the base class
     def set_duration(self, duration, movable_attr="DTSTART"):
         """

tests/test_caldav_unit.py

@@ -1902,6 +1902,168 @@ async def fake_search(**kwargs):
         assert obj.id == uid
 
 
+class TestAsyncCalendarObjectResource:
+    """Tests that CalendarObjectResource methods return coroutines (not None) for async clients.
+
+    These guard against the pattern where a sync method calls self.save() or
+    self.parent.some_method() without awaiting, silently discarding the coroutine.
+    """
+
+    completed_todo = """BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Example Corp.//CalDAV Client//EN
+BEGIN:VTODO
+UID:20070313T123432Z-456553@example.com
+DTSTAMP:20070313T123432Z
+DUE;VALUE=DATE:20070501
+SUMMARY:Submit Quebec Income Tax Return for 2006
+STATUS:COMPLETED
+COMPLETED:20070501T000000Z
+END:VTODO
+END:VCALENDAR"""
+
+    todo_with_relation = """BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Example Corp.//CalDAV Client//EN
+BEGIN:VTODO
+UID:20070313T123432Z-456553@example.com
+DTSTAMP:20070313T123432Z
+DUE;VALUE=DATE:20070501
+SUMMARY:Submit Quebec Income Tax Return for 2006
+RELATED-TO;RELTYPE=PARENT:parent-uid-001
+STATUS:NEEDS-ACTION
+END:VTODO
+END:VCALENDAR"""
+
+    def _make_async_client_and_calendar(self):
+        from caldav.async_davclient import AsyncDAVClient
+
+        client = MockedDAVClient("")
+        client.__class__ = type(
+            "AsyncDAVClient", (MockedDAVClient,), {"__module__": AsyncDAVClient.__module__}
+        )
+        calendar = Calendar(client, url="/calendar/")
+        return client, calendar
+
+    def test_uncomplete_returns_coroutine_for_async_client(self):
+        """uncomplete() must return a coroutine for async clients, not silently discard save()."""
+        import asyncio
+
+        client, calendar = self._make_async_client_and_calendar()
+        todo = Todo(
+            client=client,
+            url="/calendar/todo1.ics",
+            data=self.completed_todo,
+            parent=calendar,
+        )
+        result = todo.uncomplete()
+        assert asyncio.iscoroutine(result), (
+            f"expected coroutine from uncomplete(), got {type(result)}"
+        )
+        result.close()
+
+    def test_uncomplete_async_saves_and_clears_status(self):
+        """Awaiting uncomplete() must actually save the object and clear STATUS/COMPLETED."""
+        import asyncio
+
+        client, calendar = self._make_async_client_and_calendar()
+        todo = Todo(
+            client=client,
+            url="/calendar/todo1.ics",
+            data=self.completed_todo,
+            parent=calendar,
+        )
+
+        saved = False
+
+        async def fake_async_put(*args, **kwargs):
+            nonlocal saved
+            saved = True
+
+        todo._async_put = fake_async_put
+        asyncio.run(todo.uncomplete())
+
+        assert saved, "uncomplete() did not call _async_put for async client"
+        assert todo.icalendar_component.get("STATUS") == "NEEDS-ACTION"
+        assert "COMPLETED" not in todo.icalendar_component
+
+    def test_get_relatives_returns_coroutine_for_async_client(self):
+        """get_relatives(fetch_objects=True) must return a coroutine for async clients."""
+        import asyncio
+
+        client, calendar = self._make_async_client_and_calendar()
+        todo = Todo(
+            client=client,
+            url="/calendar/todo1.ics",
+            data=self.todo_with_relation,
+            parent=calendar,
+        )
+        result = todo.get_relatives()
+        assert asyncio.iscoroutine(result), (
+            f"expected coroutine from get_relatives(), got {type(result)}"
+        )
+        result.close()
+
+    def test_get_relatives_async_returns_objects(self):
+        """Awaiting get_relatives() must return fetched objects, not coroutines."""
+        import asyncio
+
+        client, calendar = self._make_async_client_and_calendar()
+        todo = Todo(
+            client=client,
+            url="/calendar/todo1.ics",
+            data=self.todo_with_relation,
+            parent=calendar,
+        )
+
+        parent_todo = Todo(client=client, url="/calendar/parent.ics", data=ev1, parent=calendar)
+
+        async def fake_get_object_by_uid(uid):
+            return parent_todo
+
+        calendar.get_object_by_uid = fake_get_object_by_uid
+
+        result = asyncio.run(todo.get_relatives())
+        assert "PARENT" in result
+        parent_set = result["PARENT"]
+        assert len(parent_set) == 1
+        obj = next(iter(parent_set))
+        assert obj is parent_todo, f"expected the parent todo object, got {obj!r}"
+
+    def test_set_relation_returns_coroutine_for_async_client(self):
+        """set_relation() must return a coroutine for async clients, not silently drop save()."""
+        import asyncio
+
+        client, calendar = self._make_async_client_and_calendar()
+        todo = Todo(
+            client=client,
+            url="/calendar/todo1.ics",
+            data=self.completed_todo,
+            parent=calendar,
+        )
+        other_todo = Todo(
+            client=client,
+            url="/calendar/todo2.ics",
+            data=self.completed_todo,
+            parent=calendar,
+        )
+        # Patch id so set_relation can extract a UID without a full ical parse
+        other_todo._id = "some-other-uid"
+
+        result = todo.set_relation(other_todo, reltype="PARENT", set_reverse=False)
+        assert asyncio.iscoroutine(result), (
+            f"expected coroutine from set_relation(), got {type(result)}"
+        )
+        result.close()
+
+    def test_accept_invite_raises_not_implemented_for_async_client(self):
+        """accept_invite() must raise NotImplementedError for async clients (not silently fail)."""
+        client, calendar = self._make_async_client_and_calendar()
+        event = Event(client=client, url="/calendar/ev1.ics", data=ev1, parent=calendar)
+        with pytest.raises(NotImplementedError):
+            event.accept_invite()
+
+
 class TestRateLimitHelpers:
     """Unit tests for the shared rate-limit helper functions in caldav.lib.error."""