some more documentation, trying to make it more visible that a CalendarObjectResource (event) should contain one calendar component except for recurrences where it may contain overridden instances

Author: tobixen

caldav/calendarobjectresource.py

@@ -79,9 +79,17 @@
 
 
 class CalendarObjectResource(DAVObject):
-    """
-    Ref RFC 4791, section 4.1, a "Calendar Object Resource" can be an
+    """Ref RFC 4791, section 4.1, a "Calendar Object Resource" can be an
     event, a todo-item, a journal entry, or a free/busy entry
+
+    As per the RFC, a CalendarObjectResource can at most contain one
+    calendar component, with the exception of recurrence components.
+    Meaning that event.data typically contains one VCALENDAR with one
+    VEVENT and possibly one VTIMEZONE.
+
+    In the case of expanded calendar date searches, each recurrence
+    will (by default) wrapped in a distinct CalendarObjectResource
+    object.  This is a deviation from the definition given in the RFC.
     """
 
     ## There is also STARTTOFINISH, STARTTOSTART and FINISHTOFINISH in RFC9253,
@@ -473,7 +481,7 @@ def _set_icalendar_component(self, value) -> None:
     icalendar_component = property(
         _get_icalendar_component,
         _set_icalendar_component,
-        doc="icalendar component - should not be used with recurrence sets",
+        doc="icalendar component - this is the simplest way to access the event/task - it will give you the first component that isn't a timezone component.  For recurrence sets, the master component will be returned.  For any non-recurring event/task/journal, there should be only one calendar component in the object.  For results from an expanded search, there should be only one calendar component in the object",
     )
 
     component = icalendar_component

caldav/davclient.py

@@ -563,14 +563,22 @@ def principals(self, name=None):
         ## TODO: allow server side filtering.  We need a  <D:property-search><D:prop><D:displayname/></D:prop><D:match>{name}</D:match></D:property-search> inside the PrincipalPropertySearch
 
         if name:
-            name_filter = [ dav.PropertySearch() + [dav.Prop() + [dav.DisplayName()]] + dav.Match(value=name)]
-            import pdb; pdb.set_trace()
+            name_filter = [
+                dav.PropertySearch()
+                + [dav.Prop() + [dav.DisplayName()]]
+                + dav.Match(value=name)
+            ]
+            import pdb
+
+            pdb.set_trace()
         else:
             name_filter = []
 
-        query = dav.PrincipalPropertySearch() + name_filter + [
-            dav.Prop() + cdav.CalendarHomeSet() + dav.DisplayName()
-        ]
+        query = (
+            dav.PrincipalPropertySearch()
+            + name_filter
+            + [dav.Prop() + cdav.CalendarHomeSet() + dav.DisplayName()]
+        )
         response = self.report(self.url, etree.tostring(query.xmlelement()))
         principal_dict = response.find_objects_and_props()
         ret = []

caldav/elements/dav.py

@@ -30,11 +30,14 @@ class PrincipalPropertySearch(BaseElement):
 class PropertySearch(BaseElement):
     tag: ClassVar[str] = ns("D", "property-search")
 
+
 # Filters
 
+
 class Match(BaseElement):
     tag: ClassVar[str] = ns("D", "match")
 
+
 # Conditions
 class SyncToken(BaseElement):
     tag: ClassVar[str] = ns("D", "sync-token")

tests/test_vcal.py

@@ -49,7 +49,7 @@ def normalize(s, ignore_uid):
             ## ref https://github.com/python-caldav/caldav/issues/380
             for i in range(0, len(s)):
                 ## We cut the value itself, just asserting the attribute is present
-                if s[i].startswith(b'DTSTAMP'):
+                if s[i].startswith(b"DTSTAMP"):
                     s[i] = s[i][:9]
             return b"\n".join(s)