feat: make more methods async-aware and refactor

Invite-handling (accept_invite, decline_invite, tentatively_accept_invite)
now returns awaitable coroutines when used in async mode.

SynchronizableCalendarObjectCollection.sync() has also been dealt
with, togheter with `MailBox.get_items()` and `DAVObject.children()`

Also adds design docs:
- docs/design/TODO_SCHEDULE_TAG.md (analysis and implementation plan,
  refs #660)
- docs/design/TODO_COMPATIBILITY_HINTS.md (FeatureSet cleanup analysis,
  refs #659)

The code logic here is partly human-created, mostly partly AI-created,
certainly under human guideance.  The final secision on how to handle
async in 3.x has been carved in stone by a human. Test code is
predominantly AI-created.

The AI-generation involves tedious code duplication work and tedious
routine refactoring, chances for mistakes are bigger when doing it by
hand than by AI.  I've been looking through the changes, and I trust
the tests to uncover any errors slipping through.

Some of the (many) commits dealing with this have been squashed
into this commit.

The return type of cached properties should always be an awaitable
coroutine in async mode.

prompt: Please make an async version of the get_items method in
  `caldav/collections.py`
followup-prompt: I don't want workarounds in _async_get_items for
  async-unaware get_objects_by_sync_token. Fix _async_get_items assuming
  get_objects_by_sync_token will be made async-aware.
followup-prompt: Please make an async-version of get_objects_by_sync_token
prompt: Please investigate those failures:
  FAILED tests/test_async_integration.py::TestAsyncSchedulingForStalwart (...)
prompt: make an async version of _reply_to_invite_request in
  `caldav/calendarobjectresource.py`
prompt: In collection.py and calendarobjectresource.py and
  possibly in some of the other files as well, many methods are split up
  into a sync version and an async version.  Please make appropriate
  type-hints for all methods that in async mode will yield a coroutine
  rather than an object
Prompt: Let's refactor the async methods where it's possible.
The existing pattern goes like this:
  * we have a sync version `foo` or `_foo`
  * we have an async version of the same method, `_async_foo`
  * `foo` is *most of the time* doing
    `if self.is_async_client: return self._async_foo(...)`
I'd like to reduce the amount of duplicated code as well as to split out
the IO-logic as much as possible.  As for now, I want to go with this
pattern:
  * `foo` should *always* do the
    `if self.is_async_client: return self._async_foo(...)`-logic
  * `self._async_foo` should never be called upon other places
  * Quite many of the methods are doing some preparations, firing off
    some other method causing I/O, and then doing some processing of
    the data returned from the server.  Other methods are more complex,
    having mutliple code lines causing I/O.
  * For methods containing significant amount of logic (like, two or
    more code lines) before doing any IO, the
    `if self.is_async_client: return self._async_foo(...)`-logic
    should be moved to the last possible point in the method. * For methods
    containing significant amount of logic after doing the IO, split the
    logic out in a `_post_foo`-method.
(the rules above was later moved to a document and tweaked a bit)
prompt: Apply the rules from `docs/design/ASYNC_DUAL_MODE.md` for the
`def sync` and `def async_sync` in `collection.py`

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

Author: tobixen

CHANGELOG.md

@@ -37,6 +37,14 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 
 * Open-ended time-range search compatibility hints: new `search.time-range.open`, `search.time-range.open.end`, `search.time-range.open.start`, and `search.time-range.open.start.duration` features (RFC4791 section 9.9).  Old `no_search_openended` flag and `search.time-range.todo.duration`/`search.time-range.todo.open-start` features migrated.  `testTodoSearch` updated to use `is_supported("search.time-range.open.end")` instead of the old compatibility flag.
 * RFC 6638 scheduling feature-detection infrastructure: new `scheduling`, `scheduling.mailbox`, and `scheduling.calendar-user-address-set` compatibility hints; legacy `no_scheduling` flags migrated.  Default scheduling hints set for all the servers tested.
+* New `scheduling.schedule-tag` compatibility flag and tests covering RFC 6638 §3.2–3.3: `testScheduleTagReturnedOnSave`, `testScheduleTagStableOnPartstateUpdate`, `testScheduleTagChangesOnOrganizerUpdate`, `testScheduleTagMismatchRaisesError`, `testScheduleTagMatchSucceeds` — plus async counterparts of all five.
+* New `scheduling.schedule-tag.stable-partstat` compatibility hint: RFC6638 §3.2 requires the Schedule-Tag to remain unchanged when an attendee performs a PARTSTAT-only update; CCS does not comply and is marked `unsupported`.  `testScheduleTagStableOnPartstateUpdate` (and its async counterpart) now skip on non-compliant servers.
+* New `scheduling.auto-schedule` compatibility flag (see Added section).  Server entries updated: Baikal, Cyrus, DAViCal, Davis, CCS, Nextcloud, Stalwart gain explicit `inbox-delivery` + `auto-schedule` values; Zimbra: `inbox-delivery=False` + `auto-schedule=True`.
+* Scheduling freebusy-query: `scheduling.freebusy-query` feature flag (RFC 6638 outbox POST); `freebusy-query.rfc4791` merged into `freebusy-query` (RFC 4791 REPORT).  `testFreeBusy` added to `_TestSchedulingBase`; async counterpart added to `_AsyncTestSchedulingBase`.
+* `search.time-range.todo.strict` compatibility flag: server must not return VTODOs whose time span is entirely outside the searched range; xandikos is marked `broken`.
+* New `save-load.property.related-to`, `search.time-range.todo.duration`, and `search.time-range.todo.open-start` feature flags replacing old-style flags.  RFC links added to all FEATURES entries.
+* `_AsyncTestSchedulingBase` added: async counterpart of `_TestSchedulingBase` with `test_invite_and_respond` and `test_freebusy`; `TestAsyncSchedulingFor<Server>` classes generated for each server with `scheduling_users` configured.
+* New `scheduling.schedule-tag.stable-partstat` compatibility hint: RFC6638 §3.2 requires the Schedule-Tag to remain unchanged when an attendee performs a PARTSTAT-only update; CCS does not comply and is marked `unsupported`.  `testScheduleTagStableOnPartstateUpdate` (and its async counterpart) now skip on non-compliant servers.
 * Calendar owner example (`examples/calendar_owner_examples.py`) demonstrating how to retrieve the owner of a calendar via `DAV:owner` and resolve their calendar-user address.  `testFindCalendarOwner` now exercises the full owner → principal → `get_vcal_address()` chain.  Closes https://github.com/python-caldav/caldav/issues/544
 * `testInviteAndRespond` implemented end-to-end: organizer creates an event, invites an attendee, attendee accepts, and the organizer verifies the updated `PARTSTAT`.  Per-server compatibility flags applied for known quirks (Baikal, Cyrus, SOGo).
 * Multi-user RFC 6638 scheduling tests wired into the Docker server setup for Cyrus and Baikal (pre-populated `user1`–`user3`/`user1`–`user5`).

caldav/aio.py

@@ -27,7 +27,7 @@
 """
 
 # Import the async client (this is truly async)
-from caldav.async_davclient import AsyncDAVClient, AsyncDAVResponse, get_calendar, get_calendars
+from caldav.async_davclient import AsyncDAVClient, DAVResponse, get_calendar, get_calendars
 from caldav.async_davclient import get_davclient as get_async_davclient
 from caldav.calendarobjectresource import CalendarObjectResource, Event, FreeBusy, Journal, Todo
 from caldav.collection import (
@@ -59,7 +59,7 @@
 __all__ = [
     # Client
     "AsyncDAVClient",
-    "AsyncDAVResponse",
+    "DAVResponse",
     "get_async_davclient",
     # Factory functions (async equivalents of caldav.get_calendar / get_calendars)
     "get_calendar",

caldav/async_davclient.py

@@ -71,24 +71,8 @@ def auth_flow(self, request):
 from caldav.compatibility_hints import FeatureSet
 from caldav.lib import error
 from caldav.lib.python_utilities import to_wire
-from caldav.lib.url import URL
-from caldav.protocol.types import (
-    CalendarQueryResult,
-    PropfindResult,
-)
-from caldav.protocol.xml_builders import (
-    _build_calendar_multiget_body,
-    _build_calendar_query_body,
-    _build_propfind_body,
-    _build_sync_collection_body,
-)
-from caldav.protocol.xml_parsers import (
-    _parse_calendar_query_response,
-    _parse_propfind_response,
-    _parse_sync_collection_response,
-)
 from caldav.requests import HTTPBearerAuth
-from caldav.response import BaseDAVResponse
+from caldav.response import CalendarQueryResult, DAVResponse, PropfindResult
 
 log = logging.getLogger("caldav")
 
@@ -98,31 +82,6 @@ def auth_flow(self, request):
     from typing import Self
 
 
-class AsyncDAVResponse(BaseDAVResponse):
-    """
-    Response from an async DAV request.
-
-    This class handles the parsing of DAV responses, including XML parsing.
-    End users typically won't interact with this class directly.
-
-    Response parsing methods are inherited from BaseDAVResponse.
-
-    New protocol-based attributes:
-        results: Parsed results from protocol layer (List[PropfindResult], etc.)
-        sync_token: Sync token from sync-collection response
-    """
-
-    # Protocol-based parsed results (new interface)
-    results: list[PropfindResult | CalendarQueryResult] | None = None
-    sync_token: str | None = None
-
-    def __init__(self, response: Any, davclient: Optional["AsyncDAVClient"] = None) -> None:
-        """Initialize from httpx.Response or niquests.Response."""
-        self._init_from_response(response, davclient)
-
-    # Response parsing methods are inherited from BaseDAVResponse
-
-
 class AsyncDAVClient(BaseDAVClient):
     """
     Async WebDAV/CalDAV client.
@@ -366,7 +325,7 @@ async def request(
         body: str = "",
         headers: Mapping[str, str] | None = None,
         rate_limit_time_slept: float = 0,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send an async HTTP request, with optional rate-limit sleep-and-retry.
 
@@ -404,7 +363,7 @@ async def _async_request(
         method: str = "GET",
         body: str = "",
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Async HTTP request implementation with auth negotiation.
 
@@ -463,7 +422,7 @@ async def _async_request(
                     if auth_types:
                         msg += "\nSupported authentication types: {}".format(", ".join(auth_types))
                 log.warning(msg)
-            response = AsyncDAVResponse(r, self)
+            response = DAVResponse(r, self)
         except Exception:
             # Workaround for servers that abort connection on unauthenticated requests
             # ref https://github.com/python-caldav/caldav/issues/158
@@ -498,7 +457,7 @@ async def _async_request(
                 # Retry original request with auth
                 request_kwargs["auth"] = self.auth
                 r = await self.session.request(**request_kwargs)
-            response = AsyncDAVResponse(r, self)
+            response = DAVResponse(r, self)
 
         # Handle 429/503 rate-limit responses
         error.raise_if_rate_limited(r.status_code, str(url_obj), r.headers.get("Retry-After"))
@@ -542,7 +501,7 @@ async def propfind(
         depth: int = 0,
         headers: Mapping[str, str] | None = None,
         props: list[str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a PROPFIND request.
 
@@ -554,7 +513,7 @@ async def propfind(
             props: List of property names to request (uses protocol layer).
 
         Returns:
-            AsyncDAVResponse with results attribute containing parsed PropfindResult list.
+            DAVResponse with results attribute containing parsed PropfindResult list.
         """
         # Use protocol layer to build XML if props provided
         if props is not None and not body:
@@ -580,7 +539,7 @@ async def report(
         body: str = "",
         depth: int | None = 0,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a REPORT request.
 
@@ -592,7 +551,7 @@ async def report(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         final_headers = self._build_method_headers("REPORT", depth, headers)
         return await self.request(url or str(self.url), "REPORT", body, final_headers)
@@ -601,7 +560,7 @@ async def options(
         self,
         url: str | None = None,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send an OPTIONS request.
 
@@ -610,7 +569,7 @@ async def options(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         return await self.request(url or str(self.url), "OPTIONS", "", headers)
 
@@ -621,7 +580,7 @@ async def proppatch(
         url: str,
         body: str = "",
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a PROPPATCH request.
 
@@ -631,7 +590,7 @@ async def proppatch(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         final_headers = self._build_method_headers("PROPPATCH", extra_headers=headers)
         return await self.request(url, "PROPPATCH", body, final_headers)
@@ -641,7 +600,7 @@ async def mkcol(
         url: str,
         body: str = "",
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a MKCOL request.
 
@@ -653,7 +612,7 @@ async def mkcol(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         final_headers = self._build_method_headers("MKCOL", extra_headers=headers)
         return await self.request(url, "MKCOL", body, final_headers)
@@ -663,7 +622,7 @@ async def mkcalendar(
         url: str,
         body: str = "",
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a MKCALENDAR request.
 
@@ -673,7 +632,7 @@ async def mkcalendar(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         final_headers = self._build_method_headers("MKCALENDAR", extra_headers=headers)
         return await self.request(url, "MKCALENDAR", body, final_headers)
@@ -683,7 +642,7 @@ async def put(
         url: str,
         body: str,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a PUT request.
 
@@ -693,7 +652,7 @@ async def put(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         return await self.request(url, "PUT", body, headers)
 
@@ -702,7 +661,7 @@ async def post(
         url: str,
         body: str,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a POST request.
 
@@ -712,15 +671,15 @@ async def post(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         return await self.request(url, "POST", body, headers)
 
     async def delete(
         self,
         url: str,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Send a DELETE request.
 
@@ -729,7 +688,7 @@ async def delete(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse
+            DAVResponse
         """
         return await self.request(url, "DELETE", "", headers)
 
@@ -747,7 +706,7 @@ async def calendar_query(
         expand: bool = False,
         depth: int = 1,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Execute a calendar-query REPORT to search for calendar objects.
 
@@ -763,7 +722,7 @@ async def calendar_query(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse with results containing List[CalendarQueryResult].
+            DAVResponse with results containing List[CalendarQueryResult].
         """
 
         body, _ = _build_calendar_query_body(
@@ -797,7 +756,7 @@ async def calendar_multiget(
         hrefs: list[str] | None = None,
         depth: int = 1,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Execute a calendar-multiget REPORT to fetch specific calendar objects.
 
@@ -808,7 +767,7 @@ async def calendar_multiget(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse with results containing List[CalendarQueryResult].
+            DAVResponse with results containing List[CalendarQueryResult].
         """
         body = _build_calendar_multiget_body(hrefs or [])
 
@@ -835,7 +794,7 @@ async def sync_collection(
         props: list[str] | None = None,
         depth: int = 1,
         headers: Mapping[str, str] | None = None,
-    ) -> AsyncDAVResponse:
+    ) -> DAVResponse:
         """
         Execute a sync-collection REPORT for efficient synchronization.
 
@@ -847,7 +806,7 @@ async def sync_collection(
             headers: Additional headers.
 
         Returns:
-            AsyncDAVResponse with results containing SyncCollectionResult.
+            DAVResponse with results containing SyncCollectionResult.
         """
         body = _build_sync_collection_body(sync_token=sync_token, props=props)
 
@@ -869,6 +828,12 @@ async def sync_collection(
 
         return response
 
+    def _value_or_coroutine(self, value):
+        return self._async_value_or_coroutine(value)
+
+    async def _async_value_or_coroutine(self, value):
+        return value
+
     # ==================== Authentication Helpers ====================
 
     def build_auth_object(self, auth_types: list[str] | None = None) -> None:
@@ -1121,21 +1086,6 @@ async def principal(self) -> "Principal":
         """
         return await self.get_principal()
 
-    def calendar(self, **kwargs: Any) -> "Calendar":
-        """Returns a calendar object.
-
-        Typically, a URL should be given as a named parameter (url)
-
-        No network traffic will be initiated by this method.
-
-        If you don't know the URL of the calendar, use
-        ``await client.get_principal().get_calendars()`` instead, or
-        ``await client.get_calendars()``
-        """
-        from caldav.collection import Calendar
-
-        return Calendar(client=self, **kwargs)
-
     async def check_dav_support(self) -> str | None:
         """
         Check if the server supports DAV.