refactor: scrap operations and protocol

After an audit of caldav/operations/ and caldav/protocol/ (documented in
docs/design/OPERATIONS_PROTOCOL_AUDIT.md), both directories are deleted,
the code that was in use have been moved elsewhere.

The code changes are predominantly AI-written.  Tedious refactoring
work, 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.

prompt: During the great attempt on Sans-IO refactoring, a directory
`caldav/operations/` was made. Please check up how much code is
duplicated and/or dead there, and come with recommendations on whether
to keep "operations" there or not. Same with the protocols folder.
followup-prompt: Save the analysis to the docs/design folder
followup-prompt: Kill the operations directory ref the document
followup-prompt: All response-related logic in the protocol directory
should be moved back to the response class. Make sure there is no
duplicated code or logic.
followup-prompt: move xml builders to the dav base client, and ensure
sync and async code paths uses the same builder methods
prompt: Deal with the code duplication in response.py
followup-prompt: It seems like the last commit, with purpose "remove code duplication in response.py" has more code additions than removed code?

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

Author: tobixen

caldav/async_davclient.py

@@ -71,6 +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.requests import HTTPBearerAuth
 from caldav.response import CalendarQueryResult, DAVResponse, PropfindResult
 
@@ -517,19 +519,13 @@ 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)
 
-        # Parse response using protocol layer
         if response.status in (200, 207) and response._raw:
-            raw_bytes = (
-                response._raw if isinstance(response._raw, bytes) else response._raw.encode("utf-8")
-            )
-            response.results = _parse_propfind_response(
-                raw_bytes, response.status, response.huge_tree
-            )
+            response.results = response.parse_propfind()
 
         return response
 
@@ -725,7 +721,7 @@ async def calendar_query(
             DAVResponse with results containing List[CalendarQueryResult].
         """
 
-        body, _ = _build_calendar_query_body(
+        body, _ = self._build_calendar_query_body(
             start=start,
             end=end,
             event=event,
@@ -739,14 +735,8 @@ async def calendar_query(
             url or str(self.url), "REPORT", body.decode("utf-8"), final_headers
         )
 
-        # Parse response using protocol layer
         if response.status in (200, 207) and response._raw:
-            raw_bytes = (
-                response._raw if isinstance(response._raw, bytes) else response._raw.encode("utf-8")
-            )
-            response.results = _parse_calendar_query_response(
-                raw_bytes, response.status, response.huge_tree
-            )
+            response.results = response.parse_calendar_query()
 
         return response
 
@@ -769,21 +759,15 @@ async def calendar_multiget(
         Returns:
             DAVResponse 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(
             url or str(self.url), "REPORT", body.decode("utf-8"), final_headers
         )
 
-        # Parse response using protocol layer
         if response.status in (200, 207) and response._raw:
-            raw_bytes = (
-                response._raw if isinstance(response._raw, bytes) else response._raw.encode("utf-8")
-            )
-            response.results = _parse_calendar_query_response(
-                raw_bytes, response.status, response.huge_tree
-            )
+            response.results = response.parse_calendar_query()
 
         return response
 
@@ -808,21 +792,15 @@ async def sync_collection(
         Returns:
             DAVResponse 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(
             url or str(self.url), "REPORT", body.decode("utf-8"), final_headers
         )
 
-        # Parse response using protocol layer
         if response.status in (200, 207) and response._raw:
-            raw_bytes = (
-                response._raw if isinstance(response._raw, bytes) else response._raw.encode("utf-8")
-            )
-            sync_result = _parse_sync_collection_response(
-                raw_bytes, response.status, response.huge_tree
-            )
+            sync_result = response.parse_sync_collection()
             response.results = sync_result.changed
             response.sync_token = sync_result.sync_token
 
@@ -934,12 +912,12 @@ async def get_calendars(self, principal: Optional["Principal"] = None) -> list["
                 print(f"Calendar: {cal.get_display_name()}")
         """
         from caldav.collection import Calendar
-        from caldav.operations.calendarset_ops import (
-            _extract_calendars_from_propfind_results as extract_calendars,
-        )
-        from caldav.operations.principal_ops import (
+        from caldav.collection import (
             _extract_calendar_home_set_from_results as extract_home_set,
         )
+        from caldav.collection import (
+            _extract_calendars_from_propfind_results as extract_calendars,
+        )
 
         if principal is None:
             principal = await self.get_principal()

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.
@@ -214,12 +255,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(value=sync_token or ""),
+            dav.SyncLevel(value=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/calendarobjectresource.py

@@ -18,7 +18,7 @@
 from collections import defaultdict
 from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any, ClassVar, Optional
-from urllib.parse import ParseResult, SplitResult
+from urllib.parse import ParseResult, SplitResult, quote
 
 import icalendar
 from dateutil.rrule import rrulestr
@@ -47,11 +47,19 @@
 from .lib.error import errmsg
 from .lib.python_utilities import to_normal_str, to_unicode, to_wire
 from .lib.url import URL
-from .operations.calendarobject_ops import _quote_uid
 
 log = logging.getLogger("caldav")
 
 
+def _quote_uid(uid: str) -> str:
+    """URL-quote a UID for use in a CalDAV object URL.
+
+    Slashes are double-quoted (replaced with %2F before percent-encoding)
+    per https://github.com/python-caldav/caldav/issues/143.
+    """
+    return quote(uid.replace("/", "%2F"))
+
+
 class CalendarObjectResource(DAVObject):
     """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