Skip to content

fix: add the missing VTIMEZONE to objects built from arguments - #852

Merged
tobixen merged 6 commits into
python-caldav:masterfrom
ivenos:add-vtimezone
Nov 8, 2026
Merged

tobixen merged 6 commits into
python-caldav:masterfrom
ivenos:add-vtimezone

Conversation

@ivenos

@ivenos ivenos commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Objects built from keyword arguments (add_event(dtstart=...), add_todo(due=...) with a time zone other than UTC) get a TZID but no VTIMEZONE, which RFC 5545 section 3.6.5 requires. Home Assistant creates its events this way, and Synology's web UI shows them shifted by the UTC offset (home-assistant/core#172990, details in #849).

create_ical() now adds the missing VTIMEZONEs, built with icalendar's Timezone.from_tzid() like its Calendar.add_missing_timezones() does. I don't call that method because before icalendar 7.0.3 it raises a KeyError when an ical_fragment has a VTIMEZONE that no property refers to, and icalendar-searcher allows 6.2. Calendar leaves them out where save-load.icalendar.olson-tzid from #850 is supported, with a plain is_supported() passed on as create_ical(add_vtimezones=False); add_event(add_vtimezones=False) does the same per call. The default unsupported and Synology's fragile keep them, so a client without a profile, like Home Assistant, sends them.

Two adjustments for vobject 0.9.9, which backs vobject_instance: icalendar writes the transitions as one RDATE list per observance and vobject only reads the first value, which puts the time an hour off for half of every year, so the RDATEs go one per line. And icalendar stops at 2038, after which vobject keeps the last offset, so the range runs to 2100. That makes the VTIMEZONE about 6 KB. The VTIMEZONEs go after the event, so subcomponents[0] stays the event as the docs use it, and a VTIMEZONE that comes in with the ical_fragment is left alone.

complete(handle_rrule=True, rrule_mode="thisandfuture") treated every component as an instance of the task, the first as the series and the last as the one to complete. That already breaks today with KeyError: 'RRULE' for any task that has its VTIMEZONE before the VTODO, the usual order in tasks from other clients, and with this change it would complete the new VTIMEZONE after the VTODO instead of the task. It skips VTIMEZONE components now, which is why it's in this PR.

Tested with the unit tests on Python 3.10 and 3.14 with icalendar 6.2, 6.3.1, 7.0.2 and 7.3 (the new tests that expect a VTIMEZONE fail without the fix), the suite with the embedded Radicale and Xandikos, and by hand: earlier against Radicale, Xandikos, Baikal, Nextcloud and SOGo, where the events are stored with the VTIMEZONE, the server's time-range filter finds them, and vobject and icalendar read the right time back, also in 2060 (SOGo's filter misses the 2060 event with or without this change). Now against Baikal and Xandikos without a profile, with their own and with synology: the VTIMEZONE goes out without a profile and with synology, the bare TZID with theirs, and the filter and vobject get the time right either way. A thisandfuture completion of a task with a time zone saves in every case.

Not covered: set_due()/set_dtstart() on existing objects, an ical_fragment given as plain property lines, and tzinfos without an IANA name. Timezone.from_tzid() can also miss offset changes that last less than 64 days, so vobject reads Africa/Casablanca during Ramadan 2024 an hour off, where it got it right from the zone name before. That's for icalendar to fix.

Fixes #849.

Written with Claude Opus 5.5, the prompts are in the commit message.

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 python-caldav#849

Prompt (translated from German): yes [build the VTIMEZONE fix for python-caldav]

Followup-Prompt: python-caldav#849 [after python-caldav#850 and python-caldav#851 were merged]

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
@tobixen

tobixen commented Nov 8, 2026

Copy link
Copy Markdown
Member

My opus found some few nits, I'll just push the fixes to this PR unless you mind

python-caldav#852 added the
add_vtimezones keyword without mentioning it in the docstring.

Prompt: PR python-caldav#852, review [python-caldav#852]

Followup-Prompt: add the docstring and merge

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
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 <noreply@anthropic.com>
Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
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 <noreply@anthropic.com>
Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
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 <noreply@anthropic.com>
Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
@ivenos

ivenos commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

One thing in 6ed9b12: a date in 9999 now crashes, datetime.date(max(...) + 1, 1, 1) raises ValueError: year must be in 1..9999, not 10000 before the try, e.g. with dtend=datetime(9999, 12, 31, 13, tzinfo=ZoneInfo("Europe/Berlin")), which some systems use for "no end". The size has no upper bound either, a date in 2500 gives a 23 KB VTIMEZONE, 9998 about 350 KB. Capping the last year at around 2200 would cover both. The changelog fragment still says 1970 to 2100.

@tobixen

tobixen commented Nov 8, 2026

Copy link
Copy Markdown
Member

I somehow doubt the timezones we're using today will still be valid in year 9999, but some systems using year 9999 as a sentinel is a valid argument.

Sorry for not merging yet, I got interrupted earlier today. I'll have a look at the year 9999-issue before merging.

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 python-caldav#852 (comment)]

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-by: Tobias Brox <tobias@redpill-linpro.com>
@tobixen
tobixen merged commit aa7cf72 into python-caldav:master Nov 8, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Objects built from arguments have a TZID but no VTIMEZONE

2 participants