jmap.objects – JMAP data objects#

JMAP Calendar object.

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

class caldav.jmap.objects.calendar.JMAPCalendar(id, name, description=None, color=None, is_subscribed=True, my_rights=<factory>, sort_order=0, is_visible=True)[source][source]#

A JMAP Calendar object.

id[source]#

Server-assigned calendar identifier.

name[source]#

Display name of the calendar.

description[source]#

Optional longer description.

color[source]#

Optional CSS color string (e.g. "#ff0000").

is_subscribed[source]#

Whether the user is subscribed to this calendar.

my_rights[source]#

Dict of right names → bool for the current user.

sort_order[source]#

Hint for display ordering (lower = first).

is_visible[source]#

Whether the calendar should be displayed.

add_event(ical_str)[source][source]#

Add an event to this calendar from an iCalendar string.

Mirrors caldav.collection.Calendar.add_event(). When called on an async-backed calendar, returns a coroutine that must be awaited.

Return type:

str

Parameters:

ical_str – A VCALENDAR string representing the event.

Returns:

The server-assigned JMAP event ID. Unlike the CalDAV equivalent, 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.

classmethod from_jmap(data)[source][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][source]#

Get a calendar object by its iCalendar UID.

Mirrors caldav.collection.Calendar.get_object_by_uid(). When called on an async-backed calendar, returns a coroutine that must be awaited.

Parameters:

  • uid – The iCalendar UID to search for.

  • comp_class – Accepted for API compatibility with the CalDAV interface; 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.

search(**searchargs)[source][source]#

Search for calendar objects in this calendar.

Mirrors caldav.collection.Calendar.search(). 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.

Unknown parameters are silently ignored for backward compatibility.

Returns:

List of JMAPCalendarObject for all matching objects.

to_jmap()[source][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

JMAP error hierarchy.

Extends the existing caldav.lib.error.DAVError base so that JMAP errors integrate naturally with existing exception handling in user code.

RFC 8620 §3.6.2 defines the standard method-level error types.

exception caldav.jmap.error.JMAPAuthError(url=None, reason=None, error_type=None)[source][source]#

HTTP 401 or 403 received from JMAP server.

Unlike CalDAV, JMAP does not use a 401-challenge-retry dance. A 401/403 on the session GET or any API call is a hard failure.

exception caldav.jmap.error.JMAPCapabilityError(url=None, reason=None, error_type=None)[source][source]#

Server does not advertise the required JMAP capability.

Raised when the Session object returned by the server does not include urn:ietf:params:jmap:calendars in the account capabilities.

exception caldav.jmap.error.JMAPError(url=None, reason=None, error_type=None)[source][source]#

Base class for all JMAP errors.

Adds error_type to carry the RFC 8620 error type string (e.g. "unknownMethod", "invalidArguments").

exception caldav.jmap.error.JMAPMethodError(url=None, reason=None, error_type=None)[source][source]#

A JMAP method call returned an error response.

RFC 8620 §3.6.2 error types that may be set as error_type:

  • serverError — unexpected server-side error

  • unknownMethod — method name not recognised

  • invalidArguments — bad argument types or values

  • invalidResultReference — bad #result reference

  • forbidden — not allowed to perform this call

  • accountNotFound — accountId does not exist

  • accountNotSupportedByMethod — account lacks needed capability

  • accountReadOnly — account is read-only

  • requestTooLarge — request exceeds server limits

  • stateMismatch — ifInState check failed

  • serverPartialFail — partial failure; some calls succeeded

  • notFound — requested object does not exist

  • notDraft — object is not in draft state