refactor: move XML builders to BaseDAVClient, delete protocol/ package

All XML request-body builder functions are now static methods on
BaseDAVClient so both DAVClient (sync) and AsyncDAVClient (async)
inherit the same implementations:

  _build_propfind_body, _build_proppatch_body,
  _build_calendar_query_body, _build_calendar_multiget_body,
  _build_sync_collection_body, _build_mkcalendar_body

The _prop_name_to_element helper is a module-level function in
base_client.py called by the builders.

Updated callers:
- async_davclient.py: dropped protocol.xml_builders import; uses
  self._build_* throughout (propfind, calendar_query, calendar_multiget,
  sync_collection)
- davclient.py: dropped late import in propfind(); uses
  self._build_propfind_body
- collection.py: both sync and async synchronize() now call
  self.client._build_sync_collection_body() instead of building the
  sync-collection element tree inline

The caldav/protocol/ package is now empty and deleted entirely.
test_protocol.py imports the builders directly from BaseDAVClient.

prompt: move xml builders to the dav base client, and ensure sync and async code paths uses the same builder methods

AI Prompts:
claude-sonnet-4-6: For the xml building, do some more research: why is this needed for the async davclient, but not for the sync davclient?  The async and sync davclient classes should be as similar as possible, and all non-IO-related logic should be consolidated.  I don't think it needs a separate directory for xmlbuilding logic though.  Would it make sense moving it to the davclient baseclass?  Where else in the code do we build XML structures?  Can things be consolidated further?  If we are to have an xmlbuilder.py or something, then it xml building logic from everywhere should be moved/consolidated into that file.
claude-sonnet-4-6: move xml builders to the dav base client, and ensure sync and async code paths uses the same builder methods

Author: tobixen

caldav/async_davclient.py

@@ -71,12 +71,6 @@ def auth_flow(self, request):
 from caldav.lib import error
 from caldav.lib.python_utilities import to_wire
 from caldav.lib.url import URL
-from caldav.protocol.xml_builders import (
-    _build_calendar_multiget_body,
-    _build_calendar_query_body,
-    _build_propfind_body,
-    _build_sync_collection_body,
-)
 from caldav.requests import HTTPBearerAuth
 from caldav.response import BaseDAVResponse, CalendarQueryResult, PropfindResult
 
