feat: freebusy scheduling

The scheduling freebusy-requests were completely untested and didn't work at all.

logic was human-written, test-code by Claude

Prompt: look into https://datatracker.ietf.org/doc/html/rfc6638#appendix-B.5
and make a pure unit test with a mocked-up response to a freebusy scheduling
request, exercising the handling part of it.  This will break with a
NotImplementedError as for now.  Only fix the test, do not fix the code logic.
Consider the TODO-comment in response.py, line 247, and give me an opinion on
weather it makes sense to reuse the _find_objects_and_props for scheduling
response or if it's better to create a dedicated separate method for this.

Author: tobixen

CHANGELOG.md

@@ -35,6 +35,7 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 
 ### Test framework, compatibility hints, documentation, examples
 
+* 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.
 * 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).

caldav/collection.py

@@ -477,15 +477,17 @@ def calendars(self) -> list["Calendar"]:
         """
         return self.get_calendars()
 
-    def freebusy_request(self, dtstart, dtend, attendees):
+    ## TODO: we have code in lib.vcal for constructing icalendar objects,
+    ## and from icalendar 7 there is also code in the icalendar library
+    ## for this.  The cruft below for constructing the request should be
+    ## eliminated.  Also, the async diversion should happen closer to the
+    ## bottom of the method, reducing the need of duplicating code
+    def freebusy_request(self, dtstart, dtend, attendees) -> dict[str, FreeBusy]:
         """Sends a freebusy-request for some attendee to the server
         as per RFC6638.
 
         For async clients, returns a coroutine that must be awaited.
         """
-        if self.is_async_client:
-            return self._async_freebusy_request(dtstart, dtend, attendees)
-
         freebusy_ical = icalendar.Calendar()
         freebusy_ical.add("prodid", "-//tobixen/python-caldav//EN")
         freebusy_ical.add("version", "2.0")
@@ -498,42 +500,34 @@ def freebusy_request(self, dtstart, dtend, attendees):
         freebusy_comp.add("dtend", dtend)
         freebusy_ical.add_component(freebusy_comp)
         outbox = self.schedule_outbox()
-        caldavobj = FreeBusy(data=freebusy_ical, parent=outbox)
-        caldavobj.add_organizer()
+        caldavobj = FreeBusy(data=freebusy_ical, parent=self)
         for attendee in attendees:
             caldavobj.add_attendee(attendee, no_default_parameters=True)
 
+        if self.is_async_client:
+            return self._async_freebusy_request(outbox, caldavobj)
+
+        caldavobj.add_organizer()
+
         response = self.client.post(
             outbox.url,
             caldavobj.data,
             headers={"Content-Type": "text/calendar; charset=utf-8"},
         )
-        return response._find_objects_and_props()
+        return response._parse_scheduling_response_objects(parent=self)
 
-    async def _async_freebusy_request(self, dtstart, dtend, attendees):
+    async def _async_freebusy_request(self, outbox, fb_obj) -> dict:
         """Async implementation of freebusy_request() for async clients."""
-        freebusy_ical = icalendar.Calendar()
-        freebusy_ical.add("prodid", "-//tobixen/python-caldav//EN")
-        freebusy_ical.add("version", "2.0")
-        freebusy_ical.add("method", "REQUEST")
-        uid = uuid.uuid4()
-        freebusy_comp = icalendar.FreeBusy()
-        freebusy_comp.add("uid", uid)
-        freebusy_comp.add("dtstamp", datetime.now())
-        freebusy_comp.add("dtstart", dtstart)
-        freebusy_comp.add("dtend", dtend)
-        freebusy_ical.add_component(freebusy_comp)
-        outbox = await self._async_schedule_outbox()
-        caldavobj = FreeBusy(data=freebusy_ical, parent=outbox)
-        await caldavobj.add_organizer()
-        for attendee in attendees:
-            caldavobj.add_attendee(attendee, no_default_parameters=True)
-        response = await self.client.post(
-            outbox.url,
-            caldavobj.data,
-            headers={"Content-Type": "text/calendar; charset=utf-8"},
-        )
-        return response._find_objects_and_props()
+        ## TODO: could we have common headers as global variable?
+        headers = {"Content-Type": "text/calendar; charset=utf-8"}
+        outbox = await outbox
+        ## TODO: it's really bad that arbitrary methods returns
+        ## a coroutine in async mode.  It's needed to make it much
+        ## more clear what methods involves I/O and what methods
+        ## doesn't involve I/O in 4.0
+        await fb_obj.add_organizer()
+        response = await self.client.post(outbox.url, fb_obj.data, headers)
+        return response._parse_scheduling_response_objects(parent=self)
 
     def calendar_user_address_set(self) -> list[str | None]:
         """
