session: JMAP session discovery

JMAP session establishment (RFC 8620 Section 2).

Fetches the Session object from /.well-known/jmap and extracts the information needed to make subsequent API calls.

class calendaring_jmap.session.Session(api_url: str, account_id: str, state: str, account_capabilities: dict = <factory>, server_capabilities: dict = <factory>, upload_url: str | None = None, download_url: str | None = None, raw: dict = <factory>)

Bases: object

Parsed JMAP Session object (RFC 8620 Section 2).

Variables:

• api_url (str) – URL to POST method calls to.

• account_id (str) – The accountId to use for calendar method calls. Chosen from primaryAccounts if available, otherwise the first account advertising the calendars capability.

• state (str) – Current session state string.

• account_capabilities (dict) – Capabilities dict for the chosen account.

• server_capabilities (dict) – Server-level capabilities dict.

• upload_url (str | None) – URI Template (RFC 8620 Section 6.1) for uploading a blob, or None if the server omits it.

• download_url (str | None) – URI Template (RFC 8620 Section 6.2) for downloading a blob, or None if the server omits it.

• raw (dict) – The full parsed Session JSON for anything not captured above.

account_capabilities: dict

account_id: str

api_url: str

download_url: str | None = None

raw: dict

server_capabilities: dict

state: str

upload_url: str | None = None

async calendaring_jmap.session.async_fetch_session(url: str, auth, timeout: int = 30) → Session

Async variant of fetch_session() using niquests.AsyncSession.

Parameters:

• url – Full URL to the JMAP session endpoint.

• auth – A niquests-compatible auth object.

Returns:

Parsed Session with api_url and account_id set.

Raises:

• JMAPAuthError – If the server returns HTTP 401 or 403.

• JMAPCapabilityError – If no account advertises the calendars capability.

calendaring_jmap.session.fetch_session(url: str, auth, timeout: int = 30) → Session

Fetch and parse the JMAP Session object.

Performs a GET request to url (expected to be /.well-known/jmap or equivalent), authenticates with auth, and returns a parsed Session.

Parameters:

• url – Full URL to the JMAP session endpoint.

• auth – A requests-compatible auth object (e.g. HTTPBasicAuth, HTTPBearerAuth).

Returns:

Parsed Session with api_url and account_id set.

Raises:

• JMAPAuthError – If the server returns HTTP 401 or 403.

• JMAPCapabilityError – If no account advertises the calendars capability.

• requests.HTTPError – For other non-2xx responses.