Refactor domain objects and core library; remove deprecated objects module

- Refined dual-mode sync/async API consistency across collection.py,
  calendarobjectresource.py, davobject.py
- Remove caldav/objects.py (deprecated aliases module)
- Update caldav/__init__.py exports accordingly
- Various fixes in config.py, lib/url.py, lib/vcal.py discovered during
  testing against multiple servers

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

Author: tobixen

caldav/__init__.py

@@ -1,4 +1,15 @@
 #!/usr/bin/env python
+"""
+caldav — CalDAV client library for Python.
+
+Heavy dependencies (niquests, icalendar, lxml) are loaded lazily on first
+use via PEP 562 module-level ``__getattr__``.  This keeps ``import caldav``
+fast even on constrained hardware.
+"""
+
+from __future__ import annotations
+
+import importlib
 import logging
 
 try:
@@ -8,16 +19,10 @@
     import warnings
 
     warnings.warn(
-        "You need to install the `build` package and do a `python -m build` to get caldav.__version__ set correctly"
+        "You need to install the `build` package and do a `python -m build` "
+        "to get caldav.__version__ set correctly"
     )
-from .davclient import DAVClient, get_calendar, get_calendars, get_davclient
 
-## TODO: this should go away in some future version of the library.
-from .objects import *
-from .search import CalDAVSearcher
-
-## We should consider if the NullHandler-logic below is needed or not, and
-## if there are better alternatives?
 # Silence notification of no default logging handler
 log = logging.getLogger("caldav")
 
@@ -29,4 +34,65 @@ def emit(self, record) -> None:
 
 log.addHandler(NullHandler())
 