@@ -548,7 +542,7 @@ async def propfind(
         """
         # Use protocol layer to build XML if props provided
         if props is not None and not body:
-            body = _build_propfind_body(props).decode("utf-8")
+            body = self._build_propfind_body(props).decode("utf-8")
 
         final_headers = self._build_method_headers("PROPFIND", depth, headers)
         response = await self.request(url or str(self.url), "PROPFIND", body, final_headers)
@@ -750,7 +744,7 @@ async def calendar_query(
             AsyncDAVResponse with results containing List[CalendarQueryResult].
         """
 
-        body, _ = _build_calendar_query_body(
+        body, _ = self._build_calendar_query_body(
             start=start,
             end=end,
             event=event,
@@ -788,7 +782,7 @@ async def calendar_multiget(
         Returns:
             AsyncDAVResponse with results containing List[CalendarQueryResult].
         """
-        body = _build_calendar_multiget_body(hrefs or [])
+        body = self._build_calendar_multiget_body(hrefs or [])
 
         final_headers = self._build_method_headers("REPORT", depth, headers)
         response = await self.request(
@@ -821,7 +815,7 @@ async def sync_collection(
         Returns:
             AsyncDAVResponse with results containing SyncCollectionResult.
         """
-        body = _build_sync_collection_body(sync_token=sync_token, props=props)
+        body = self._build_sync_collection_body(sync_token=sync_token, props=props)
 
         final_headers = self._build_method_headers("REPORT", depth, headers)
         response = await self.request(

caldav/base_client.py

@@ -10,8 +10,13 @@
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import Mapping
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, NoReturn
 
+from lxml import etree
+
+from caldav.elements import cdav, dav
+from caldav.elements.base import BaseElement
 from caldav.lib import error
 from caldav.lib.auth import extract_auth_types, select_auth_type
 from caldav.lib.python_utilities import to_normal_str
@@ -26,6 +31,42 @@
 ICALH = {"Content-Type": 'text/calendar; charset="utf-8"'}
 
 
+def _prop_name_to_element(name: str, value: Any | None = None) -> BaseElement | None:
+    """Convert a property name string (plain or Clark-notation) to a DAV element object."""
+    dav_props: dict[str, Any] = {
+        "displayname": dav.DisplayName,
+        "resourcetype": dav.ResourceType,
+        "getetag": dav.GetEtag,
+        "current-user-principal": dav.CurrentUserPrincipal,
+        "owner": dav.Owner,
+        "sync-token": dav.SyncToken,
+        "supported-report-set": dav.SupportedReportSet,
+    }
+    caldav_props: dict[str, Any] = {
+        "calendar-data": cdav.CalendarData,
+        "calendar-home-set": cdav.CalendarHomeSet,
+        "calendar-user-address-set": cdav.CalendarUserAddressSet,
+        "calendar-user-type": cdav.CalendarUserType,
+        "calendar-description": cdav.CalendarDescription,
+        "calendar-timezone": cdav.CalendarTimeZone,
+        "supported-calendar-component-set": cdav.SupportedCalendarComponentSet,
+        "schedule-inbox-url": cdav.ScheduleInboxURL,
+        "schedule-outbox-url": cdav.ScheduleOutboxURL,
+    }
+    # Strip Clark-notation namespace prefix: "{DAV:}displayname" → "displayname"
+    if name.startswith("{") and "}" in name:
+        name = name.split("}", 1)[1]
+    name_lower = name.lower().replace("_", "-")
+    for props_dict in (dav_props, caldav_props):
+        if name_lower in props_dict:
+            cls = props_dict[name_lower]
+            try:
+                return cls(value) if value is not None else cls()
+            except TypeError:
+                return cls()
+    return None
+
+
 class BaseDAVClient(ABC):
     """
     Base class for DAV clients providing shared authentication and configuration logic.
@@ -196,12 +237,148 @@ def _raise_authorization_error(self, url_str: str, reason_source: Any) -> NoRetu
             reason = "None given"
         raise error.AuthorizationError(url=url_str, reason=reason)
 
-    def _build_principal_search_query(self, name: str | None) -> bytes:
-        """Build the XML body for a principal-property-search REPORT."""
-        from lxml import etree
-
-        from caldav.elements import cdav, dav
+    # ── XML builders ──────────────────────────────────────────────────────────
+    # All methods are static: no I/O, no server interaction, pure data
+    # transformation.  Both DAVClient and AsyncDAVClient inherit these so
+    # every code path that builds request XML uses the same implementation.
+
+    @staticmethod
+    def _build_propfind_body(
+        props: list[str] | None = None,
+        allprop: bool = False,
+    ) -> bytes:
+        """Build PROPFIND request body XML."""
+        if allprop:
+            propfind = dav.Propfind() + dav.Allprop()
+        elif props:
+            prop_elements = [e for name in props if (e := _prop_name_to_element(name)) is not None]
+            propfind = dav.Propfind() + (dav.Prop() + prop_elements)
+        else:
+            propfind = dav.Propfind() + dav.Prop()
+        return etree.tostring(propfind.xmlelement(), encoding="utf-8", xml_declaration=True)
+
+    @staticmethod
+    def _build_proppatch_body(set_props: dict[str, Any] | None = None) -> bytes:
+        """Build PROPPATCH request body for setting properties."""
+        propertyupdate = dav.PropertyUpdate()
+        if set_props:
+            set_elements = [
+                e
+                for name, value in set_props.items()
+                if (e := _prop_name_to_element(name, value)) is not None
+            ]
+            if set_elements:
+                propertyupdate += dav.Set() + (dav.Prop() + set_elements)
+        return etree.tostring(propertyupdate.xmlelement(), encoding="utf-8", xml_declaration=True)
+
+    @staticmethod
+    def _build_calendar_query_body(
+        start: datetime | None = None,
+        end: datetime | None = None,
+        expand: bool = False,
+        comp_filter: str | None = None,
+        event: bool = False,
+        todo: bool = False,
+        journal: bool = False,
+        props: list[BaseElement] | None = None,
+        filters: list[BaseElement] | None = None,
+    ) -> tuple[bytes, str | None]:
+        """Build calendar-query REPORT request body.
+
+        Returns (XML bytes, component type name or None).
+        """
+        data = cdav.CalendarData()
+        if expand:
+            if not start or not end:
+                raise error.ReportError("can't expand without a date range")
+            data += cdav.Expand(start, end)
+
+        props_list: list[BaseElement] = [data] + (list(props) if props else [])
+        prop = dav.Prop() + props_list
+
+        vcalendar = cdav.CompFilter("VCALENDAR")
+        comp_type = comp_filter or (
+            "VEVENT" if event else "VTODO" if todo else "VJOURNAL" if journal else None
+        )
+        filter_list: list[BaseElement] = list(filters) if filters else []
+        if start or end:
+            filter_list.append(cdav.TimeRange(start, end))
+
+        if comp_type:
+            comp_filter_elem = cdav.CompFilter(comp_type)
+            if filter_list:
+                comp_filter_elem += filter_list
+            vcalendar += comp_filter_elem
+        elif filter_list:
+            vcalendar += filter_list
+
+        root = cdav.CalendarQuery() + [prop, cdav.Filter() + vcalendar]
+        return (
+            etree.tostring(root.xmlelement(), encoding="utf-8", xml_declaration=True),
+            comp_type,
+        )
 
+    @staticmethod
+    def _build_calendar_multiget_body(
+        hrefs: list[str],
+        include_data: bool = True,
+    ) -> bytes:
+        """Build calendar-multiget REPORT request body."""
+        elements: list[BaseElement] = []
+        if include_data:
+            elements.append(dav.Prop() + cdav.CalendarData())
+        for href in hrefs:
+            elements.append(dav.Href(href))
+        multiget = cdav.CalendarMultiGet() + elements
+        return etree.tostring(multiget.xmlelement(), encoding="utf-8", xml_declaration=True)
+
+    @staticmethod
+    def _build_sync_collection_body(
+        sync_token: str | None = None,
+        props: list[str] | None = None,
+        sync_level: str = "1",
+    ) -> bytes:
+        """Build sync-collection REPORT request body."""
+        elements: list[BaseElement] = [
+            dav.SyncToken(sync_token or ""),
+            dav.SyncLevel(sync_level),
+        ]
+        if props:
+            prop_elements = [e for name in props if (e := _prop_name_to_element(name)) is not None]
+            if prop_elements:
+                elements.append(dav.Prop() + prop_elements)
+        else:
+            elements.append(dav.Prop() + [dav.GetEtag(), cdav.CalendarData()])
+        sync_collection = dav.SyncCollection() + elements
+        return etree.tostring(sync_collection.xmlelement(), encoding="utf-8", xml_declaration=True)
+
+    @staticmethod
+    def _build_mkcalendar_body(
+        displayname: str | None = None,
+        description: str | None = None,
+        timezone: str | None = None,
+        supported_components: list[str] | None = None,
+    ) -> bytes:
+        """Build MKCALENDAR request body."""
+        prop = dav.Prop()
+        if displayname:
+            prop += dav.DisplayName(displayname)
+        if description:
+            prop += cdav.CalendarDescription(description)
+        if timezone:
+            prop += cdav.CalendarTimeZone(timezone)
+        if supported_components:
+            sccs = cdav.SupportedCalendarComponentSet()
+            for comp in supported_components:
+                sccs += cdav.Comp(comp)
+            prop += sccs
+        prop += dav.ResourceType() + [dav.Collection(), cdav.Calendar()]
+        mkcalendar = cdav.Mkcalendar() + (dav.Set() + prop)
+        return etree.tostring(mkcalendar.xmlelement(), encoding="utf-8", xml_declaration=True)
+
+    @staticmethod
+    def _build_principal_search_query(name: str | None) -> bytes:
+        """Build the XML body for a principal-property-search REPORT."""
         name_filter = (
             [dav.PropertySearch() + [dav.Prop() + [dav.DisplayName()]] + dav.Match(value=name)]
             if name

caldav/collection.py

@@ -1800,11 +1800,9 @@ def get_objects_by_sync_token(
 
         if use_sync_token:
             try:
-                cmd = dav.SyncCollection()
-                token = dav.SyncToken(value=sync_token)
-                level = dav.SyncLevel(value="1")
-                props = dav.Prop() + dav.GetEtag()
-                root = cmd + [level, token, props]
+                root = self.client._build_sync_collection_body(
+                    sync_token=sync_token, props=["getetag"]
+                )
                 (response, objects) = self._request_report_build_resultlist(
                     root, props=[dav.GetEtag()], no_calendardata=True
                 )
@@ -1931,11 +1929,9 @@ async def _async_get_objects_by_sync_token(
 
         if use_sync_token:
             try:
-                cmd = dav.SyncCollection()
-                token = dav.SyncToken(value=sync_token)
-                level = dav.SyncLevel(value="1")
-                props = dav.Prop() + dav.GetEtag()
-                root = cmd + [level, token, props]
+                root = self.client._build_sync_collection_body(
+                    sync_token=sync_token, props=["getetag"]
+                )
                 (response, objects) = await self._request_report_build_resultlist(
                     root, props=[dav.GetEtag()], no_calendardata=True
                 )

caldav/davclient.py

@@ -703,13 +703,11 @@ def propfind(
         -------
         DAVResponse
         """
-        from caldav.protocol.xml_builders import _build_propfind_body
-
         # Handle both old interface (props=xml_string) and new interface (props=list)
         body = ""
         if props is not None:
             if isinstance(props, list):
-                body = _build_propfind_body(props).decode("utf-8")
+                body = self._build_propfind_body(props).decode("utf-8")
             else:
                 body = props  # Old interface: props is XML string