JMAPClient – JMAP calendar client#

Synchronous JMAP client.

Wraps session establishment, HTTP communication, and method dispatching into a single object with a clean public API.

Auth note: JMAP has no 401-challenge-retry dance (unlike CalDAV). Credentials are sent upfront on every request. A 401/403 is a hard failure.

class caldav.jmap.client.JMAPClient(url, username=None, password=None, auth=None, auth_type=None, timeout=30)[source][source]#

Synchronous JMAP client for calendar operations.

Usage:

from caldav.jmap import get_jmap_client
client = get_jmap_client(url="https://jmap.example.com/.well-known/jmap",
                          username="alice", password="secret")
calendars = client.get_calendars()
Parameters:

  • url – URL of the JMAP session endpoint (/.well-known/jmap).

  • username – Username for Basic auth.

  • password – Password for Basic auth, or bearer token if no username.

  • auth – A pre-built requests-compatible auth object. Takes precedence over username/password if provided.

  • auth_type – Force a specific auth type: "basic" or "bearer".

  • timeout – HTTP request timeout in seconds.

create_event(calendar_id, ical_str)[source][source]#

Create a calendar event from an iCalendar string.

Return type:

str

Parameters:

  • calendar_id – The JMAP calendar ID to create the event in.

  • ical_str – A VCALENDAR string representing the event.

Returns:

The server-assigned JMAP event ID.

Raises:

JMAPMethodError – If the server rejects the create request.

create_task(task_list_id, title, **kwargs)[source][source]#

Create a task in a task list.

Return type:

str

Parameters:

  • task_list_id – The JMAP task list ID to create the task in.

  • title – Task title (maps to VTODO SUMMARY).

  • **kwargs – Optional JMAP Task fields using wire names: description, due, start, timeZone, estimatedDuration, percentComplete, progress, priority.

Returns:

The server-assigned JMAP task ID.

Raises:

JMAPMethodError – If the server rejects the create request.

delete_event(event_id)[source][source]#

Delete a calendar event.

Return type:

None

Parameters:

event_id – The JMAP event ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

delete_task(task_id)[source][source]#

Delete a task.

Return type:

None

Parameters:

task_id – The JMAP task ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

get_calendars()[source][source]#

Fetch all calendars for the authenticated account.

Return type:

list[JMAPCalendar]

Returns:

List of JMAPCalendar objects.

get_event(event_id)[source][source]#

Fetch a calendar event by JMAP event ID.

Return type:

JMAPCalendarObject

Parameters:

event_id – The JMAP event ID to retrieve.

Returns:

A JMAPCalendarObject wrapping the raw JSCalendar dict. parent is None since no JMAPCalendar is available at the client level.

Raises:

JMAPMethodError – If the event is not found.

get_objects_by_sync_token(sync_token)[source][source]#

Fetch events changed since a previous sync token.

Calls CalendarEvent/changes to discover which events were created, modified, or destroyed since sync_token was issued. Created and modified events are returned as JMAPCalendarObject instances; destroyed events are returned as IDs (the objects no longer exist on the server).

Return type:

tuple[list[JMAPCalendarObject], list[JMAPCalendarObject], list[str]]

Parameters:

sync_token – A state string previously returned by get_sync_token() or by a prior call to this method.

Returns:

  • added: objects for newly created events (parent is None).

  • modified: objects for updated events (parent is None).

  • deleted: Event IDs that were destroyed.

Return type:

A 3-tuple (added, modified, deleted)

Raises:

JMAPMethodError – If the server reports hasMoreChanges: true.

get_sync_token()[source][source]#

Return the current CalendarEvent state string for use as a sync token.

Calls CalendarEvent/get with an empty ID list — no event data is transferred, only the state field from the response.

Return type:

str

Returns:

Opaque state string. Pass to get_objects_by_sync_token() to retrieve only what changed since this point.

get_task(task_id)[source][source]#

Fetch a task by ID.

Return type:

dict

Parameters:

task_id – The JMAP task ID to retrieve.

Returns:

Raw JMAP Task dict as returned by the server.

Raises:

JMAPMethodError – If the task is not found.

get_task_lists()[source][source]#

Fetch all task lists for the authenticated account.

Return type:

list[dict]

Returns:

List of raw JMAP TaskList dicts as returned by the server.

search_events(calendar_id=None, start=None, end=None, text=None)[source][source]#

Search for calendar events.

All parameters are optional; omitting all returns every event in the account. Results are fetched in a single batched JMAP request using a result reference from CalendarEvent/query into CalendarEvent/get.

Return type:

list[JMAPCalendarObject]

Parameters:

  • calendar_id – Limit results to this calendar.

  • start – Only events ending after this datetime (YYYY-MM-DDTHH:MM:SS).

  • end – Only events starting before this datetime (YYYY-MM-DDTHH:MM:SS).

  • text – Free-text search across title, description, locations, and participants.

Returns:

List of JMAPCalendarObject instances. parent is None on these objects since no JMAPCalendar is available at the client level; use JMAPCalendar.search() if you need parent set.

update_event(event_id, ical_str)[source][source]#

Update a calendar event from an iCalendar string.

Return type:

None

Parameters:

  • event_id – The JMAP event ID to update.

  • ical_str – A VCALENDAR string with the updated event data.

Raises:

JMAPMethodError – If the server rejects the update.

update_task(task_id, patch)[source][source]#

Update a task with a partial patch.

Return type:

None

Parameters:

  • task_id – The JMAP task ID to update.

  • patch – Partial patch dict mapping property names to new values.

Raises:

JMAPMethodError – If the server rejects the update.

Asynchronous JMAP client.

Mirrors JMAPClient with all public methods as coroutines. Uses niquests.AsyncSession for HTTP — niquests is a core dependency.

class caldav.jmap.async_client.AsyncJMAPClient(url, username=None, password=None, auth=None, auth_type=None, timeout=30)[source][source]#

Asynchronous JMAP client for calendar operations.

The JMAP support is experimental, the API may change in minor-releases

Usage:

from caldav.jmap import get_async_jmap_client
async with get_async_jmap_client(url="https://jmap.example.com/.well-known/jmap",
                                  username="alice", password="secret") as client:
    calendars = await client.get_calendars()
Parameters:

  • url – URL of the JMAP session endpoint (/.well-known/jmap).

  • username – Username for Basic auth.

  • password – Password for Basic auth, or bearer token if no username.

  • auth – A pre-built niquests-compatible auth object. Takes precedence over username/password if provided.

  • auth_type – Force a specific auth type: "basic" or "bearer".

  • timeout – HTTP request timeout in seconds.

async create_event(calendar_id, ical_str)[source][source]#

Create a calendar event from an iCalendar string.

Return type:

str

Parameters:

  • calendar_id – The JMAP calendar ID to create the event in.

  • ical_str – A VCALENDAR string representing the event.

Returns:

The server-assigned JMAP event ID.

Raises:

JMAPMethodError – If the server rejects the create request.

async create_task(task_list_id, title, **kwargs)[source][source]#

Create a task in a task list.

Return type:

str

Parameters:

  • task_list_id – The JMAP task list ID to create the task in.

  • title – Task title (maps to VTODO SUMMARY).

  • **kwargs – Optional JMAP Task fields using wire names: description, due, start, timeZone, estimatedDuration, percentComplete, progress, priority.

Returns:

The server-assigned JMAP task ID.

Raises:

JMAPMethodError – If the server rejects the create request.

async delete_event(event_id)[source][source]#

Delete a calendar event.

Return type:

None

Parameters:

event_id – The JMAP event ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

async delete_task(task_id)[source][source]#

Delete a task.

Return type:

None

Parameters:

task_id – The JMAP task ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

async get_calendars()[source][source]#

Fetch all calendars for the authenticated account.

Return type:

list[JMAPCalendar]

Returns:

List of JMAPCalendar objects.

async get_event(event_id)[source][source]#

Fetch a calendar event as an iCalendar string.

Return type:

JMAPCalendarObject

Parameters:

event_id – The JMAP event ID to retrieve.

Returns:

A JMAPCalendarObject wrapping the raw JSCalendar dict. parent is None since no JMAPCalendar is available at the client level.

Raises:

JMAPMethodError – If the event is not found.

async get_objects_by_sync_token(sync_token)[source][source]#

Fetch events changed since a previous sync token.

Calls CalendarEvent/changes to discover which events were created, modified, or destroyed since sync_token was issued. Created and modified events are returned as JMAPCalendarObject instances; destroyed events are returned as IDs (the objects no longer exist on the server).

Return type:

tuple[list[JMAPCalendarObject], list[JMAPCalendarObject], list[str]]

Parameters:

sync_token – A state string previously returned by get_sync_token() or by a prior call to this method.

Returns:

  • added: objects for newly created events (parent is None).

  • modified: objects for updated events (parent is None).

  • deleted: Event IDs that were destroyed.

Return type:

A 3-tuple (added, modified, deleted)

Raises:

JMAPMethodError – If the server reports hasMoreChanges: true.

async get_sync_token()[source][source]#

Return the current CalendarEvent state string for use as a sync token.

Calls CalendarEvent/get with an empty ID list — no event data is transferred, only the state field from the response.

Return type:

str

Returns:

Opaque state string. Pass to get_objects_by_sync_token() to retrieve only what changed since this point.

async get_task(task_id)[source][source]#

Fetch a task by ID.

Return type:

dict

Parameters:

task_id – The JMAP task ID to retrieve.

Returns:

Raw JMAP Task dict as returned by the server.

Raises:

JMAPMethodError – If the task is not found.

async get_task_lists()[source][source]#

Fetch all task lists for the authenticated account.

Return type:

list[dict]

Returns:

List of raw JMAP TaskList dicts as returned by the server.

async search_events(calendar_id=None, start=None, end=None, text=None)[source][source]#

Search for calendar events.

All parameters are optional; omitting all returns every event in the account. Results are fetched in a single batched JMAP request using a result reference from CalendarEvent/query into CalendarEvent/get.

Return type:

list[JMAPCalendarObject]

Parameters:

  • calendar_id – Limit results to this calendar.

  • start – Only events ending after this datetime (YYYY-MM-DDTHH:MM:SS).

  • end – Only events starting before this datetime (YYYY-MM-DDTHH:MM:SS).

  • text – Free-text search across title, description, locations, and participants.

Returns:

List of JMAPCalendarObject instances. parent is None on these objects; use JMAPCalendar.search() if you need parent set.

async update_event(event_id, ical_str)[source][source]#

Update a calendar event from an iCalendar string.

Return type:

None

Parameters:

  • event_id – The JMAP event ID to update.

  • ical_str – A VCALENDAR string with the updated event data.

Raises:

JMAPMethodError – If the server rejects the update.

async update_task(task_id, patch)[source][source]#

Update a task with a partial patch.

Return type:

None

Parameters:

  • task_id – The JMAP task ID to update.

  • patch – Partial patch dict mapping property names to new values.

Raises:

JMAPMethodError – If the server rejects the update.