Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 22 additions & 7 deletions caldav/calendarobjectresource.py
Original file line number Diff line number Diff line change
Expand Up @@ -981,7 +981,10 @@ def copy(self, keep_uid: bool = False, new_parent: Any | None = None) -> Self:
## TODO: move get-logics to a load_by_get method.
## The load method should deal with "server quirks".
def load(
self, only_if_unloaded: bool = False, multiget_fallback: bool = True
self,
only_if_unloaded: bool = False,
multiget_fallback: bool = True,
fallbacks: bool = True,
) -> "Self | Coroutine[Any, Any, Self]":
"""
(Re)load the object from the caldav server.
Expand All @@ -999,6 +1002,13 @@ def load(
on by default. Pass False to see what the server itself
answered - a compatibility checker probing whether a missing
object really raises NotFoundError needs the unrescued error.
A 404 for an object with a UID is still retried as a search by
UID; fallbacks=False is the GET alone.
:param fallbacks: False loads by the GET and nothing else: no
multiget, and no search by UID after a 404 for an object that
has one (which multiget_fallback=False still does). For a
caller that needs the server's own answer to the GET, such as a
compatibility checker comparing it with what a search returns.

Example (sync):
obj.load()
Expand All @@ -1021,7 +1031,9 @@ def load(
# Dual-mode support: async clients return a coroutine
if self.is_async_client:
return self._async_load(
only_if_unloaded=only_if_unloaded, multiget_fallback=multiget_fallback
only_if_unloaded=only_if_unloaded,
multiget_fallback=multiget_fallback,
fallbacks=fallbacks,
)

if self.url is None:
Expand All @@ -1040,7 +1052,7 @@ def load(
# (has a UID), indicating the server may have changed the URL.
# Without a UID, the 404 is definitive.
uid = self.id
if uid:
if uid and fallbacks:
# Fallback 1: try multiget (REPORT may work even when GET fails)
if multiget_fallback:
try:
Expand All @@ -1062,15 +1074,18 @@ def load(
pass
raise
except Exception:
if not multiget_fallback:
if not (multiget_fallback and fallbacks):
raise
return self.load_by_multiget()

self._update_tag_props(r)
return self

async def _async_load(
self, only_if_unloaded: bool = False, multiget_fallback: bool = True
self,
only_if_unloaded: bool = False,
multiget_fallback: bool = True,
fallbacks: bool = True,
) -> Self:
"""Async implementation of load."""
if only_if_unloaded and self.is_loaded():
Expand All @@ -1089,7 +1104,7 @@ async def _async_load(
self._keep_raw_data(getattr(r, "_raw_body", None))
except error.NotFoundError:
uid = self.id
if uid:
if uid and fallbacks:
# Fallback 1: try multiget (REPORT may work even when GET fails)
if multiget_fallback:
try:
Expand All @@ -1111,7 +1126,7 @@ async def _async_load(
pass
raise
except Exception:
if not multiget_fallback:
if not (multiget_fallback and fallbacks):
raise
return await self.load_by_multiget()

Expand Down
22 changes: 12 additions & 10 deletions caldav/compatibility_hints.py
Original file line number Diff line number Diff line change
Expand Up @@ -557,8 +557,8 @@ class FeatureSet:
"REPORT against the parent collection, and a server answering 403 on the object "
"URL may report the missing href with a 404 inside that multistatus (Robur does); "
"read the `behaviour` field for what a given server does. Anything reaching past "
"`load()` sees the raw answer, and `load(multiget_fallback=False)` asks for it "
"deliberately. 'unsupported' when the lookup ends in some other DAVError - "
"`load()` sees the raw answer, and `load(fallbacks=False)` asks for it "
"deliberately (`multiget_fallback=False` still retries a 404 as a search by UID). 'unsupported' when the lookup ends in some other DAVError - "
"typically AuthorizationError, because the server answers 403 rather than 404 to "
"avoid leaking whether a resource exists, which is a legitimate choice rather "
"than an RFC breach, hence 'unsupported' rather than 'broken'."
Expand Down Expand Up @@ -2050,10 +2050,12 @@ def __getattr__(name: str) -> Any:
## 5.x, hence the version-stamped name - a plain `bedework` would be claiming
## far more than we have measured.
bedework_3_10_3 = {
## Measured by hand 2026-11-14 (the conformance suite of calendaring):
## a calendar-query returns the master without the moved occurrence,
## which a GET of the same object has.
## Probed 2026-11-14 by caldav-server-tester: a calendar-query returns
## the master without the moved occurrence, which a GET of the same
## object has. The object keeps both, so the exception is stored
## (save-load.event.recurrences.exception was read off a search before).
"search.recurrences.exception.in-calendar-data": {"support": "unsupported", "behaviour": "the calendar-data of a search holds the master only"},
"save-load.event.recurrences.exception": {"support": "full"},
## Measured with caldav-server-tester, 2026-10-27: the UID filter works although search.text does not.
"search.text.uid": {"support": "full"},
## Probed 2026-10-26 by caldav-server-tester: RFC 4791 section 5.2.3 makes
Expand Down Expand Up @@ -2085,7 +2087,6 @@ def __getattr__(name: str) -> Any:
'auto-connect.url': {'basepath': '/ucaldav/'},
'save-load.journal': {'support': 'ungraceful'},
'save-load.todo.recurrences.thisandfuture': {'support': 'ungraceful'},
'save-load.event.recurrences.exception': {'support': 'unsupported'},
'search.time-range.alarm': {'support': 'unsupported'},
"freebusy-query": True,
"search.time-range.todo": False,
Expand Down Expand Up @@ -2146,10 +2147,12 @@ def __getattr__(name: str) -> Any:
## deletes calendars, its sync-token and text search behave differently - so
## nothing is inherited from that profile.
bedework_5_0_0 = {
## Measured by hand 2026-11-14 (the conformance suite of calendaring):
## a calendar-query returns the master without the moved occurrence,
## which a GET of the same object has.
## Probed 2026-11-14 by caldav-server-tester: a calendar-query returns
## the master without the moved occurrence, which a GET of the same
## object has. The object keeps both, so the exception is stored
## (save-load.event.recurrences.exception was read off a search before).
"search.recurrences.exception.in-calendar-data": {"support": "unsupported", "behaviour": "the calendar-data of a search holds the master only"},
"save-load.event.recurrences.exception": {"support": "full"},
## Probed 2026-11-12 by caldav-server-tester, and by hand on a fresh
## container: a PUT with one ATTENDEE gives two identical ATTENDEE lines
## in GET and calendar-multiget alike.
Expand Down Expand Up @@ -2222,7 +2225,6 @@ def __getattr__(name: str) -> Any:
## user with a working `tasks` collection may well see this work.
"search.time-range.todo": {"support": "unknown"},

"save-load.event.recurrences.exception": {"support": "unsupported"},
## Seen 2026-09-13 in testChangeAttendeeStatusWithEmailGiven, which only
## started running once save-load.mutable.attendee-partstat came out full.
"save-load.event.no-summary": {
Expand Down
5 changes: 4 additions & 1 deletion caldav/search.py
Original file line number Diff line number Diff line change
Expand Up @@ -1128,11 +1128,14 @@ def _search_impl(
return

# Bedework leaves the exceptions out of the calendar-data of a search.
# Only what the search itself returned; the batch load below fetches whole objects
# Only what the search itself returned; the batch load below fetches whole objects.
# Not after a server-side expansion: its instances carry a RECURRENCE-ID, and a
# multiget would swap them for the unexpanded master and exception
partial = []
if (
cw
and not caller_chose_data
and not server_expand
and not calendar.client.features.is_supported(
"search.recurrences.exception.in-calendar-data"
)
Expand Down
1 change: 1 addition & 0 deletions changes/+load-fallbacks.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
New parameter `CalendarObjectResource.load(fallbacks=True)`. Set it to `False` to load by the GET alone: no calendar-multiget and no search by UID when the GET fails, which `multiget_fallback=False` still does after a 404.
39 changes: 39 additions & 0 deletions tests/test_async_davclient.py
Original file line number Diff line number Diff line change
Expand Up @@ -1131,6 +1131,45 @@ async def test_load_without_multiget_fallback_raises_the_servers_own_error(self)
await event.load(multiget_fallback=False)
multiget.assert_not_awaited()

@pytest.mark.asyncio
async def test_load_without_fallbacks_raises_the_servers_own_error(self) -> None:
"""fallbacks=False surfaces the 403 and sends no REPORT."""
from caldav.aio import AsyncCalendarObjectResource

event = self._forbidden_event()
with patch.object(
AsyncCalendarObjectResource, "load_by_multiget", new_callable=AsyncMock
) as multiget:
with pytest.raises(error.AuthorizationError):
await event.load(fallbacks=False)
multiget.assert_not_awaited()

@pytest.mark.asyncio
async def test_load_without_fallbacks_raises_a_404_for_an_object_with_a_uid(self) -> None:
"""fallbacks=False: no multiget and no search by UID after a 404."""
from caldav.aio import AsyncCalendarObjectResource, AsyncEvent
from caldav.collection import Calendar

client = AsyncDAVClient(url="https://caldav.example.com/dav/")
client.request = AsyncMock(side_effect=error.NotFoundError("404 Not Found"))
calendar = Calendar(client=client, url="https://caldav.example.com/dav/calendars/test/")
event = AsyncEvent(
client=client,
url="https://caldav.example.com/dav/calendars/test/x.ics",
parent=calendar,
data="BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//x//y//EN\r\nBEGIN:VEVENT\r\nUID:x\r\nDTSTAMP:20260101T000000Z\r\nDTSTART:20260101T000000Z\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n",
)
with (
patch.object(
AsyncCalendarObjectResource, "load_by_multiget", new_callable=AsyncMock
) as multiget,
patch.object(Calendar, "get_object_by_uid", new_callable=AsyncMock) as by_uid,
):
with pytest.raises(error.NotFoundError):
await event.load(fallbacks=False)
multiget.assert_not_awaited()
by_uid.assert_not_awaited()


class TestAsyncRateLimiting:
"""
Expand Down
52 changes: 52 additions & 0 deletions tests/test_caldav_unit.py
Original file line number Diff line number Diff line change
Expand Up @@ -630,6 +630,33 @@ def testLoadWithoutMultigetFallbackRaisesTheServersOwnError(self):
with pytest.raises(error.AuthorizationError):
object.load(multiget_fallback=False)