@@ -1473,7 +1467,7 @@ def freebusy_request(self, start: datetime, end: datetime) -> "FreeBusy":
         Returns:
           [FreeBusy(), ...]
         """
-
+        ## TODO: async variant?
         root = cdav.FreeBusyQuery() + [cdav.TimeRange(start, end)]
         response = self._query(root, 1, "report")
         return FreeBusy(self, response.raw)

caldav/datastate.py

@@ -5,6 +5,9 @@
 representations of calendar data (raw string, icalendar object, vobject object).
 
 See https://github.com/python-caldav/caldav/issues/613 for design discussion.
+
+TODO: verify that we have sufficient test coverage - both through unit tests
+and integration tests
 """
 
 from __future__ import annotations
@@ -61,18 +64,18 @@ def get_uid(self) -> str | None:
         """
         cal = self.get_icalendar_copy()
         for comp in cal.subcomponents:
-            if comp.name in ("VEVENT", "VTODO", "VJOURNAL") and "UID" in comp:
+            if comp.name in ("VEVENT", "VTODO", "VJOURNAL", "FREEBUSY") and "UID" in comp:
                 return str(comp["UID"])
         return None
 
     def get_component_type(self) -> str | None:
-        """Get the component type (VEVENT, VTODO, VJOURNAL) without full parsing.
+        """Get the component type (VEVENT, VTODO, VJOURNAL, FREEBUSY) without full parsing.
 
         Default implementation parses the data, but subclasses can optimize.
         """
         cal = self.get_icalendar_copy()
         for comp in cal.subcomponents:
-            if comp.name in ("VEVENT", "VTODO", "VJOURNAL"):
+            if comp.name in ("VEVENT", "VTODO", "VJOURNAL", "FREEBUSY"):
                 return comp.name
         return None
 
@@ -146,6 +149,8 @@ def get_component_type(self) -> str | None:
             return "VTODO"
         elif "BEGIN:VJOURNAL" in self._data:
             return "VJOURNAL"
+        elif "BEGIN:FREEBUSY" in self._data:
+            return "VFREEBUSY"
         return None
 
 
@@ -182,13 +187,13 @@ def get_vobject_copy(self) -> vobject.base.Component:
 
     def get_uid(self) -> str | None:
         for comp in self._calendar.subcomponents:
-            if comp.name in ("VEVENT", "VTODO", "VJOURNAL") and "UID" in comp:
+            if comp.name in ("VEVENT", "VTODO", "VJOURNAL", "VFREEBUSY") and "UID" in comp:
                 return str(comp["UID"])
         return None
 
     def get_component_type(self) -> str | None:
         for comp in self._calendar.subcomponents:
-            if comp.name in ("VEVENT", "VTODO", "VJOURNAL"):
+            if comp.name in ("VEVENT", "VTODO", "VJOURNAL", "VFREEBUSY"):
                 return comp.name
         return None
 
@@ -232,6 +237,8 @@ def get_uid(self) -> str | None:
                 return str(self._vobject.vtodo.uid.value)
             elif hasattr(self._vobject, "vjournal"):
                 return str(self._vobject.vjournal.uid.value)
+            elif hasattr(self._vobject, "vfreebusy"):
+                return str(self._vobject.vfreebusy.uid.value)
         except AttributeError:
             pass
         return None
@@ -243,4 +250,6 @@ def get_component_type(self) -> str | None:
             return "VTODO"
         elif hasattr(self._vobject, "vjournal"):
             return "VJOURNAL"
+        elif hasattr(self._vobject, "vfreebusy"):
+            return "VFREEBUSY"
         return None

