client: 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 calendaring_jmap.client.JMAPClient(url: str, username: str | None = None, password: str | None = None, auth=None, auth_type: str | None = None, timeout: int = 30)[source]#

Bases: _JMAPClientBase

Synchronous JMAP client for calendar operations.

Usage:

from calendaring_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.

close() → None[source]#

Release the persistent HTTP session and its connection pool.

Only needed when the client was not used as a context manager – the documented Quick Start builds one directly, and without this there was no way to hand the sockets back. Idempotent; the session is recreated on the next request.

create_event(calendar_id: str, ical_str: str) → str[source]#

Create a calendar event from an iCalendar string.

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: str, title: str, **kwargs) → str[source]#

Create a task in a task list.

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: str) → None[source]#

Delete a calendar event.

Parameters:

event_id – The JMAP event ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

delete_task(task_id: str) → None[source]#

Delete a task.

Parameters:

task_id – The JMAP task ID to delete.

Raises:

JMAPMethodError – If the server rejects the delete.

get_calendars() → list[JMAPCalendar[Literal[False]]][source]#

Fetch all calendars for the authenticated account.

Returns:

List of JMAPCalendar objects.

get_event(event_id: str) → JMAPCalendarObject[source]#

Fetch a calendar event by JMAP event ID.

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: str) → tuple[list[JMAPCalendarObject], list[JMAPCalendarObject], list[str], str][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).

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.

  • new_sync_token: Pass to the next call to this method as sync_token.

Return type:

A 4-tuple (added, modified, deleted, new_sync_token)

Raises:

JMAPMethodError – If the server reports hasMoreChanges: true.

get_sync_token() → str[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.

Returns:

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

get_task(task_id: str) → dict[source]#

Fetch a task by ID.

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() → list[dict][source]#

Fetch all task lists for the authenticated account.

Returns:

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

search_events(calendar_id: str | None = None, start: str | None = None, end: str | None = None, text: str | None = None) → list[JMAPCalendarObject][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.

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: str, ical_str: str) → None[source]#

Update a calendar event from an iCalendar string.

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: str, patch: dict) → None[source]#

Update a task with a partial patch.

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.