calendaring_jmap.objects.calendar module#

JMAP Calendar object.

Represents a JMAP Calendar resource as returned by Calendar/get. Properties are defined in the JMAP Calendars specification.

class calendaring_jmap.objects.calendar.JMAPCalendar[_M: bool](id, name, description=None, color=None, is_subscribed=True, my_rights=dict(), sort_order=0, is_visible=True, time_zone=None, share_with=None, default_alerts_with_time=None, default_alerts_without_time=None)[source]#

Bases: Generic[_M]

A JMAP Calendar object.

Variables:

id (str) – Server-assigned calendar identifier.
name (str) – Display name of the calendar. Per-user: a sharee who sets this gets their own copy, leaving the owner's name unchanged.
description (str | None) – Optional longer description.
color (str | None) – Optional CSS color string (e.g. "#ff0000"). Per-user, same override rule as name.
is_subscribed (bool) – Whether the user is subscribed to this calendar.
my_rights (dict) – Dict of right names to bool for the current user.
sort_order (int) – Hint for display ordering (lower = first). Per-user.
is_visible (bool) – Whether the calendar should be displayed. Per-user.
time_zone (str | None) – IANA time zone used to resolve floating events on this calendar (e.g. for alerts, availability). None falls back to the account's own time zone. Per-user, same override rule as name.
share_with (dict | None) – Map of Principal ID to a dict of right names to bool (mayReadItems, mayWriteAll, etc.). Only visible to and settable by users with the mayShare right; the server returns None here for anyone else. Not per-user: this is the calendar's actual sharing configuration.
default_alerts_with_time (dict | None) – Map of alert ID to Alert dict, applied to new timed events on this calendar when useDefaultAlerts is set. Per-user, not inherited from the owner.
default_alerts_without_time (dict | None) – Same as default_alerts_with_time, for all-day events.

add_event(ical_str)[source]#

Add an event to this calendar from an iCalendar string.

Overloads:

ical_str (str) → str
ical_str (str) → Coroutine[Any, Any, str]

When called on an async-backed calendar, returns a coroutine that must be awaited.

Parameters:

ical_str (str) – A VCALENDAR string representing the event.

Returns:

The server-assigned JMAP event ID. This returns a string ID rather than a calendar object: the CalendarEvent/set response does not include the full object, so a follow-up GET would be required.

Raises:

JMAPMethodError – If the server rejects the create request.
ValueError – If ical_str is malformed in a way ical_to_jscal rejects (missing UID/DTSTART, a negative duration, mismatched DTSTART/DTEND value types).

color: str | None = None#

default_alerts_with_time: dict | None = None#

default_alerts_without_time: dict | None = None#

description: str | None = None#

classmethod from_jmap(data)[source]#

Construct a JMAPCalendar from a raw JMAP Calendar JSON dict.

Unknown keys in data are silently ignored so that forward compatibility is maintained as the spec evolves.

Return type:: JMAPCalendar

get_object_by_uid(uid, comp_class=None)[source]#

Get a calendar object by its iCalendar UID.

Overloads:

uid (str), comp_class (Any) = None → JMAPCalendarObject
uid (str), comp_class (Any) = None → Coroutine[Any, Any, JMAPCalendarObject]

When called on an async-backed calendar, returns a coroutine that must be awaited.

Parameters:

uid (str) – The iCalendar UID to search for.
comp_class (Any) – JMAP CalendarEvent/query has no native component-type filter, so this argument is currently ignored.

Returns:

A JMAPCalendarObject for the matching object.

Raises:

JMAPMethodError – If no object with this UID is found.

id: str#

is_subscribed: bool = True#

is_visible: bool = True#

my_rights: dict#

name: str#

search(**searchargs)[source]#

Search for calendar objects in this calendar.

Overloads:

**searchargs (Any) → list[JMAPCalendarObject]
**searchargs (Any) → Coroutine[Any, Any, list[JMAPCalendarObject]]

When called on an async-backed calendar, returns a coroutine that must be awaited.

Accepted keyword arguments (all optional):

start (datetime or str): only events ending after this time (maps to JMAP after filter).
end (datetime or str): only events starting before this time (maps to JMAP before filter).
text (str): free-text search across title, description, locations, and participants.
has_attachment (bool), participant_email (str), participation_status (str), participant_role (str): see search_events().

Does not support position/limit/calculate_total: unlike search_events(), this always returns every matching object in one call. Passing them is silently ignored rather than an error, since this accepts **searchargs; use search_events directly instead if you need to page through a large result set.

Returns:: List of JMAPCalendarObject for all matching objects.

share_with: dict | None = None#

sort_order: int = 0#

time_zone: str | None = None#

to_jmap()[source]#

Serialise to a JMAP Calendar JSON dict for Calendar/set.

id and myRights are intentionally excluded, both are server-set and must not appear in create or update payloads. Optional fields are included only when they hold a non-default value.

Return type:: dict