fix: make multiget async-aware, fix _post_load_by_multiget, deprecate calendar_multiget

- multiget() now dispatches to _async_multiget_objects() for async clients,
  following the ASYNC_DUAL_MODE pattern
- extracted _post_multiget() shared post-processing helper
- added _async_multiget_objects() async counterpart
- _post_load_by_multiget() now calls iter() so it works with both generator
  (_multiget) and list (_async_multiget) inputs
- calendar_multiget() now emits DeprecationWarning pointing to multiget()
- test_multi_get updated to use multiget() directly (not deprecated calendar_multiget)
- fix test_async_integration.py: use save-load.mutable instead of no-overwrite flag

prompt: tests/test_async_integration.py::TestAsyncForXandikos::test_multi_get fails in the git worktree branch on /tmp/caldav-async-tests/, fix multiget in collection.py to be async-aware, following the pattern in docs/design/ASYNC_DUAL_MODE.md
followup-prompt: wait. calendar_multiget is deprecated and scheduled for deletion. Any test code exercising calendar_multiget can be removed or rewritten to use self.multiget instead.
followup-prompt: Add deprecation warnings to that calendar_multiget method
followup-prompt: commit (include the save-load.mutable fix)

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

Author: tobixen

caldav/calendarobjectresource.py

@@ -1071,6 +1071,7 @@ async def _async_load_by_multiget(self) -> Self:
     def _post_load_by_multiget(self, items):
         if not items:
             raise error.NotFoundError(self.url)
+        items = iter(items)
         url_data = next(items, None)
         if url_data is None:
             ## We shouldn't come here.  Something is wrong.

caldav/collection.py

@@ -1080,6 +1080,7 @@ def _multiget(self, event_urls: Iterable[URL], raise_notfound: bool = False) ->
         """
         get multiple events' data.
         TODO: Does it overlap the _request_report_build_resultlist method
+        ## WARNING: async logic is duplicated in _async_multiget — mirror any changes there
         """
         if self.url is None:
             raise ValueError("Unexpected value None for self.url")
@@ -1098,28 +1099,33 @@ def _multiget(self, event_urls: Iterable[URL], raise_notfound: bool = False) ->
         for r in results:
             yield (r, results[r][cdav.CalendarData.tag])
 
-    ## Replace the last lines with
+    def _post_multiget(self, results: Iterable[tuple[str, str]]) -> list[_CC]:
+        """Post-processing shared by multiget and _async_multiget_objects."""
+        return [
+            self._calendar_comp_class_by_data(data)(
+                self.client,
+                # Quote path to handle servers returning unencoded spaces (e.g., Zimbra)
+                url=self.url.join(quote(unquote(str(url)), safe="/:@")),
+                data=data,
+                parent=self,
+            )
+            for url, data in results
+        ]
+
     def multiget(self, event_urls: Iterable[URL], raise_notfound: bool = False) -> Iterable[_CC]:
         """
         get multiple events' data
         TODO: Does it overlap the _request_report_build_resultlist method?
         @author mtorange@gmail.com (refactored by Tobias)
         """
-        results = self._multiget(event_urls, raise_notfound=raise_notfound)
-        for url, data in results:
-            # Quote path to handle servers returning unencoded spaces (e.g., Zimbra)
-            quoted_url = quote(unquote(str(url)), safe="/:@")
-            yield self._calendar_comp_class_by_data(data)(
-                self.client,
-                url=self.url.join(quoted_url),
-                data=data,
-                parent=self,
-            )
+        if self.is_async_client:
+            return self._async_multiget_objects(event_urls, raise_notfound=raise_notfound)
+        return self._post_multiget(self._multiget(event_urls, raise_notfound=raise_notfound))
 
     async def _async_multiget(
         self, event_urls: Iterable[URL], raise_notfound: bool = False
     ) -> list[tuple[str, str]]:
-        """Async version of _multiget — returns a list of (url, data) tuples."""
+        ## WARNING: sync logic is duplicated in _multiget — mirror any changes there
         if self.url is None:
             raise ValueError("Unexpected value None for self.url")
 
@@ -1134,13 +1140,29 @@ async def _async_multiget(
                     raise error.NotFoundError(f"Status {status} in {href}")
         return [(r, results[r][cdav.CalendarData.tag]) for r in results]
 
+    async def _async_multiget_objects(
+        self, event_urls: Iterable[URL], raise_notfound: bool = False
+    ) -> list[_CC]:
+        """Async version of multiget."""
+        return self._post_multiget(
+            await self._async_multiget(event_urls, raise_notfound=raise_notfound)
+        )
+
     def calendar_multiget(self, *largs, **kwargs):
         """
         get multiple events' data
         @author mtorange@gmail.com
         (refactored by Tobias)
         This is for backward compatibility.  It may be removed in 3.0 or later release.
+
+        .. deprecated::
+            Use :meth:`multiget` instead.
         """
+        warnings.warn(
+            "calendar_multiget is deprecated, use multiget instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return list(self.multiget(*largs, **kwargs))
 
     def date_search(

tests/test_async_integration.py

@@ -620,7 +620,7 @@ async def test_create_overwrite_delete_event(self, async_calendar: Any) -> None:
         assert e1.url is not None
 
         # same UID again → overwrite (unless server forbids it)
-        if not self.is_supported("no-overwrite"):
+        if not self.is_supported("save-load.mutable"):
             e2 = await c.add_event(ev1_static)
 
             # no_create on an existing event must succeed
@@ -718,7 +718,7 @@ async def test_copy_event(self, async_calendar: Any, async_calendar2: Any) -> No
 
     @pytest.mark.asyncio
     async def test_multi_get(self, async_calendar: Any) -> None:
-        """calendar_multiget() retrieves multiple events in one request."""
+        """multiget() retrieves multiple events in one request."""
         self.skip_unless_support("save-load.event")
 
         c = async_calendar
@@ -736,7 +736,7 @@ async def test_multi_get(self, async_calendar: Any) -> None:
             summary="test-multiget-2",
         )
 
-        results = await c.calendar_multiget([event1.url, event2.url])
+        results = await c.multiget([event1.url, event2.url])
         assert len(results) == 2
         uids = {str(r.icalendar_component["uid"]) for r in results}
         assert uids == {"test-multiget-1", "test-multiget-2"}