def testLoadWithoutFallbacksRaisesA404ForAnObjectWithAUid(self):
"""load(fallbacks=False) is the GET and nothing else.

A 404 for an object that has a UID is otherwise retried as a multiget
and then as a search by UID - the latter whatever multiget_fallback
says. A compatibility checker comparing what a GET returns with what
a search returns must not get a search for its GET.
"""
client = DAVClient(url="http://cal.example.com/")
client.request = mock.Mock(side_effect=error.NotFoundError("404 Not Found"))
calendar = Calendar(client, url="/calendar/")
event = Event(client=client, url="/calendar/x.ics", parent=calendar, data=ev1)
with (
mock.patch.object(Calendar, "get_object_by_uid") as by_uid,
mock.patch.object(Event, "load_by_multiget") as multiget,
):
with pytest.raises(error.NotFoundError):
event.load(fallbacks=False)
by_uid.assert_not_called()
multiget.assert_not_called()

def testLoadWithoutFallbacksRaisesAForbidden(self):
"""fallbacks=False also leaves a refused GET unrescued."""
object = self._robur_object(self.MULTIGET_FOUND, "/calendar/robur/found.ics")
with pytest.raises(error.AuthorizationError):
object.load(fallbacks=False)

def testTheMultigetFallbackDoesNotLaunderARealForbidden(self):
"""A genuine 403 does not come out of the multiget fallback as a 404.

Expand Down Expand Up @@ -10102,6 +10129,31 @@ def test_no_second_request_elsewhere(self, base) -> None:
)
assert requests == ["query"]

def test_a_server_expansion_is_not_loaded_again(self, base) -> None:
"""Expanded on the server, each instance carries a RECURRENCE-ID: a
multiget would swap them for the unexpanded master and exception."""
instances = "".join(
"BEGIN:VEVENT\r\nUID:series-1\r\nDTSTAMP:20260101T000000Z\r\n"
f"RECURRENCE-ID:202611{day:02d}T090000Z\r\n"
f"DTSTART:202611{day:02d}T{hour}0000Z\r\nDTEND:202611{day:02d}T{hour + 1}0000Z\r\n"
f"SUMMARY:R: {'moved' if day == 3 else 'daily'}\r\nEND:VEVENT\r\n"
for day, hour in ((1, 9), (2, 9), (3, 14), (4, 9), (5, 9))
)
features = {
"search.recurrences.expanded": {"support": "full"},
"search.recurrences.exception.in-calendar-data": {"support": "unsupported"},
}
summaries, requests = self._search(
base,
features,
expand=False,
query=self.HEAD + instances + self.TAIL,
search_kwargs={"server_expand": True},
)
assert requests == ["query"]
assert ("2026-11-03 09:00:00+00:00", "R: moved") in summaries
assert len(summaries) == 5

def test_a_one_off_event_in_a_zone_is_not_loaded_again(self, base) -> None:
one_off = self.HEAD + self.ONE_OFF + self.TAIL
summaries, requests = self._search(base, query=one_off, full=one_off)
Expand Down
Loading