caldav/elements/cdav.py

@@ -41,6 +41,9 @@ def _to_utc_date_string(ts):
     return ts.strftime("%Y%m%dT%H%M%SZ")
 
 
+## TODO: add RFC references to every class, like it's done in the Response class
+
+
 # Operations
 class CalendarQuery(BaseElement):
     tag: ClassVar[str] = ns("C", "calendar-query")
@@ -58,14 +61,6 @@ class CalendarMultiGet(BaseElement):
     tag: ClassVar[str] = ns("C", "calendar-multiget")
 
 
-class ScheduleInboxURL(BaseElement):
-    tag: ClassVar[str] = ns("C", "schedule-inbox-URL")
-
-
-class ScheduleOutboxURL(BaseElement):
-    tag: ClassVar[str] = ns("C", "schedule-outbox-URL")
-
-
 # Filters
 class Filter(BaseElement):
     tag: ClassVar[str] = ns("C", "filter")
@@ -143,13 +138,6 @@ class Comp(NamedBaseElement):
     tag: ClassVar[str] = ns("C", "comp")
 
 
-# Uhhm ... can't find any references to calendar-collection in rfc4791.txt
-# and newer versions of baikal gives 403 forbidden when this one is
-# encountered
-# class CalendarCollection(BaseElement):
-#     tag = ns("C", "calendar-collection")
-
-
 # Properties
 class CalendarUserAddressSet(BaseElement):
     tag: ClassVar[str] = ns("C", "calendar-user-address-set")
@@ -208,5 +196,47 @@ class Allprop(BaseElement):
     tag: ClassVar[str] = ns("C", "allprop")
 
 
+# Scheduling
+
+
 class ScheduleTag(BaseElement):
     tag: ClassVar[str] = ns("C", "schedule-tag")
+
+
+class ScheduleInboxURL(BaseElement):
+    tag: ClassVar[str] = ns("C", "schedule-inbox-URL")
+
+
+class ScheduleOutboxURL(BaseElement):
+    tag: ClassVar[str] = ns("C", "schedule-outbox-URL")
+
+
+class ScheduleResponse(BaseElement):
+    tag: ClassVar[str] = ns("C", "schedule-response")
+
+
+class Response(BaseElement):
+    """
+    https://datatracker.ietf.org/doc/html/rfc6638#section-10.2
+    Child of schedule-response
+    """
+
+    tag: ClassVar[str] = ns("C", "response")
+
+
+class Recipient(BaseElement):
+    """
+    https://datatracker.ietf.org/doc/html/rfc6638#section-10.3
+    Child of response
+    """
+
+    tag: ClassVar[str] = ns("C", "recipient")
+
+
+class RequestStatus(BaseElement):
+    """
+    https://datatracker.ietf.org/doc/html/rfc6638#section-10.4
+    Child of response
+    """
+
+    tag: ClassVar[str] = ns("C", "request-status")

caldav/elements/dav.py

@@ -5,6 +5,8 @@
 
 from .base import BaseElement, ValuedBaseElement
 
+## TODO: add RFC references to every class, consistently with the cdav.py
+
 
 # Operations
 class Propfind(BaseElement):

caldav/elements/ical.py

@@ -6,7 +6,7 @@
 from .base import ValuedBaseElement
 
 
-# Properties
+# Properties - those are non-standard but implemented in several calendar servers
 class CalendarColor(ValuedBaseElement):
     tag: ClassVar[str] = ns("I", "calendar-color")
 

caldav/protocol/xml_parsers.py

