fix: Restore communication dump to sync and async request paths

The debug_dump_communication / PYTHON_CALDAV_COMMDUMP feature was lost
during the v3.0 refactor.  Extract it into a shared _dump_communication()
helper in caldav.lib.error so the logic is not duplicated between the
sync (_sync_request) and async (_async_request) code paths.

Fixes #638

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

Author: tobixen

CHANGELOG.md

@@ -14,6 +14,10 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 
 ## [Unreleased]
 
+### Fixed
+
+* Communication dump (`PYTHON_CALDAV_COMMDUMP` / `debug_dump_communication`) was accidentally dropped during the v3.0 refactor.  Restored, with the dump logic extracted into a shared helper so both the sync and async code paths benefit.  Fixes https://github.com/python-caldav/caldav/issues/638
+
 ### Documentation
 
 I've decided to try to stick to the conventionalcommits standard.  This is documented in CONTRIBUTING.md.  We'll see how many days it takes before I forget about it ...

caldav/async_davclient.py

@@ -527,6 +527,9 @@ async def _async_request(
         if response.status in (401, 403):
             self._raise_authorization_error(str(url_obj), response)
 
+        if error.debug_dump_communication:
+            error._dump_communication(method, url, combined_headers, body, response)
+
         return response
 
     # ==================== HTTP Method Wrappers ====================

caldav/davclient.py

@@ -936,6 +936,10 @@ def _sync_request(
             self._raise_authorization_error(str(url_obj), r)
 
         response = DAVResponse(r, self)
+
+        if error.debug_dump_communication:
+            error._dump_communication(method, url, combined_headers, body, response)
+
         return response
 
 

caldav/lib/error.py

@@ -34,6 +34,40 @@ def errmsg(r) -> str:
     return "%s %s\n\n%s" % (r.status, r.reason, r.raw)
 
 
+def _dump_communication(method: str, url: str, combined_headers: dict, body, response) -> None:
+    """Write a request/response exchange to a uniquely-named temp file.
+
+    Called when ``debug_dump_communication`` is truthy.  Works for both the
+    sync and async code paths because it only depends on the attributes that
+    ``BaseDAVResponse`` exposes: ``.status``, ``.reason``, ``.headers``,
+    ``.tree``, and ``._raw``.
+    """
+    import datetime
+    from tempfile import NamedTemporaryFile
+
+    from lxml import etree
+
+    from caldav.lib.python_utilities import to_wire
+
+    with NamedTemporaryFile(prefix="caldavcomm", delete=False) as commlog:
+        commlog.write(b"=" * 80 + b"\n")
+        commlog.write(f"{datetime.datetime.now():%FT%H:%M:%S}".encode())
+        commlog.write(b"\n====>\n")
+        commlog.write(f"{method} {url}\n".encode())
+        commlog.write(b"\n".join(to_wire(f"{k}: {v}") for k, v in combined_headers.items()))
+        commlog.write(b"\n\n")
+        commlog.write(to_wire(body) or b"")
+        commlog.write(b"\n<====\n")
+        commlog.write(f"{response.status} {response.reason}\n".encode())
+        commlog.write(b"\n".join(to_wire(f"{k}: {v}") for k, v in response.headers.items()))
+        commlog.write(b"\n\n")
+        if response.tree is not None:
+            commlog.write(to_wire(etree.tostring(response.tree, pretty_print=True)))
+        else:
+            commlog.write(to_wire(response._raw) or b"")
+        commlog.write(b"\n")
+
+
 def weirdness(*reasons):
     from caldav.lib.debug import xmlstring
 

tests/test_caldav_unit.py

@@ -415,6 +415,40 @@ def testNonValidXMLNoContentLength(self, mocked):
         with pytest.raises(lxml.etree.XMLSyntaxError):
             client.request("/")
 
+    @mock.patch("caldav.davclient.requests.Session.request")
+    def testCommunicationDump(self, mocked):
+        """
+        ref https://github.com/python-caldav/caldav/issues/638
+        When PYTHON_CALDAV_COMMDUMP (or debug_dump_communication) is set,
+        request/response data should be written to a temp file.
+        """
+        import glob
+        import os
+        import tempfile
+
+        mocked().status_code = 200
+        mocked().headers = {"Content-Type": "text/plain"}
+        mocked().content = b""
+        mocked().reason = "OK"
+        mocked().reason_phrase = None
+
+        from caldav.lib import error as caldav_error
+
+        old_value = caldav_error.debug_dump_communication
+        caldav_error.debug_dump_communication = True
+        try:
+            client = DAVClient(url="http://test.example.com/")
+            before = set(glob.glob(os.path.join(tempfile.gettempdir(), "caldavcomm*")))
+            client.request("/")
+            after = set(glob.glob(os.path.join(tempfile.gettempdir(), "caldavcomm*")))
+            new_files = after - before
+            assert len(new_files) == 1
+            content = open(list(new_files)[0], "rb").read()
+            assert b"GET /" in content
+            assert b"200 OK" in content
+        finally:
+            caldav_error.debug_dump_communication = old_value
+
     def testPathWithEscapedCharacters(self):
         xml = b"""<D:multistatus xmlns:D="DAV:" xmlns:caldav="urn:ietf:params:xml:ns:caldav" xmlns:cs="http://calendarserver.org/ns/" xmlns:ical="http://apple.com/ns/ical/">
   <D:response xmlns:carddav="urn:ietf:params:xml:ns:carddav" xmlns:cm="http://cal.me.com/_namespace/" xmlns:md="urn:mobileme:davservices">