feat: add calendar owner example and improve testFindCalendarOwner (closes #544)

- Add examples/calendar_owner_examples.py demonstrating how to get the
  owner of a calendar via DAV:owner and look up their calendar-user
  address via Principal.get_vcal_address()
- Improve testFindCalendarOwner to actually exercise the owner→principal
  →get_vcal_address() chain when the server supports both properties
- Add test_calendar_owner_examples to tests/test_examples.py
- Fix FeatureSet collapse regression: add explicit default to
  scheduling.mailbox in FEATURES so that _derive_from_subfeatures()
  does not roll the child quirk status up to the parent when
  CheckSchedulingDetails has not run

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

Author: tobixen

caldav/compatibility_hints.py

@@ -271,6 +271,7 @@ class FeatureSet:
         "scheduling.mailbox": {
             "description": "Server provides schedule-inbox and schedule-outbox collections for the principal (RFC6638 sections 2.1-2.2). When unsupported, calls to schedule_inbox() or schedule_outbox() raise NotFoundError.",
             "links": ["https://datatracker.ietf.org/doc/html/rfc6638#section-2.1"],
+            "default": {"support": "full"},
         },
         "scheduling.calendar-user-address-set": {
             "description": "Server provides the calendar-user-address-set property on the principal (RFC6638 section 2.4.1), used to identify a user's email/URI for scheduling purposes. When unsupported, calendar_user_address_set() raises NotFoundError.",
@@ -985,7 +986,7 @@ def dotted_feature_set_list(self, compact=False):
     'principal-search': "unsupported",
     ## Zimbra implements server-side automatic scheduling: invitations are
     ## auto-processed into the attendee's calendar; no iTIP notification appears in the inbox.
-    "scheduling": True,
+    "scheduling.mailbox": True,
     "scheduling.mailbox.inbox-delivery": {"support": "unsupported"},
 
     "old_flags": [
@@ -1042,7 +1043,7 @@ def dotted_feature_set_list(self, compact=False):
     #"search.unlimited-time-range": {"support": "broken"},
     ## Bedework uses a pre-built Docker image with no easy way to add users, so
     ## cross-user scheduling tests cannot be run; inbox-delivery behaviour is unknown.
-    "scheduling.mailbox.inbox-delivery": {"support": "unknown"},
+    "scheduling.mailbox": {"support": "unknown"},
 
     ## TODO: play with this and see if it's needed
     'old_flags': [
@@ -1070,6 +1071,7 @@ def dotted_feature_set_list(self, compact=False):
     # Baikal (sabre/dav) delivers iTIP notifications to the attendee inbox AND auto-schedules
     # into their calendar (quirk: both delivery modes happen simultaneously).
     "scheduling.mailbox.inbox-delivery": {"support": "quirk", "behaviour": "server delivers iTIP notification to inbox AND auto-schedules into calendar"},
+    "scheduling.mailbox": True,
     "http.multiplexing": "fragile", ## ref https://github.com/python-caldav/caldav/issues/564
     'search.comp-type.optional': {'support': 'ungraceful'},
     'search.recurrences.expanded.todo': {'support': 'unsupported'},
@@ -1115,6 +1117,7 @@ def dotted_feature_set_list(self, compact=False):
     # AND delivers an iTIP notification copy to the attendee's schedule-inbox.
     # Clients do not need to explicitly accept from the inbox (auto-accept is done),
     # but inbox items do appear.  This is "quirk" behaviour: both delivery modes happen.
+    "scheduling.mailbox": True,
     "scheduling.mailbox.inbox-delivery": {
         "support": "quirk",
         "behaviour": "server delivers iTIP notification to inbox AND auto-schedules into calendar",
@@ -1141,6 +1144,7 @@ def dotted_feature_set_list(self, compact=False):
     "http.multiplexing": { "support": "unsupported" },
     # DAViCal delivers iTIP notifications to the attendee inbox AND auto-schedules
     # into their calendar (quirk: both delivery modes happen simultaneously).
+    "scheduling.mailbox": True,
     "scheduling.mailbox.inbox-delivery": {"support": "quirk", "behaviour": "server delivers iTIP notification to inbox AND auto-schedules into calendar"},
     "search.comp-type.optional": { "support": "fragile" },
     "search.recurrences.expanded.exception": { "support": "unsupported" },
@@ -1326,7 +1330,7 @@ def dotted_feature_set_list(self, compact=False):
 davis = {
     # Davis uses sabre/dav (same backend as Baikal): delivers iTIP notifications to the
     # attendee inbox AND auto-schedules into their calendar (quirk behaviour).
-    "scheduling": True,
+    "scheduling.mailbox": True,
     "scheduling.mailbox.inbox-delivery": {"support": "quirk", "behaviour": "server delivers iTIP notification to inbox AND auto-schedules into calendar"},
     "search.recurrences.expanded.todo": {"support": "unsupported"},
     "search.recurrences.expanded.exception": {"support": "unsupported"},

examples/calendar_owner_examples.py

@@ -0,0 +1,101 @@
+"""
+Examples for finding the owner of a calendar and looking up their address.
+
+Use case: when a calendar is shared with you, you may want to know who owns
+it and how to reach them.
+
+See also: https://github.com/python-caldav/caldav/issues/544
+"""
+
+import sys
+
+sys.path.insert(0, "..")
+sys.path.insert(0, ".")
+
+import caldav
+from caldav import get_davclient
+from caldav.elements import dav
+
+
+def find_calendar_owner(calendar):
+    """
+    Return the owner URL of a calendar.
+
+    Uses the DAV:owner property (WebDAV RFC 4918, section 14.17).  The owner
+    is returned as a URL string pointing to the owner's principal resource.
+    Returns None if the server does not expose the property.
+
+    Args:
+        calendar: a :class:`caldav.Calendar` object
+
+    Returns:
+        str | None: the owner's principal URL, or None
+    """
+    return calendar.get_property(dav.Owner())
+
+
+def find_calendar_owner_address(calendar):
+    """
+    Return the calendar-user-address (typically an e-mail URI like
+    ``mailto:user@example.com``) of a calendar's owner.
+
+    This is a two-step operation:
+
+    1. Fetch the DAV:owner property of the calendar to get the owner's
+       principal URL.
+    2. Construct a :class:`caldav.Principal` from that URL and call
+       :meth:`~caldav.Principal.get_vcal_address` to retrieve the
+       ``calendar-user-address-set`` property (RFC 6638 section 2.4.1).
+
+    Requires the server to support both the DAV:owner property and the
+    ``CALDAV:calendar-user-address-set`` principal property.  Returns None
+    when either piece of information is unavailable.
+
+    Args:
+        calendar: a :class:`caldav.Calendar` object
+
+    Returns:
+        icalendar.vCalAddress | None: the owner's calendar address, or None
+    """
+    owner_url = find_calendar_owner(calendar)
+    if owner_url is None:
+        return None
+
+    owner_principal = caldav.Principal(client=calendar.client, url=owner_url)
+    try:
+        return owner_principal.get_vcal_address()
+    except Exception:
+        return None
+
+
+def run_examples():
+    """
+    Run the calendar-owner examples against a live server.
+
+    Connects via :func:`caldav.get_davclient` (reads credentials from the
+    environment or config file), creates a temporary calendar, and
+    demonstrates how to retrieve its owner URL and calendar-user address.
+    """
+    with get_davclient() as client:
+        principal = client.principal()
+        calendar = principal.make_calendar(name="Owner example calendar")
+        try:
+            owner_url = find_calendar_owner(calendar)
+            if owner_url is not None:
+                print(f"Calendar owner URL: {owner_url}")
+
+                owner_address = find_calendar_owner_address(calendar)
+                if owner_address is not None:
+                    print(f"Calendar owner address: {owner_address}")
+                else:
+                    print(
+                        "Calendar owner address: not available (server may not support calendar-user-address-set)"
+                    )
+            else:
+                print("DAV:owner property not exposed by this server")
+        finally:
+            calendar.delete()
+
+
+if __name__ == "__main__":
+    run_examples()

tests/test_caldav.py

@@ -1198,7 +1198,17 @@ def testSchedulingMailboxes(self):
     def testFindCalendarOwner(self):
         cal = self._fixCalendar()
         owner = cal.get_property(dav.Owner())
-        ## TODO: something should probably be asserted about the Owner
+        ## Not all servers expose the DAV:owner property; None is acceptable.
+        if owner is None:
+            return
+
+        ## The owner URL should point to a principal resource.
+        ## Constructing a Principal from it and fetching the vcal address
+        ## demonstrates the full workflow from issue #544.
+        if self.is_supported("scheduling.calendar-user-address-set"):
+            owner_principal = Principal(client=self.caldav, url=owner)
+            address = owner_principal.get_vcal_address()
+            assert address is not None
 
     def testIssue397(self):
         self.skip_unless_support("save-load.event.recurrences.exception")

tests/test_examples.py

@@ -56,3 +56,8 @@ def test_collation(self):
 
     def test_rfc8764_test_conf(self):
         pass
+
+    def test_calendar_owner_examples(self):
+        from examples import calendar_owner_examples
+
+        calendar_owner_examples.run_examples()