-__all__ = ["__version__", "DAVClient", "get_davclient", "get_calendars", "get_calendar"]
+# ---------------------------------------------------------------------------
+# Lazy import machinery (PEP 562)
+# ---------------------------------------------------------------------------
+# Maps public attribute names to the *caldav* submodule that provides them.
+_LAZY_IMPORTS: dict[str, str] = {
+    # davclient
+    "DAVClient": "caldav.davclient",
+    "get_calendar": "caldav.davclient",
+    "get_calendars": "caldav.davclient",
+    "get_davclient": "caldav.davclient",
+    # base_client
+    "CalendarCollection": "caldav.base_client",
+    "CalendarResult": "caldav.base_client",
+    # collection
+    "Calendar": "caldav.collection",
+    "CalendarSet": "caldav.collection",
+    "Principal": "caldav.collection",
+    "ScheduleMailbox": "caldav.collection",
+    "ScheduleInbox": "caldav.collection",
+    "ScheduleOutbox": "caldav.collection",
+    "SynchronizableCalendarObjectCollection": "caldav.collection",
+    # davobject
+    "DAVObject": "caldav.davobject",
+    # calendarobjectresource
+    "CalendarObjectResource": "caldav.calendarobjectresource",
+    "Event": "caldav.calendarobjectresource",
+    "Todo": "caldav.calendarobjectresource",
+    "Journal": "caldav.calendarobjectresource",
+    "FreeBusy": "caldav.calendarobjectresource",
+    # search
+    "CalDAVSearcher": "caldav.search",
+}
+
+# Submodules accessible as attributes (e.g. ``caldav.error``).
+_LAZY_SUBMODULES: set[str] = {"error"}
+
+__all__ = [
+    "__version__",
+    *_LAZY_IMPORTS,
+]
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_IMPORTS:
+        module = importlib.import_module(_LAZY_IMPORTS[name])
+        attr = getattr(module, name)
+        # Cache on the module so __getattr__ is not called again.
+        globals()[name] = attr
+        return attr
+
+    if name in _LAZY_SUBMODULES:
+        module = importlib.import_module(f"caldav.lib.{name}")
+        globals()[name] = module
+        return module
+
+    raise AttributeError(f"module 'caldav' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    # Expose lazy names alongside the eagerly-defined ones.
+    eager = list(globals())
+    return sorted(set(eager + list(_LAZY_IMPORTS) + list(_LAZY_SUBMODULES)))

caldav/calendarobjectresource.py

@@ -704,6 +704,28 @@ def load(self, only_if_unloaded: bool = False) -> Self:
                 raise error.NotFoundError(errmsg(r))
             self.data = r.raw  # type: ignore
         except error.NotFoundError:
+            # Only attempt fallbacks if the object was previously loaded
+            # (has a UID), indicating the server may have changed the URL.
+            # Without a UID, the 404 is definitive.
+            uid = self.id
+            if uid:
+                # Fallback 1: try multiget (REPORT may work even when GET fails)
+                try:
+                    return self.load_by_multiget()
+                except Exception:
+                    pass
+                # Fallback 2: re-fetch by UID (server may have changed the URL)
+                if self.parent and hasattr(self.parent, "get_object_by_uid"):
+                    try:
+                        obj = self.parent.get_object_by_uid(uid)
+                        if obj:
+                            self.url = obj.url
+                            self.data = obj.data
+                            if hasattr(obj, "props"):
+                                self.props.update(obj.props)
+                            return self
+                    except error.NotFoundError:
+                        pass
             raise
         except Exception:
             return self.load_by_multiget()
@@ -730,6 +752,19 @@ async def _async_load(self, only_if_unloaded: bool = False) -> Self:
                 raise error.NotFoundError(errmsg(r))
             self.data = r.raw  # type: ignore
         except error.NotFoundError:
+            # Fallback: re-fetch by UID (server may have changed the URL)
+            uid = self.id
+            if uid and self.parent and hasattr(self.parent, "get_object_by_uid"):
+                try:
+                    obj = await self.parent.get_object_by_uid(uid)
+                    if obj:
+                        self.url = obj.url
+                        self.data = obj.data
+                        if hasattr(obj, "props"):
+                            self.props.update(obj.props)
+                        return self
+                except error.NotFoundError:
+                    pass
             raise
         except Exception:
             # Note: load_by_multiget is sync-only, not supported in async mode yet
@@ -862,7 +897,9 @@ def _generate_url(self):
         ## See https://github.com/python-caldav/caldav/issues/143 for the rationale behind double-quoting slashes
         ## TODO: should try to wrap my head around issues that arises when id contains weird characters.  maybe it's
         ## better to generate a new uuid here, particularly if id is in some unexpected format.
-        return self.parent.url.join(quote(self.id.replace("/", "%2F")) + ".ics")
+        url = self.parent.url.join(quote(self.id.replace("/", "%2F")) + ".ics")
+        assert " " not in str(url)
+        return url
 
     def change_attendee_status(self, attendee: Any | None = None, **kwargs) -> None:
         """
@@ -950,11 +987,7 @@ def save(
 
         """
         # Early return if there's no data (no-op case)
-        if (
-            self._vobject_instance is None
-            and self._data is None
-            and self._icalendar_instance is None
-        ):
+        if not self.is_loaded():
             return self
 
         # Helper function to get the full object by UID

caldav/collection.py

@@ -421,6 +421,10 @@ async def _async_get_calendar_home_set(self) -> "CalendarSet":
         self.calendar_home_set = calendar_home_set_url
         return self._calendar_home_set
 
+    ## TODO: the parameter names name, cal_id and cal_url is quite inconsistent
+    ## I think it was made so to make sure the calendar URL was not mixed up
+    ## with the caldav base URL - but I still think we should reconsider this
+    ## parameter naming
     def calendar(
         self,
         name: str | None = None,
@@ -754,7 +758,7 @@ def delete(self):
         ## TODO: remove quirk handling from the functional tests
         ## TODO: this needs test code
         quirk_info = self.client.features.is_supported("delete-calendar", dict)
-        wipe = quirk_info["support"] in ("unsupported", "fragile")
+        wipe = not self.client.features.is_supported("delete-calendar")
         if quirk_info["support"] == "fragile":
             ## Do some retries on deleting the calendar
             for x in range(0, 20):
@@ -776,42 +780,31 @@ def delete(self):
             super().delete()
 
     async def _async_calendar_delete(self):
-        """Async implementation of Calendar.delete().
+        """Async implementation of Calendar.delete()."""
+        import asyncio
 
-        Note: Server quirk handling (fragile/wipe modes) is simplified for async.
-        Most modern servers support proper calendar deletion.
-        """
         quirk_info = self.client.features.is_supported("delete-calendar", dict)
+        wipe = not self.client.features.is_supported("delete-calendar")
 
-        # For fragile servers, try simple delete first
         if quirk_info["support"] == "fragile":
-            for _ in range(0, 5):
+            # Do some retries on deleting the calendar
+            for _ in range(0, 20):
                 try:
                     await self._async_delete()
-                    return
                 except error.DeleteError:
-                    import asyncio
-
+                    pass
+                try:
+                    await self.search(event=True)
                     await asyncio.sleep(0.3)
-            # If still failing after retries, fall through to wipe
-
-        if quirk_info["support"] in ("unsupported", "fragile"):
-            # Need to delete all objects first
-            # Use the async client's get_events method
-            try:
-                events = await self.client.get_events(self)
-                for event in events:
-                    await event._async_delete()
-            except Exception:
-                pass  # Best effort
-            try:
-                todos = await self.client.get_todos(self)
-                for todo in todos:
-                    await todo._async_delete()
-            except Exception:
-                pass  # Best effort
+                except error.NotFoundError:
+                    wipe = False
+                    break
 
-        await self._async_delete()
+        if wipe:
+            for obj in await self.search():
+                await obj._async_delete()
+        else:
+            await self._async_delete()
 
     def get_supported_components(self) -> list[Any]:
         """
@@ -1036,9 +1029,11 @@ def multiget(self, event_urls: Iterable[URL], raise_notfound: bool = False) -> I
         """
         results = self._multiget(event_urls, raise_notfound=raise_notfound)
         for url, data in results:
+            # Quote path to handle servers returning unencoded spaces (e.g., Zimbra)
+            quoted_url = quote(unquote(str(url)), safe="/:@")
             yield self._calendar_comp_class_by_data(data)(
                 self.client,
-                url=self.url.join(url),
+                url=self.url.join(quoted_url),
                 data=data,
                 parent=self,
             )
@@ -1526,21 +1521,18 @@ def get_object_by_uid(
         Returns:
          CalendarObjectResource (Event, Todo, or Journal)
         """
-        ## late import to avoid cyclic dependencies
-        from .search import CalDAVSearcher
-
-        ## 2025-11: some logic validating the comp_filter and
-        ## comp_class has been removed, and replaced with the
-        ## recommendation not to use comp_filter.  We're still using
-        ## comp_filter internally, but it's OK, it doesn't need to be
-        ## validated.
-
-        ## Lots of old logic has been removed, the new search logic
-        ## can do the things for us:
-        searcher = CalDAVSearcher(comp_class=comp_class)
-        ## Default is substring
-        searcher.add_property_filter("uid", uid, "==")
-        items_found = searcher.search(self, xml=comp_filter, _hacks="insist", post_filter=True)
+        ## Use self.search() rather than CalDAVSearcher directly, so that any
+        ## monkey-patching of Calendar.search (e.g. the search-cache delay for
+        ## servers with lazy search indexes) is respected.  This mirrors the
+        ## pattern used in get_todos() and get_events().
+        ##
+        ## search(uid=...) does substring matching on the server side, so we
+        ## apply an exact match filter afterwards to preserve the semantics of
+        ## this method (see testObjectByUID).
+        items_found = self.search(
+            uid=uid, comp_class=comp_class, xml=comp_filter, post_filter=True, _hacks="insist"
+        )
+        items_found = [o for o in items_found if o.id == uid]
 
         if not items_found:
             raise error.NotFoundError("%s not found on server" % uid)