@@ -162,6 +162,7 @@ def _parse_calendar_query_response(
     return results
 
 
+## TODO: the purpose of the xml_parsers was to consolidate common code to be used by sync and async code paths, to avoid duplicated code.  Why cannot this code snippet be used for async?  The code here is very similar to _parse_calendar_query_response - we should consolidate common code
 def _parse_sync_collection_response(
     body: bytes,
     status_code: int = 207,

caldav/response.py

@@ -13,7 +13,8 @@
 from lxml import etree
 from lxml.etree import _Element
 
-from caldav.elements import dav
+from caldav.calendarobjectresource import FreeBusy
+from caldav.elements import cdav, dav
 from caldav.elements.base import BaseElement
 from caldav.lib import error
 from caldav.lib.python_utilities import to_normal_str
@@ -230,17 +231,90 @@ def _parse_response(self, response: _Element) -> tuple[str, list[_Element], Any
             error.assert_("404" in status)
         return (cast(str, href), propstats, status)
 
-    ## TODO: there is currently quite some overlapping with the protocol.xml_parsers
-    ## we should refactor
+    def _parse_scheduling_response_objects(self, parent) -> dict:
+        """Parses an RFC6638 freebusy scheduling request response
+
+        The response from the server is asserted to be a
+        scheduling-response, with freebusy status for one or more wanted
+        attendee - potentially with error status for all or some
+        of the wanted attendees.
+
+        TODO: some asserts here - should make better error handling
+
+        Returns:
+            Dict with:
+              * email addresses -> FreeBusy status (raw data)
+              * errors - dict with email addresses -> error messages
+
+        """
+        self.objects = {}
+        self.objects["errors"] = {}
+        assert self.tree.tag == cdav.ScheduleResponse.tag
+        for response in self.tree:
+            assert response.tag == cdav.Response.tag
+            parsed_response = self._parse_scheduling_response(response)
+            for x in parsed_response:
+                if x.endswith(":err"):
+                    self.objects["errors"][x[:-4]] = parsed_response[x]
+                else:
+                    self.objects[x] = FreeBusy(parent=parent, data=parsed_response[x])
+
+        return self.objects
+
+    def _parse_scheduling_response(self, response) -> dict[str, str]:
+        """
+        TODO: lots of asserts here - should make better error handling
+
+        Parses one attendee response from a RFC6638 freebusy scheduling request
+
+        Returns:
+          * ``{ recipient => calendar_data }`` if everything is OK,
+          * ``{f"{recipient}:err": status}`` if things are not OK,
+          * a dict with both elements if things are partially OK
+        """
+        ret = {}
+        recipient = None
+        status = None
+        calendar_data = None
+        for x in response:
+            if x.tag == cdav.Recipient.tag:
+                if len(x) == 1:
+                    assert x[0].tag == dav.Href.tag
+                    recipient = x[0].text
+                else:
+                    recipient = x.text
+            elif x.tag == cdav.RequestStatus.tag:
+                status = x.text
+            elif x.tag == cdav.CalendarData.tag:
+                calendar_data = x.text
+            else:
+                raise error.DAVError(f"unexpected attribute {x.tag}")
+        assert recipient
+        assert status
+        if not status.startswith("2.0"):
+            ret[f"{recipient}:err"] = status
+        if calendar_data:
+            ret[recipient] = calendar_data
+        return ret
+
+    ## TODO: there is currently quite some overlapping with the
+    ## protocol.xml_parsers we should refactor.  I'm not 100% sure the
+    ## protocol.xml_parsers layer is a better approach.  Look for more
+    ## cases of old code that was is still remaining after the
+    ## protocol layer refactoring
     def _find_objects_and_props(self) -> dict[str, dict[str, _Element]]:
         """Internal implementation of find_objects_and_props without deprecation warning."""
         self.objects: dict[str, dict[str, _Element]] = {}
         self.statuses: dict[str, str] = {}
 
+        ## TODO: the schedule_tag is not used anywhere as for now
+        ## TODO: should it be set somewhere else? (now it's not
+        ## covered by the scheduling freebusy requests)
         if "Schedule-Tag" in self.headers:
             self.schedule_tag = self.headers["Schedule-Tag"]
 
         responses = self._strip_to_multistatus()
+
         for r in responses:
             if r.tag == dav.SyncToken.tag:
                 self.sync_token = r.text
@@ -312,7 +386,7 @@ def _expand_simple_prop(
         if proptag in props_found:
             prop_xml = props_found[proptag]
             for item in prop_xml.items():
-                if proptag == "{urn:ietf:params:xml:ns:caldav}calendar-data":
+                if proptag == cdav.CalendarData.tag:
                     if (
                         item[0].lower().endswith("content-type")
                         and item[1].lower() == "text/calendar"