Skip to content

Commit 0a0d112

Browse files
committed
Merge PR 42: Move and rename on servers that keep a UID in one calendar, or rename a calendar's URL
#42 Moving an item works where a server keeps a UID in one calendar only (CCS, Cyrus, Ox: delete first, never for an occurrence, and not at all where a deleted UID cannot be reused; Zimbra: the copy moves the original), from caldav's hints, until caldav has a move() using WebDAV MOVE. A rename that moves the calendar's URL (Zimbra) is followed. Commits: - ffc45d9 fix: move where a UID fits in one calendar only - 75db9dc fix: follow a calendar that a rename moved Assisted-By: Claude Opus 5.5 <noreply@anthropic.com> Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
2 parents 04fdbeb + 75db9dc commit 0a0d112

11 files changed

Lines changed: 608 additions & 18 deletions

File tree

‎docs/design/API_DESIGN.md‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -395,7 +395,9 @@ class AsyncCollection:
395395
backend reported when it listed the collection. Assigning to them would
396396
have to write to the server as a side effect, so renaming is an explicit
397397
`set_name()`, which raises `UnsupportedError` where the backend cannot
398-
rename (a feed, a single `.ics` file). The same goes for items: there is no
398+
rename (a feed, a single `.ics` file). A server that names a calendar's URL
399+
after its display name (Zimbra) moves the calendar on a rename, and
400+
`set_name()` then updates `id` too. The same goes for items: there is no
399401
`collection.save()` without an argument, and no autosave (but see
400402
[§12](#12-beyond-the-funded-scope-implicit-synchronization)). This follows caldav, which settled on
401403
methods for anything that talks to the server. *Proposed by the author in
@@ -485,10 +487,21 @@ for `PARENT`, the children pointing back), as caldav's `get_relatives()`
485487
does. plann calls it 16 times, so it has to be here. Relatives outside
486488
this collection are looked up across the backend.
487489

488-
**`move`** within one backend uses its own move where it has one
489-
(CalDAV `MOVE`); between backends it is `add` to the target, then `delete`
490-
from the source, declared `EMULATED` because it is not atomic: a failure
491-
between the two leaves the item in both places, never in neither.
490+
**`move`** within one backend uses its own move where it has one; between
491+
backends, and on CalDAV until caldav has a `move()` using WebDAV `MOVE`
492+
([caldav #841](https://github.com/python-caldav/caldav/issues/841)), it is
493+
`add` to the target, then `delete` from the source, declared `EMULATED`
494+
because it is not atomic: a failure between the two leaves the item in both
495+
places, never in neither. Where a server keeps a UID in one calendar only
496+
(caldav's `save.duplicate-uid.cross-calendar`), the capability's `order`
497+
says what to do instead: `delete-first` where the copy would be refused
498+
(CCS, Cyrus, Ox), putting the item back if the add then fails (and saying so
499+
on the error where that fails too), and `add-may-move` where saving the copy
500+
moves the original (Zimbra), checking that the target holds the copy before
501+
the original is deleted. `delete-first` needs the deleted UID to be reusable
502+
(`save-load.reuse-deleted-uid`); where it is not, `move` is `UNSUPPORTED`.
503+
An occurrence cannot be moved by deleting first: deleting it only excludes
504+
it from its series, whose UID stays.
492505

493506
**How it fits Gitea:** a repository is a collection with `components =
494507
{TASK}`; `events()` returns an empty list rather than raising (there are

‎src/calendaring/_async/caldav.py‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@
4949
SAFE_NAME = re.compile(r"^[A-Za-z0-9._@-]{1,200}$")
5050

5151

52+
def _url_of(calendar: Calendar) -> str:
53+
return str(calendar.url).rstrip("/") + "/"
54+
55+
5256
def _name_of(href: object) -> str:
5357
return unquote(str(href).rstrip("/").rsplit("/", 1)[-1])
5458

@@ -60,7 +64,7 @@ def __init__(
6064
self, backend: AsyncCalDAVBackend, calendar: Calendar, *, name: str | None, components: frozenset[Component]
6165
) -> None:
6266
self.calendar = calendar
63-
self.url = str(calendar.url).rstrip("/") + "/"
67+
self.url = _url_of(calendar)
6468
super().__init__(
6569
backend,
6670
id=_name_of(self.url),
@@ -216,7 +220,17 @@ async def _delete(self, native_id: str, *, etag: str | None) -> None:
216220
)
217221

218222
async def _set_name(self, name: str) -> None:
219-
await self._backend._dav.set_display_name(self.calendar, name)
223+
dav = self._backend._dav
224+
await dav.set_display_name(self.calendar, name)
225+
# Zimbra names a calendar's URL after its display name, so a rename moves the calendar.
226+
listed = await dav.calendars()
227+
if any(_url_of(c) == self.url for c in listed):
228+
return
229+
named = [c for c in listed if await dav.display_name(c) == name]
230+
if len(named) == 1: # with several of that name, which one it became is a guess
231+
self.calendar = self.native = named[0]
232+
self.url = _url_of(named[0])
233+
self.id = _name_of(self.url)
220234

221235
async def _delete_collection(self) -> None:
222236
await self._backend._dav.delete_calendar(self.calendar)

‎src/calendaring/_async/collection.py‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
from ..capabilities import BACKEND_FEATURES, COMPONENT_FEATURE, Capabilities, Feature, Support
3030
from ..errors import (
3131
AlreadyExistsError,
32+
BackendError,
3233
CalendaringError,
3334
ConflictError,
3435
InvalidDataError,
@@ -1047,7 +1048,11 @@ async def move(
10471048
async def move(
10481049
self, item: Item, target: AsyncCollection, *, loss: LossPolicy | None = None, verify: bool | None = None
10491050
) -> AsyncItem:
1050-
"""Move to ``target``; between backends, add there and then delete here (``EMULATED``, not atomic)."""
1051+
"""Move to ``target``; between backends, add there and then delete here (``EMULATED``, not atomic).
1052+
1053+
Where a UID may be in one calendar only, the ``move`` capability's ``order`` says what to do instead:
1054+
``delete-first`` (the copy would be refused), or ``add-may-move`` (the copy may move the original).
1055+
"""
10511056
with self._context():
10521057
self._require_writable(item)
10531058
self._require(Feature.MOVE)
@@ -1060,12 +1065,38 @@ async def move(
10601065
return target._one(stored, written=True)
10611066
if item.etag is not None and (await self._fetch(item.native_id)).etag != item.etag:
10621067
raise ConflictError(f"{item.native_id!r} changed since it was read")
1068+
# Where a UID may be in one calendar only, the server refuses the copy, or moves the original.
1069+
order = self.capabilities.details(Feature.MOVE).get("order")
1070+
if order == "delete-first":
1071+
if item.is_occurrence: # deleting it writes an EXDATE: the UID stays here, and the copy is refused
1072+
raise UnsupportedError(Feature.MOVE, "an occurrence, where the copy must be made after the delete")
1073+
await self.delete(item)
1074+
try:
1075+
return await target.add(item.as_data(), loss=loss, verify=verify)
1076+
except CalendaringError as exc:
1077+
try:
1078+
await self.add(item.as_data(), loss=loss, verify=False)
1079+
except CalendaringError:
1080+
exc.add_note(
1081+
f"{item.uid!r} was deleted here and could not be put back: it is in neither collection"
1082+
)
1083+
raise
10631084
moved = await target.add(item.as_data(), loss=loss, verify=verify)
1085+
if order == "add-may-move":
1086+
try:
1087+
await target._fetch(moved.native_id) # type: ignore[arg-type] # add() returns a stored item
1088+
except NotFoundError:
1089+
raise BackendError(f"{item.uid!r} was not stored in {target.id!r}; it is still here") from None
10641090
try:
10651091
await self.delete(item)
1092+
except NotFoundError:
1093+
if order != "add-may-move":
1094+
raise
1095+
# the copy moved it: Zimbra still answers a read of the old URL, so only the delete tells
10661096
except ConflictError:
1067-
with suppress(CalendaringError): # best effort: the conflict is what to report
1068-
await target.delete(moved, overwrite=True)
1097+
if order != "add-may-move": # there, the copy may be the only one
1098+
with suppress(CalendaringError): # best effort: the conflict is what to report
1099+
await target.delete(moved, overwrite=True)
10691100
raise
10701101
return moved
10711102

‎src/calendaring/_caldav_features.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@
6464
Feature.SEARCH_TIME_RANGE: E,
6565
Feature.SEARCH_TEXT: E,
6666
Feature.CHANGES: {"level": E, "method": "etag-listing"},
67-
Feature.MOVE: {"level": E, "note": "added to the target, then deleted here"},
6867
Feature.IDENTITY_FOREIGN_ID: {"level": U, "note": "the UID is native"},
6968
Feature.RECURRENCE_EDIT_OCCURRENCE: {"level": U, "note": EDIT_ICALENDAR_PENDING},
7069
Feature.RECURRENCE_EDIT_THIS_AND_FUTURE: U,
@@ -133,6 +132,19 @@ def _table(features: Any) -> dict[Feature, Any]:
133132
return table
134133

135134

135+
def _move(features: Any) -> dict[str, Any]:
136+
"""Copy, then delete; unless the server keeps a UID in one calendar only (``save.duplicate-uid.cross-calendar``)."""
137+
hint = features.is_supported("save.duplicate-uid.cross-calendar", dict) if _hinted(features) else {}
138+
cross = str(hint.get("support", "unknown"))
139+
if cross in ("full", "unknown"):
140+
return {"level": E, "note": "added to the target, then deleted here"}
141+
if cross == "unsupported" and hint.get("behaviour") != "silently-ignored": # Zimbra moves the original
142+
return {"level": E, "order": "add-may-move", "note": "added to the target, then deleted here if still there"}
143+
if _level(features, "save-load.reuse-deleted-uid") is U:
144+
return {"level": U, "note": "the UID can be neither in two calendars at once nor reused once deleted"}
145+
return {"level": E, "order": "delete-first", "note": "deleted here, then added to the target"}
146+
147+
136148
def _changes(features: Any) -> dict[str, Any]:
137149
"""A native change feed where the server has a reliable one; else the etag listing, which always works.
138150
@@ -181,6 +193,7 @@ def collection_capabilities(features: Any, components: frozenset[Component]) ->
181193
"""The server's table, narrowed to what the calendar says it holds."""
182194
table = {f: v for f, v in _table(features).items() if f not in BACKEND_FEATURES}
183195
table[Feature.CHANGES] = _changes(features)
196+
table[Feature.MOVE] = _move(features)
184197
table[Feature.SEARCH_TIME_RANGE] = _time_range(features)
185198
for kind, (feature, name) in COMPONENT_FROM_SERVER.items():
186199
if kind in components:

‎src/calendaring/_sync/caldav.py‎

Lines changed: 16 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/calendaring/_sync/collection.py‎

Lines changed: 34 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎tests/_async/test_caldav_backend.py‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,59 @@ async def make_calendar(name: str, components: list[str]) -> Any:
103103
assert asked == [["VEVENT"]]
104104

105105

106+
async def test_a_rename_that_moves_the_calendar_follows_it(
107+
collection: AsyncCollection, monkeypatch: pytest.MonkeyPatch
108+
) -> None:
109+
"""Zimbra names a calendar's URL after its display name, so a rename moves the calendar."""
110+
backend = collection._backend
111+
moved_to = await backend.create_collection("moved-to", components=(Component.TASK,))
112+
dav = backend._dav # type: ignore[attr-defined]
113+
calendars, set_display_name = dav.calendars, dav.set_display_name
114+
115+
async def renamed_elsewhere(calendar: Any, name: str) -> None:
116+
await set_display_name(moved_to.calendar, name) # type: ignore[attr-defined]
117+
118+
old_url = collection.url # type: ignore[attr-defined]
119+
120+
async def without_the_old_url() -> list[Any]:
121+
return [c for c in await calendars() if str(c.url).rstrip("/") + "/" != old_url]
122+
123+
monkeypatch.setattr(dav, "set_display_name", renamed_elsewhere)
124+
monkeypatch.setattr(dav, "calendars", without_the_old_url)
125+
old = collection.id
126+
await collection.set_name("Renamed")
127+
assert collection.id == moved_to.id != old
128+
assert (await backend.collection(collection.id)).name == "Renamed"
129+
monkeypatch.undo()
130+
await (await backend.collection(old)).delete_collection() # still there in this simulation
131+
132+
133+
async def test_a_rename_does_not_guess_between_calendars_of_the_same_name(
134+
collection: AsyncCollection, monkeypatch: pytest.MonkeyPatch
135+
) -> None:
136+
backend = collection._backend
137+
made = [await backend.create_collection(name, components=(Component.TASK,)) for name in ("one", "two")]
138+
dav = backend._dav # type: ignore[attr-defined]
139+
calendars, set_display_name = dav.calendars, dav.set_display_name
140+
old_url = collection.url # type: ignore[attr-defined]
141+
142+
async def renamed_twice(calendar: Any, name: str) -> None:
143+
for other in made:
144+
await set_display_name(other.calendar, name) # type: ignore[attr-defined]
145+
146+
async def without_the_old_url() -> list[Any]:
147+
return [c for c in await calendars() if str(c.url).rstrip("/") + "/" != old_url]
148+
149+
monkeypatch.setattr(dav, "set_display_name", renamed_twice)
150+
monkeypatch.setattr(dav, "calendars", without_the_old_url)
151+
old = collection.id
152+
await collection.set_name("Renamed")
153+
assert collection.id == old
154+
monkeypatch.undo()
155+
for other in made:
156+
await other.delete_collection()
157+
158+
106159
async def test_wire_bytes_are_sent_as_given(collection: AsyncCollection, monkeypatch: pytest.MonkeyPatch) -> None:
107160
# icalendar would fold this line. Xandikos refolds what it stores, so what is checked is the PUT.
108161
client = collection._backend._dav.client # type: ignore[attr-defined]

0 commit comments

Comments
 (0)