Fix add_object/add_event/add_todo for async clients (issue #631)

Calendar.add_object() was calling o.save() without await, so with an
AsyncDAVClient the method returned a coroutine object instead of an
awaited Event/Todo.  Added _async_add_object_finish() helper that
properly awaits save() and handles reverse relations, and route async
clients through it.

Added regression tests in TestAsyncCalendarAddObject:
- test_add_event_returns_coroutine_with_async_client: verifies the
  return value is awaitable
- test_add_event_result_has_url: verifies the awaited result has a URL

Also fixes test pollution in test_async_davclient.py: switched from
direct class attribute mutation (AsyncEvent._async_create = AsyncMock())
to patch.object(), which restores the original after the test.

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

Author: tobixen

CHANGELOG.md

@@ -14,10 +14,6 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 
 ## [Unreleased]
 
-### Breaking Changes
-
-* The icalendar dependency is updated from 6 to 7 - not because 3.0 depends on icalendar7, but because I'm planning to use icalendar7-features in some upcoming 3.x.  If this causes problems for you, just reach out and I will downgrade the dependency, release a new 3.0.1, and possibly procrastinate the icalendar7-stuff until 4.0.
-
 ### Added
 
 * **Stalwart CalDAV server** added to Docker test server framework.
@@ -30,10 +26,17 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 * Fixed `Principal._async_get_property()` override having an incompatible signature (missing `use_cached` and `**passthrough`) and reimplementing PROPFIND logic already handled correctly by the parent `DAVObject._async_get_property()`. The override has been removed.
 * Fixed inconsistent URL quoting for calendar object UIDs containing slashes -- both `_generate_url()` and `_find_id_and_path()` in `calendarobject_ops.py` now share a single `_quote_uid()` helper (related to https://github.com/python-caldav/caldav/issues/143).
 * Fixed `expand_simple_props()` return value handling.
+* Fixed `Calendar.add_object()` (and `add_event()` / `add_todo()`) not being awaitable when using `AsyncDAVClient` -- `save()` returns a coroutine for async clients, but the code was calling it without `await`, making the method uncallable in async contexts.  https://github.com/python-caldav/caldav/issues/631
+
+### Added (compatibility)
+
+* New feature flag `save-load.event.recurrences.exception` to express whether the server stores master+exception VEVENTs as a single calendar object (per RFC) or splits them into separate objects. When a server stores them separately, `expand=True` searches now automatically fall back to server-side `CALDAV:expand` (when supported), since client-side expansion of the master alone would otherwise yield duplicate occurrences.
+* Added Stalwart compatibility hints: `search.recurrences.includes-implicit.event` (fragile — broken for all-day/VALUE=DATE events), `search.recurrences.includes-implicit.todo` (fragile), `search.recurrences.expanded.exception` (unsupported), `save-load.event.recurrences.exception` (unsupported — exceptions stored as separate objects), `vtodo_datesearch_nodtstart_task_is_skipped` and `no_search_openended` old-flags.
 
 ### Test Framework
 
 * Added async rate-limit unit tests matching the sync test suite.
+* caldav-server-tester: `CheckRecurrenceSearch` now also verifies implicit recurrence support for all-day (VALUE=DATE) recurring events, marking the feature as `fragile` (with behaviour description) when only datetime recurring events work.
 
 ## [3.0.0a2] - 2026-02-25 (Alpha Release)
 

caldav/collection.py

@@ -840,6 +840,8 @@ def add_object(
             ),
             parent=self,
         )
+        if self.is_async_client:
+            return self._async_add_object_finish(o, no_overwrite=no_overwrite, no_create=no_create)
         o = o.save(no_overwrite=no_overwrite, no_create=no_create)
         ## TODO: Saving nothing is currently giving an object with None as URL.
         ## This should probably be changed in some future version to raise an error
@@ -848,6 +850,13 @@ def add_object(
             o._handle_reverse_relations(fix=True)
         return o
 
+    async def _async_add_object_finish(self, o, no_overwrite=False, no_create=False):
+        """Async helper for add_object(): awaits save() then handles reverse relations."""
+        o = await o.save(no_overwrite=no_overwrite, no_create=no_create)
+        if o.url is not None:
+            o._handle_reverse_relations(fix=True)
+        return o
+
     def add_event(self, *largs, **kwargs) -> "Event":
         """
         Add an event to the calendar.

tests/test_async_davclient.py

@@ -821,6 +821,61 @@ def test_has_component_with_only_vcalendar(self) -> None:
         assert obj.has_component() is False
 
 
+class TestAsyncCalendarAddObject:
+    """Tests for Calendar.add_object/add_event/add_todo with async clients (issue #631)."""
+
+    SIMPLE_EVENT = """BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:test-async-add-event@example.com
+DTSTART:20200101T100000Z
+DTEND:20200101T110000Z
+SUMMARY:Test Async Add Event
+END:VEVENT
+END:VCALENDAR"""
+
+    @pytest.mark.asyncio
+    async def test_add_event_returns_coroutine_with_async_client(self) -> None:
+        """Calendar.add_event() must be awaitable when using AsyncDAVClient.
+
+        Regression test for issue #631: o.save() returns a coroutine for async
+        clients, so add_object() must await it instead of doing o.url on the
+        coroutine object.
+        """
+        import inspect
+
+        from caldav.aio import AsyncEvent
+        from caldav.collection import Calendar
+
+        client = AsyncDAVClient(url="https://caldav.example.com/dav/")
+        calendar = Calendar(client=client, url="https://caldav.example.com/dav/calendars/test/")
+
+        with patch.object(AsyncEvent, "_async_create", new_callable=AsyncMock):
+            result = calendar.add_event(self.SIMPLE_EVENT)
+            # With an async client, add_event must return a coroutine
+            assert inspect.isawaitable(result), (
+                "add_event() should return a coroutine when using AsyncDAVClient, "
+                "got %r instead" % result
+            )
+            event = await result
+        assert isinstance(event, AsyncEvent)
+
+    @pytest.mark.asyncio
+    async def test_add_event_result_has_url(self) -> None:
+        """Awaiting add_event() with async client returns an Event with a URL."""
+        from caldav.aio import AsyncEvent
+        from caldav.collection import Calendar
+
+        client = AsyncDAVClient(url="https://caldav.example.com/dav/")
+        calendar = Calendar(client=client, url="https://caldav.example.com/dav/calendars/test/")
+
+        with patch.object(AsyncEvent, "_async_create", new_callable=AsyncMock):
+            event = await calendar.add_event(self.SIMPLE_EVENT)
+        # Should have a URL set (or None, but not crash)
+        _ = event.url  # must not raise AttributeError
+
+
 class TestAsyncRateLimiting:
     """
     Unit tests for 429/503 rate-limit handling in AsyncDAVClient.