convert: JSCalendar and iCalendar conversion

ical_to_jscal and jscal_to_ical convert between iCalendar text and JSCalendar dicts directly, with no JMAP client or network connection involved.

JSCalendar and iCalendar conversion utilities.

Public API:

ical_to_jscal(ical_str, calendar_id=None) -> dict jscal_to_ical(jscal) -> str

iCalendar to JSCalendar conversion (RFC 5545 to RFC 8984).

Public API:

ical_to_jscal(ical_str, calendar_id=None) -> dict

The output dict is a raw JSCalendar CalendarEvent object suitable for passing directly to CalendarEvent/set.

calendaring_jmap.convert.ical_to_jscal.ical_to_jscal(ical_str: str, calendar_id: str | None = None) → dict

Convert an iCalendar string to a JSCalendar CalendarEvent dict (RFC 8984).

Processes the first VEVENT found in the string. Any sibling VEVENTs with a RECURRENCE-ID are folded into the recurrenceOverrides map of the master event. EXDATE entries are also added to recurrenceOverrides.

Parameters:

• ical_str – A VCALENDAR string (or bare VEVENT; fixup() normalises it).

• calendar_id – If provided, sets calendarIds: {calendar_id: true} on the output. Required when the result will be used in CalendarEvent/set (the server needs to know which calendar).

Returns:

Raw JSCalendar dict suitable for passing directly to CalendarEvent/set.

Raises:

ValueError – If no VEVENT component is found; the master VEVENT is missing UID or DTSTART (both mandatory per RFC 5545, but not every producer enforces this); DTSTART/DTEND have mismatched value types, one DATE and one DATE-TIME (RFC 5545 Section 3.8.2.2 requires both to match, and DTEND to be later in time than DTSTART); or DTEND/DURATION resolves to before DTSTART (RFC 8984 Section 5.1.2 requires duration to be zero or positive).

JSCalendar to iCalendar conversion (RFC 8984 to RFC 5545).

Public API:

jscal_to_ical(jscal: dict) -> str

Accepts a raw JSCalendar CalendarEvent dict (as returned by CalendarEvent/get or produced by ical_to_jscal). Returns a VCALENDAR string.

calendaring_jmap.convert.jscal_to_ical.jscal_to_ical(jscal: dict) → str

Convert a JSCalendar CalendarEvent dict to an iCalendar VCALENDAR string.

Handles the full set of fields supported by ical_to_jscal for round-trip fidelity. recurrenceOverrides entries with excluded: true become EXDATE properties; patch dicts become child VEVENTs with RECURRENCE-ID.

Parameters:

jscal – A raw JSCalendar CalendarEvent dict as returned by CalendarEvent/get.

Returns:

An iCalendar VCALENDAR string, normalised by fixup.

Raises:

ValueError – If uid is absent or empty (mandatory per RFC 8984 Section 4.1.2; a server response should always include it, but emitting an UID-less VEVENT, invalid per RFC 5545, would be a worse failure mode than raising here).