From a5550c1e99e7462400e990cbf77f4e7279cb49a0 Mon Sep 17 00:00:00 2001 From: ivenos Date: Sat, 7 Nov 2026 23:32:24 +0100 Subject: [PATCH 1/6] fix: add the missing VTIMEZONE to objects built from arguments An object built by create_ical(), e.g. add_event(dtstart=...) or add_todo(due=...) with a time zone other than UTC, had a TZID without the VTIMEZONE that RFC 5545 section 3.6.5 requires. A Home Assistant user reports such events shifted by the UTC offset in Synology Calendar. create_ical() now adds the missing VTIMEZONEs, built with icalendar's Timezone.from_tzid() as its Calendar.add_missing_timezones() does. That method raises a KeyError before icalendar 7.0.3 when an ical_fragment has a VTIMEZONE no property refers to, so caldav adds them on its own. Calendar leaves them out where the server hint save-load.icalendar.olson-tzid is supported, by passing add_vtimezones=False to create_ical(), and so does add_event(add_vtimezones=False). The default "unsupported" and Synology's "fragile" keep them. icalendar writes all transitions of an observance as one RDATE list, and vobject 0.9.9 only reads the first value of it, so the times in vobject_instance would be an hour off for half of every year. The added VTIMEZONEs get one RDATE per line. They also run to 2100 instead of icalendar's 2038, as vobject keeps the last offset for anything later. They go after the event, so subcomponents[0] stays the event as the docs use it, and a VTIMEZONE that came with the ical_fragment is left as it is. complete(handle_rrule=True, rrule_mode="thisandfuture") treated every component of the object as an instance of the task, the first as the series and the last as the one to complete. It raised KeyError: 'RRULE' for a task with its VTIMEZONE before the VTODO, the usual order in tasks from other clients, and would complete the VTIMEZONE now added after it. It skips VTIMEZONE components now. Fixes https://github.com/python-caldav/caldav/issues/849 Prompt (translated from German): yes [build the VTIMEZONE fix for python-caldav] Followup-Prompt: https://github.com/python-caldav/caldav/issues/849 [after #850 and #851 were merged] Assisted-By: Claude Opus 5.5 --- caldav/calendarobjectresource.py | 10 ++- caldav/collection.py | 8 +- caldav/lib/vcal.py | 29 ++++++- changes/849.fixed.1.md | 1 + changes/849.fixed.2.md | 1 + tests/test_caldav_unit.py | 133 +++++++++++++++++++++++++++++++ tests/test_vcal.py | 129 +++++++++++++++++++++++++++++- 7 files changed, 302 insertions(+), 9 deletions(-) create mode 100644 changes/849.fixed.1.md create mode 100644 changes/849.fixed.2.md diff --git a/caldav/calendarobjectresource.py b/caldav/calendarobjectresource.py index dbbac9b0..767eeba4 100644 --- a/caldav/calendarobjectresource.py +++ b/caldav/calendarobjectresource.py @@ -2972,7 +2972,11 @@ def _prepare_recurring_thisandfuture(self, completion_timestamp) -> None: algorithm description. The caller does the single ``save(increase_seqno=False)`` that follows. """ - recurrences = self.icalendar_instance.subcomponents + recurrences = [ + x + for x in self.icalendar_instance.subcomponents + if not isinstance(x, icalendar.Timezone) + ] orig = recurrences[0] if "STATUS" not in orig: orig["STATUS"] = "NEEDS-ACTION" @@ -2984,6 +2988,7 @@ def _prepare_recurring_thisandfuture(self, completion_timestamp) -> None: just_completed.add("RECURRENCE-ID", orig.get("DTSTART", completion_timestamp)) seqno = just_completed.pop("SEQUENCE", 0) just_completed.add("SEQUENCE", seqno + 1) + self.icalendar_instance.add_component(just_completed) recurrences.append(just_completed) prev = recurrences[-1] @@ -3040,8 +3045,7 @@ def _complete_recurring_thisandfuture(self, completion_timestamp) -> None: recurring tasks is ... but this is my shot at it. 1) The original, with rrule, will be kept as it is. The rrule - string is fetched from the first subcomponent of the - icalendar. + string is fetched from the first VTODO of the icalendar. 2) If there are multiple recurrence instances in subcomponents and the last one is marked with RANGE=THISANDFUTURE, then diff --git a/caldav/collection.py b/caldav/collection.py index 70b6e802..7a9b5847 100644 --- a/caldav/collection.py +++ b/caldav/collection.py @@ -1328,6 +1328,7 @@ async def _async_save_with_invites( return obj def _use_or_create_ics(self, ical, objtype, **ical_data): + add_vtimezones = ical_data.pop("add_vtimezones", None) if ical_data or ( (isinstance(ical, str) or isinstance(ical, bytes)) and b"BEGIN:VCALENDAR" not in to_wire(ical) @@ -1335,7 +1336,12 @@ def _use_or_create_ics(self, ical, objtype, **ical_data): ## TODO: the ical_fragment code is not much tested if ical and "ical_fragment" not in ical_data: ical_data["ical_fragment"] = ical - return vcal.create_ical(objtype=objtype, **ical_data) + if add_vtimezones is None: + add_vtimezones = not ( + self.client + and self.client.features.is_supported("save-load.icalendar.olson-tzid") + ) + return vcal.create_ical(objtype=objtype, add_vtimezones=add_vtimezones, **ical_data) return ical def add_object( diff --git a/caldav/lib/vcal.py b/caldav/lib/vcal.py index b943d340..f4c9e225 100644 --- a/caldav/lib/vcal.py +++ b/caldav/lib/vcal.py @@ -235,13 +235,14 @@ def __call__(self, line): ## sorry for being english-language-euro-centric ... fits rather perfectly as default language for me :-) -def create_ical(ical_fragment=None, objtype=None, language="en_DK", **props): +def create_ical( + ical_fragment=None, objtype=None, language="en_DK", *, add_vtimezones=True, **props +): """Creates some icalendar based on properties given as parameters. It basically creates an icalendar object with all the boilerplate, some sensible defaults, the properties given and returns it as a - string. - - TODO: timezones not supported so far + string. Unless add_vtimezones is False, a VTIMEZONE is added for + every known TZID that has none. """ ical_fragment = to_normal_str(ical_fragment) if "class_" in props: @@ -307,6 +308,8 @@ def create_ical(ical_fragment=None, objtype=None, language="en_DK", **props): component.add(prop, props[prop]) if alarm: add_alarm(my_instance, alarm) + if add_vtimezones: + _add_vtimezones(my_instance) ret = to_normal_str(my_instance.to_ical()) if ical_fragment and ical_fragment.strip(): ret = re.sub( @@ -319,6 +322,24 @@ def create_ical(ical_fragment=None, objtype=None, language="en_DK", **props): return ret +def _add_vtimezones(ical: icalendar.Calendar) -> None: + missing = ical.get_used_tzids() - {"UTC"} - {tz.get("TZID") for tz in ical.timezones} + for tzid in sorted(missing): + try: + ## vobject keeps the last offset after the last RDATE, icalendar stops at 2038 + vtimezone = icalendar.Timezone.from_tzid(tzid, last_date=datetime.date(2100, 1, 1)) + except (ValueError, OSError): + continue + for observance in vtimezone.subcomponents: + rdates = observance.pop("RDATE", []) + ## vobject 0.9.9 only reads the first value of an RDATE list in a VTIMEZONE + for rdate in rdates if isinstance(rdates, list) else [rdates]: + for value in rdate.dts: + observance.add("RDATE", value.dt) + ## at the end, so subcomponents[0] stays the event as the docs use it + ical.add_component(vtimezone) + + def add_alarm(ical, alarm): ia = icalendar.Alarm() for prop in alarm: diff --git a/changes/849.fixed.1.md b/changes/849.fixed.1.md new file mode 100644 index 00000000..dd1106b6 --- /dev/null +++ b/changes/849.fixed.1.md @@ -0,0 +1 @@ +An object caldav builds from keyword arguments, e.g. `add_event(dtstart=...)` or `add_todo(due=...)` with a time zone other than UTC, had a `TZID` without the `VTIMEZONE` that RFC 5545 section 3.6.5 requires. A Home Assistant user reports such events shifted by the UTC offset in Synology Calendar. The missing `VTIMEZONE` for a known time zone is now added, covering 1970 to 2100 with one `RDATE` per line, as vobject reads only the first value of an `RDATE` list in a `VTIMEZONE`. It is left out where the server hint `save-load.icalendar.olson-tzid` says it is supported, or with `add_vtimezones=False`. diff --git a/changes/849.fixed.2.md b/changes/849.fixed.2.md new file mode 100644 index 00000000..017985bf --- /dev/null +++ b/changes/849.fixed.2.md @@ -0,0 +1 @@ +`complete(handle_rrule=True, rrule_mode="thisandfuture")` treated every component of the object as an instance of the task, the first as the series and the last as the one to complete. So it raised `KeyError: 'RRULE'` for a task with its `VTIMEZONE` before the `VTODO`, the usual order in tasks from other clients and after reading `vobject_instance`, and completed a `VTIMEZONE` that came after it. It now skips `VTIMEZONE` components. diff --git a/tests/test_caldav_unit.py b/tests/test_caldav_unit.py index 2f18fbc9..0e451544 100755 --- a/tests/test_caldav_unit.py +++ b/tests/test_caldav_unit.py @@ -3457,6 +3457,59 @@ def test_reply_to_invite_does_not_bump_auto_schedule_async(self): existing.save.assert_awaited_once_with(increase_seqno=False) +class TestOlsonTzidHint: + @staticmethod + def _add_event(client: DAVClient, *largs: Any, **kwargs: Any) -> CalendarObjectResource: + put = [] + with mock.patch.object( + CalendarObjectResource, "_create", lambda self_, *largs, **kwargs: put.append(self_) + ): + Calendar(client, url="/calendar/").add_event(*largs, **kwargs) + return put[0] + + @staticmethod + def _berlin() -> datetime: + from zoneinfo import ZoneInfo + + return datetime(2026, 6, 6, 20, tzinfo=ZoneInfo("Europe/Berlin")) + + @pytest.mark.parametrize( + "support, vtimezone", + [(None, True), ("unsupported", True), ("fragile", True), ("full", False)], + ) + def test_add_event_sends_vtimezone_unless_olson_tzid_is_full( + self, support: str | None, vtimezone: bool + ) -> None: + from caldav.compatibility_hints import FeatureSet + + client = MockedDAVClient("") + if support: + client.features = FeatureSet({"save-load.icalendar.olson-tzid": {"support": support}}) + put = self._add_event(client, summary="tz", dtstart=self._berlin()) + assert "DTSTART;TZID=Europe/Berlin:20260606T200000" in put.data + assert ("BEGIN:VTIMEZONE" in put.data) is vtimezone + + def test_add_event_passes_add_vtimezones_on(self) -> None: + put = self._add_event( + MockedDAVClient(""), summary="tz", dtstart=self._berlin(), add_vtimezones=False + ) + assert "VTIMEZONE" not in put.data + + def test_add_vtimezones_leaves_a_complete_object_alone(self) -> None: + ical = icalendar.Calendar.from_ical( + "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" + "BEGIN:VTIMEZONE\nTZID:Europe/Berlin\n" + "BEGIN:STANDARD\nDTSTART:19701025T030000\n" + "TZOFFSETFROM:+0200\nTZOFFSETTO:+0100\n" + "END:STANDARD\nEND:VTIMEZONE\n" + "BEGIN:VEVENT\nUID:complete@example.com\nDTSTAMP:20261101T000000Z\n" + "DTSTART;TZID=Europe/Berlin:20261207T130000\nSUMMARY:complete\n" + "END:VEVENT\nEND:VCALENDAR\n" + ) + put = self._add_event(MockedDAVClient(""), ical, add_vtimezones=False) + assert put.icalendar_instance.to_ical() == ical.to_ical() + + class TestFreeBusyScheduleResponse: """Unit tests for parsing RFC6638 schedule-response to a freebusy request. @@ -6356,6 +6409,86 @@ def test_thisandfuture_completed_early_advances(self) -> None: assert thisandfuture["RECURRENCE-ID"].dt == nxt assert thisandfuture["DTSTART"].dt == nxt + _prague_vtimezone = ( + "BEGIN:VTIMEZONE\nTZID:Europe/Prague\n" + "BEGIN:STANDARD\nDTSTART:19701025T030000\n" + "RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU\n" + "TZOFFSETFROM:+0200\nTZOFFSETTO:+0100\n" + "END:STANDARD\n" + "BEGIN:DAYLIGHT\nDTSTART:19700329T020000\n" + "RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU\n" + "TZOFFSETFROM:+0100\nTZOFFSETTO:+0200\n" + "END:DAYLIGHT\nEND:VTIMEZONE\n" + ) + + @staticmethod + def _prague_vtodo(day: int, extra: str) -> str: + return ( + "BEGIN:VTODO\nUID:vtimezone-thisandfuture@example.com\n" + "DTSTAMP:20261101T000000Z\n" + f"DTSTART;TZID=Europe/Prague:202611{day:02}T090000\n" + f"DUE;TZID=Europe/Prague:202611{day:02}T100000\n" + f"{extra}SUMMARY:Weekly chore\nEND:VTODO\n" + ) + + def _prague_todo(self, vtodos: str, vtimezone_first: bool = True) -> Todo: + body = ( + self._prague_vtimezone + vtodos if vtimezone_first else vtodos + self._prague_vtimezone + ) + return self._make_todo( + "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" + body + "END:VCALENDAR\n" + ) + + @pytest.mark.parametrize("vtimezone_first", [True, False]) + def test_prepare_thisandfuture_leaves_vtimezone_alone(self, vtimezone_first: bool) -> None: + todo = self._prague_todo(self._prague_vtodo(2, "RRULE:FREQ=WEEKLY\n"), vtimezone_first) + before = todo.icalendar_instance.walk("VTIMEZONE")[0].to_ical() + + todo._prepare_recurring_thisandfuture(datetime(2026, 11, 3, 12, tzinfo=timezone.utc)) + + assert [tz.to_ical() for tz in todo.icalendar_instance.walk("VTIMEZONE")] == [before] + master, completed, thisandfuture = todo.icalendar_instance.walk("VTODO") + assert "RRULE" in master + assert str(master["STATUS"]) == "NEEDS-ACTION" + assert str(completed["STATUS"]) == "COMPLETED" + assert completed["RECURRENCE-ID"].dt == master["DTSTART"].dt + assert thisandfuture["RECURRENCE-ID"].params["RANGE"] == "THISANDFUTURE" + + def test_prepare_thisandfuture_completes_the_counted_series_not_the_vtimezone(self) -> None: + todo = self._prague_todo(self._prague_vtodo(2, "RRULE:FREQ=WEEKLY;COUNT=2\n")) + before = todo.icalendar_instance.walk("VTIMEZONE")[0].to_ical() + + todo._prepare_recurring_thisandfuture(datetime(2026, 11, 3, 12, tzinfo=timezone.utc)) + todo._prepare_recurring_thisandfuture(datetime(2026, 11, 10, 12, tzinfo=timezone.utc)) + + assert [tz.to_ical() for tz in todo.icalendar_instance.walk("VTIMEZONE")] == [before] + assert [str(t["STATUS"]) for t in todo.icalendar_instance.walk("VTODO")] == [ + "COMPLETED" + ] * 3 + + def test_prepare_thisandfuture_continues_a_series_with_the_vtimezone_last(self) -> None: + todo = self._prague_todo( + self._prague_vtodo(2, "RRULE:FREQ=WEEKLY\nSTATUS:NEEDS-ACTION\n") + + self._prague_vtodo( + 2, + "RECURRENCE-ID;TZID=Europe/Prague:20261102T090000\n" + "STATUS:COMPLETED\nCOMPLETED:20261103T120000Z\n", + ) + + self._prague_vtodo( + 9, "RECURRENCE-ID;RANGE=THISANDFUTURE;TZID=Europe/Prague:20261109T090000\n" + ), + vtimezone_first=False, + ) + before = todo.icalendar_instance.walk("VTIMEZONE")[0].to_ical() + + todo._prepare_recurring_thisandfuture(datetime(2026, 11, 10, 12, tzinfo=timezone.utc)) + + assert [tz.to_ical() for tz in todo.icalendar_instance.walk("VTIMEZONE")] == [before] + *_, completed, thisandfuture = todo.icalendar_instance.walk("VTODO") + assert str(completed["STATUS"]) == "COMPLETED" + assert "RANGE" not in completed["RECURRENCE-ID"].params + assert thisandfuture["RECURRENCE-ID"].params["RANGE"] == "THISANDFUTURE" + def test_safe_completion_issues_two_puts(self, monkeypatch: Any) -> None: """The standalone completed copy must not be PUT twice. diff --git a/tests/test_vcal.py b/tests/test_vcal.py index 814dbff9..21274b45 100644 --- a/tests/test_vcal.py +++ b/tests/test_vcal.py @@ -1,8 +1,9 @@ #!/usr/bin/env python import re import time -from datetime import datetime, timedelta, timezone +from datetime import date, datetime, timedelta, timezone from unittest import TestCase +from zoneinfo import ZoneInfo import icalendar import pytest @@ -31,6 +32,13 @@ END:VCALENDAR""" +def _vobject_utc(ical: str, tzid: str, local: datetime) -> datetime: + ## vobject resolves a TZID through a process-wide registry, so read the VTIMEZONE itself + vtimezones = vobject.readOne(ical).vtimezone_list + tzinfo = next(tz.gettzinfo() for tz in vtimezones if tz.tzid.value == tzid) + return local.replace(tzinfo=tzinfo).astimezone(utc) + + class TestVcal(TestCase): def assertSameICal(self, ical1, ical2, ignore_uid=False): """helper method""" @@ -149,6 +157,125 @@ def create_and_validate(**args): rrule_pos = raw_bytes.index(b"RRULE:FREQ=DAILY") assert rrule_pos > end_valarm_pos, "RRULE must not be inside VALARM" + def test_create_ical_adds_vtimezone_for_each_tzid(self) -> None: + """RFC 5545 section 3.6.5 requires a VTIMEZONE for every TZID. + + https://github.com/home-assistant/core/issues/172990 + """ + lisbon = ZoneInfo("Europe/Lisbon") + chicago = ZoneInfo("America/Chicago") + ical = create_ical( + summary="tz", + dtstart=datetime(2026, 6, 6, 20, tzinfo=lisbon), + dtend=datetime(2026, 6, 6, 15, tzinfo=chicago), + ) + cal = icalendar.Calendar.from_ical(ical) + assert [c.name for c in cal.subcomponents] == ["VEVENT", "VTIMEZONE", "VTIMEZONE"] + assert [str(tz["TZID"]) for tz in cal.walk("VTIMEZONE")] == [ + "America/Chicago", + "Europe/Lisbon", + ] + assert re.search(r"^DTSTART;TZID=Europe/Lisbon:20260606T200000\r?$", ical, re.M) + assert _vobject_utc(ical, "Europe/Lisbon", datetime(2026, 6, 6, 20)) == datetime( + 2026, 6, 6, 19, tzinfo=utc + ) + assert _vobject_utc(ical, "America/Chicago", datetime(2026, 6, 6, 15)) == datetime( + 2026, 6, 6, 20, tzinfo=utc + ) + + todo = create_ical( + objtype="VTODO", summary="tz", due=datetime(2026, 1, 15, 9, tzinfo=lisbon) + ) + assert [str(tz["TZID"]) for tz in icalendar.Calendar.from_ical(todo).walk("VTIMEZONE")] == [ + "Europe/Lisbon" + ] + assert _vobject_utc(todo, "Europe/Lisbon", datetime(2026, 1, 15, 9)) == datetime( + 2026, 1, 15, 9, tzinfo=utc + ) + + def test_create_ical_skips_a_time_zone_without_a_name(self) -> None: + ical = create_ical( + summary="offset", dtstart=datetime(2026, 6, 6, 20, tzinfo=timezone(timedelta(hours=2))) + ) + assert "VTIMEZONE" not in ical + + def test_create_ical_vtimezone_covers_dates_after_2038(self) -> None: + ical = create_ical( + summary="far", dtstart=datetime(2060, 7, 6, 9, tzinfo=ZoneInfo("Europe/Berlin")) + ) + assert _vobject_utc(ical, "Europe/Berlin", datetime(2060, 7, 6, 9)) == datetime( + 2060, 7, 6, 7, tzinfo=utc + ) + + def test_create_ical_adds_no_vtimezone_without_tzid(self) -> None: + for value in (datetime(2026, 6, 6, 20, tzinfo=utc), date(2026, 6, 6)): + ical = create_ical(summary="no tz", dtstart=value) + assert "VTIMEZONE" not in ical + assert "TZID" not in ical + + def test_create_ical_add_vtimezones_false(self) -> None: + ical = create_ical( + summary="bare", + dtstart=datetime(2026, 6, 6, 20, tzinfo=ZoneInfo("Europe/Berlin")), + add_vtimezones=False, + ) + assert "VTIMEZONE" not in ical + assert re.search(r"^DTSTART;TZID=Europe/Berlin:20260606T200000\r?$", ical, re.M) + + def test_create_ical_keeps_an_unused_vtimezone(self) -> None: + fragment = ( + "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" + "BEGIN:VEVENT\nUID:test\nDTSTAMP:20261027T000000Z\n" + "DTSTART;VALUE=DATE:20261207\n" + "END:VEVENT\n" + "BEGIN:VTIMEZONE\nTZID:Europe/Amsterdam\n" + "BEGIN:STANDARD\nDTSTART:19701025T030000\n" + "RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU\n" + "TZOFFSETFROM:+0200\nTZOFFSETTO:+0100\n" + "END:STANDARD\nEND:VTIMEZONE\nEND:VCALENDAR\n" + ) + cal = icalendar.Calendar.from_ical(create_ical(ical_fragment=fragment, summary="all day")) + assert [str(tz["TZID"]) for tz in cal.walk("VTIMEZONE")] == ["Europe/Amsterdam"] + assert str(cal.walk("VEVENT")[0]["SUMMARY"]) == "all day" + + def test_create_ical_tolerates_a_vtimezone_without_tzid(self) -> None: + fragment = ( + "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" + "BEGIN:VEVENT\nUID:test\nDTSTAMP:20261027T000000Z\n" + "DTSTART;TZID=Europe/Berlin:20261207T130000\n" + "END:VEVENT\n" + "BEGIN:VTIMEZONE\nBEGIN:STANDARD\nDTSTART:19701025T030000\n" + "TZOFFSETFROM:+0200\nTZOFFSETTO:+0100\n" + "END:STANDARD\nEND:VTIMEZONE\nEND:VCALENDAR\n" + ) + cal = icalendar.Calendar.from_ical(create_ical(ical_fragment=fragment, summary="no tzid")) + assert [tz.get("TZID") for tz in cal.walk("VTIMEZONE")] == [None, "Europe/Berlin"] + + def test_create_ical_keeps_a_vtimezone_it_was_given(self) -> None: + vtimezone = ( + "BEGIN:VTIMEZONE\nTZID:Europe/Amsterdam\n" + "BEGIN:STANDARD\nDTSTART:20251026T030000\n" + "RDATE:20261025T030000,20271031T030000\n" + "TZOFFSETFROM:+0200\nTZOFFSETTO:+0100\n" + "END:STANDARD\nEND:VTIMEZONE\n" + ) + fragment = ( + "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" + "BEGIN:VEVENT\nUID:test\nDTSTAMP:20261027T000000Z\n" + "DTSTART;TZID=Europe/Amsterdam:20261207T130000\n" + "END:VEVENT\n" + vtimezone + "END:VCALENDAR\n" + ) + cal = icalendar.Calendar.from_ical( + create_ical( + ical_fragment=fragment, + dtend=datetime(2026, 12, 7, 14, tzinfo=ZoneInfo("Europe/Amsterdam")), + ) + ) + assert [tz.to_ical() for tz in cal.walk("VTIMEZONE")] == [ + icalendar.Calendar.from_ical(fragment).walk("VTIMEZONE")[0].to_ical() + ] + assert cal.walk("VEVENT")[0]["DTEND"].params["TZID"] == "Europe/Amsterdam" + def test_vcal_fixups(self): """ There is an obscure function lib.vcal that attempts to fix up From d9b599a70245076b544acf7ff6d3b637c4a788d1 Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Nov 2026 05:32:31 +0100 Subject: [PATCH 2/6] docs: document add_vtimezones in add_object() https://github.com/python-caldav/caldav/pull/852 added the add_vtimezones keyword without mentioning it in the docstring. Prompt: PR #852, review [https://github.com/python-caldav/caldav/pull/852] Followup-Prompt: add the docstring and merge Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- caldav/collection.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/caldav/collection.py b/caldav/collection.py index 7a9b5847..4ec5d90e 100644 --- a/caldav/collection.py +++ b/caldav/collection.py @@ -1369,6 +1369,12 @@ def add_object( increase_seqno: bump SEQUENCE if the ical data carries one. Defaults to True; pass False when storing data verbatim (sync, copy, import). See :meth:`CalendarObjectResource.save`. + add_vtimezones: add a VTIMEZONE for every TZID lacking one that + icalendar knows, when the object is built or amended from + properties. Defaults to True unless the server hint + ``save-load.icalendar.olson-tzid`` says the server handles a + bare TZID. Ignored when ``ical`` is a complete VCALENDAR (text + or object) and no properties are given. dtstart: properties to be inserted into the icalendar object dtend: properties to be inserted into the icalendar object summary: properties to be inserted into the icalendar object From 6ed9b1287c61e83712e13d9bcace0e4d83776116 Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Nov 2026 07:11:02 +0100 Subject: [PATCH 3/6] fix: cover every date of the object in VTIMEZONE The VTIMEZONEs added by create_ical() ran from 1970 to 2100, so a time outside that range, such as a yearly event that started in 1960, got the wrong offset in summer when read back through vobject or by a server that uses the VTIMEZONE. The range now stretches to the earliest and latest date in the object. Prompt: [fix issues found during the review process] Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- caldav/lib/vcal.py | 25 +++++++++++++++++++++++-- tests/test_vcal.py | 8 ++++++++ 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/caldav/lib/vcal.py b/caldav/lib/vcal.py index f4c9e225..33c367b3 100644 --- a/caldav/lib/vcal.py +++ b/caldav/lib/vcal.py @@ -3,6 +3,7 @@ import logging import re import uuid +from collections.abc import Iterator import icalendar @@ -324,10 +325,18 @@ def create_ical( def _add_vtimezones(ical: icalendar.Calendar) -> None: missing = ical.get_used_tzids() - {"UTC"} - {tz.get("TZID") for tz in ical.timezones} + if not missing: + return + ## vobject keeps the last offset after the last RDATE, icalendar stops at 2038 + ## and starts at 1970, so stretch the range to every date in the object + years = list(_years(ical)) + first_date = datetime.date(min([1970, *years]), 1, 1) + last_date = datetime.date(max([2099, *years]) + 1, 1, 1) for tzid in sorted(missing): try: - ## vobject keeps the last offset after the last RDATE, icalendar stops at 2038 - vtimezone = icalendar.Timezone.from_tzid(tzid, last_date=datetime.date(2100, 1, 1)) + vtimezone = icalendar.Timezone.from_tzid( + tzid, first_date=first_date, last_date=last_date + ) except (ValueError, OSError): continue for observance in vtimezone.subcomponents: @@ -340,6 +349,18 @@ def _add_vtimezones(ical: icalendar.Calendar) -> None: ical.add_component(vtimezone) +def _years(ical: icalendar.Calendar) -> Iterator[int]: + """The year of every date and date-time value in the calendar.""" + for component in ical.walk(): + for value in component.values(): + for item in value if isinstance(value, list) else [value]: + ## RDATE and EXDATE hold a list of values in .dts + for prop in item.dts if hasattr(item, "dts") else [item]: + dt = getattr(prop, "dt", None) + if isinstance(dt, datetime.date): + yield dt.year + + def add_alarm(ical, alarm): ia = icalendar.Alarm() for prop in alarm: diff --git a/tests/test_vcal.py b/tests/test_vcal.py index 21274b45..8051b8bc 100644 --- a/tests/test_vcal.py +++ b/tests/test_vcal.py @@ -207,6 +207,14 @@ def test_create_ical_vtimezone_covers_dates_after_2038(self) -> None: 2060, 7, 6, 7, tzinfo=utc ) + def test_create_ical_vtimezone_covers_dates_before_1970_and_after_2100(self) -> None: + new_york = ZoneInfo("America/New_York") + for year in (1960, 2110): + ical = create_ical(summary="old", dtstart=datetime(year, 7, 1, 12, tzinfo=new_york)) + assert _vobject_utc(ical, "America/New_York", datetime(year, 7, 1, 12)) == datetime( + year, 7, 1, 16, tzinfo=utc + ) + def test_create_ical_adds_no_vtimezone_without_tzid(self) -> None: for value in (datetime(2026, 6, 6, 20, tzinfo=utc), date(2026, 6, 6)): ical = create_ical(summary="no tz", dtstart=value) From ccb26b8ca9321dc95713743bd69deb679f8c43a2 Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Nov 2026 07:11:15 +0100 Subject: [PATCH 4/6] build: require icalendar 6.1.0 The VTIMEZONEs added by create_ical() use Timezone.from_tzid(), Calendar.get_used_tzids() and Calendar.timezones, all new in icalendar 6.1.0. Only icalendar-searcher's own pin kept older versions out so far. Prompt: [fix issues found during the review process] Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 43657166..290be03b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,7 +80,7 @@ dependencies = [ "niquests", ## see docs/source/http-libraries.rst "recurring-ical-events>=2.0.0", "typing_extensions;python_version<'3.11'", - "icalendar>6.0.0", + "icalendar>=6.1.0", ## Timezone.from_tzid(), Calendar.get_used_tzids() "icalendar-searcher>=1.1.0,<2", "dnspython", "python-dateutil", From fcc97e3f8dd617c73c5881213db95082bd4917eb Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Nov 2026 07:11:37 +0100 Subject: [PATCH 5/6] test: cover add_vtimezones=True and a quirk hint An explicit add_vtimezones=True wins over a "full" olson-tzid hint, and "quirk" leaves the VTIMEZONEs out as "full" does. The test that only checks the keyword is not sent as a property is renamed to say so. Prompt: [fix issues found during the review process] Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- tests/test_caldav_unit.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/tests/test_caldav_unit.py b/tests/test_caldav_unit.py index 0e451544..ab2624fd 100755 --- a/tests/test_caldav_unit.py +++ b/tests/test_caldav_unit.py @@ -3475,7 +3475,13 @@ def _berlin() -> datetime: @pytest.mark.parametrize( "support, vtimezone", - [(None, True), ("unsupported", True), ("fragile", True), ("full", False)], + [ + (None, True), + ("unsupported", True), + ("fragile", True), + ("quirk", False), + ("full", False), + ], ) def test_add_event_sends_vtimezone_unless_olson_tzid_is_full( self, support: str | None, vtimezone: bool @@ -3495,7 +3501,15 @@ def test_add_event_passes_add_vtimezones_on(self) -> None: ) assert "VTIMEZONE" not in put.data - def test_add_vtimezones_leaves_a_complete_object_alone(self) -> None: + def test_add_vtimezones_true_overrides_the_hint(self) -> None: + from caldav.compatibility_hints import FeatureSet + + client = MockedDAVClient("") + client.features = FeatureSet({"save-load.icalendar.olson-tzid": {"support": "full"}}) + put = self._add_event(client, summary="tz", dtstart=self._berlin(), add_vtimezones=True) + assert "BEGIN:VTIMEZONE" in put.data + + def test_add_vtimezones_does_not_become_a_property(self) -> None: ical = icalendar.Calendar.from_ical( "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//test//EN\n" "BEGIN:VTIMEZONE\nTZID:Europe/Berlin\n" From 05b6e4aec918cfd16efdbed318428745924635d1 Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Nov 2026 17:42:43 +0100 Subject: [PATCH 6/6] fix: stop the VTIMEZONE range after 2200 A date in year 9999, which some systems use for "no end", made create_ical() raise ValueError while building the VTIMEZONE, and a far-future date made the VTIMEZONE grow without bound, one RDATE per transition. The range now ends after 2200 at the latest, so a client that reads the VTIMEZONE may show a summer-time date past that an hour off. The changelog fragment describes the stretched range. Prompt: ... there is a new comment in the issue [the comment is https://github.com/python-caldav/caldav/pull/852#issuecomment-6723383216] Assisted-By: Claude Opus 5.5 Reviewed-by: Tobias Brox --- caldav/lib/vcal.py | 5 +++-- changes/849.fixed.1.md | 2 +- tests/test_vcal.py | 15 +++++++++++++++ 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/caldav/lib/vcal.py b/caldav/lib/vcal.py index 33c367b3..0683ba05 100644 --- a/caldav/lib/vcal.py +++ b/caldav/lib/vcal.py @@ -328,10 +328,11 @@ def _add_vtimezones(ical: icalendar.Calendar) -> None: if not missing: return ## vobject keeps the last offset after the last RDATE, icalendar stops at 2038 - ## and starts at 1970, so stretch the range to every date in the object + ## and starts at 1970, so stretch the range to every date in the object. + ## Stop after 2200: one RDATE per transition, and 9999 is often used for "no end" years = list(_years(ical)) first_date = datetime.date(min([1970, *years]), 1, 1) - last_date = datetime.date(max([2099, *years]) + 1, 1, 1) + last_date = datetime.date(min(max([2099, *years]), 2200) + 1, 1, 1) for tzid in sorted(missing): try: vtimezone = icalendar.Timezone.from_tzid( diff --git a/changes/849.fixed.1.md b/changes/849.fixed.1.md index dd1106b6..1069f278 100644 --- a/changes/849.fixed.1.md +++ b/changes/849.fixed.1.md @@ -1 +1 @@ -An object caldav builds from keyword arguments, e.g. `add_event(dtstart=...)` or `add_todo(due=...)` with a time zone other than UTC, had a `TZID` without the `VTIMEZONE` that RFC 5545 section 3.6.5 requires. A Home Assistant user reports such events shifted by the UTC offset in Synology Calendar. The missing `VTIMEZONE` for a known time zone is now added, covering 1970 to 2100 with one `RDATE` per line, as vobject reads only the first value of an `RDATE` list in a `VTIMEZONE`. It is left out where the server hint `save-load.icalendar.olson-tzid` says it is supported, or with `add_vtimezones=False`. +An object caldav builds from keyword arguments, e.g. `add_event(dtstart=...)` or `add_todo(due=...)` with a time zone other than UTC, had a `TZID` without the `VTIMEZONE` that RFC 5545 section 3.6.5 requires. A Home Assistant user reports such events shifted by the UTC offset in Synology Calendar. The missing `VTIMEZONE` for a known time zone is now added, covering 1970 to 2100, or the earlier or later dates in the object up to the end of 2200, with one `RDATE` per line, as vobject reads only the first value of an `RDATE` list in a `VTIMEZONE`. A client that reads the `VTIMEZONE` may show a summer-time date after 2200 off by the daylight saving offset. It is left out where the server hint `save-load.icalendar.olson-tzid` says it is supported, or with `add_vtimezones=False`. diff --git a/tests/test_vcal.py b/tests/test_vcal.py index 8051b8bc..3c8626f3 100644 --- a/tests/test_vcal.py +++ b/tests/test_vcal.py @@ -215,6 +215,21 @@ def test_create_ical_vtimezone_covers_dates_before_1970_and_after_2100(self) -> year, 7, 1, 16, tzinfo=utc ) + def test_create_ical_vtimezone_stops_at_2200(self) -> None: + ## some systems use 9999-12-31 for "no end" + berlin = ZoneInfo("Europe/Berlin") + ical = create_ical( + summary="no end", + dtstart=datetime(2026, 7, 1, 12, tzinfo=berlin), + dtend=datetime(9999, 12, 31, 13, tzinfo=berlin), + ) + vtimezone = icalendar.Calendar.from_ical(ical).timezones[0] + assert len(vtimezone.to_ical()) < 20000 + assert max(vtimezone.get_transitions()[0]).year == 2200 + assert _vobject_utc(ical, "Europe/Berlin", datetime(2026, 7, 1, 12)) == datetime( + 2026, 7, 1, 10, tzinfo=utc + ) + def test_create_ical_adds_no_vtimezone_without_tzid(self) -> None: for value in (datetime(2026, 6, 6, 20, tzinfo=utc), date(2026, 6, 6)): ical = create_ical(summary="no tz", dtstart=value)