calendaring-jmap 1.0.0__py3-none-any.whl

calendaring_jmap/__init__.py

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""
+Calendar operations over JMAP (RFC 8620 + JMAP Calendars).
+
+Provides synchronous and asynchronous JMAP clients for calendar listing,
+event CRUD, incremental sync, and task CRUD.
+
+Basic 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()
+
+Async usage::
+
+    from calendaring_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()
+"""
+
+from calendaring_jmap._config import get_connection_params
+from calendaring_jmap._version import __version__
+from calendaring_jmap.async_client import AsyncJMAPClient
+from calendaring_jmap.client import JMAPClient
+from calendaring_jmap.error import (
+    JMAPAuthError,
+    JMAPCapabilityError,
+    JMAPError,
+    JMAPMethodError,
+)
+from calendaring_jmap.objects.calendar import JMAPCalendar
+from calendaring_jmap.objects.calendar_object import JMAPCalendarObject
+
+_JMAP_KEYS = {"url", "username", "password", "auth_type", "timeout"}
+
+
+def get_jmap_client(**kwargs) -> JMAPClient | None:
+    """Create a :class:`JMAPClient` from configuration.
+
+    Configuration is read in priority order:
+
+    1. Explicit keyword arguments (``url``, ``username``, ``password``, …)
+    2. Environment variables (``JMAP_URL``, ``JMAP_USERNAME``, …)
+    3. A YAML config file (``~/.config/calendaring-jmap/calendar.yaml`` or equivalent)
+
+    Returns ``None`` if no configuration is found, rather than raising.
+
+    Example::
+
+        client = get_jmap_client(url="https://jmap.example.com/.well-known/jmap",
+                                  username="alice", password="secret")
+    """
+    conn_params = get_connection_params(**kwargs)
+    if conn_params is None:
+        return None
+    return JMAPClient(**{k: v for k, v in conn_params.items() if k in _JMAP_KEYS})
+
+
+def get_async_jmap_client(**kwargs) -> AsyncJMAPClient | None:
+    """Create an :class:`AsyncJMAPClient` from configuration.
+
+    Accepts the same arguments and reads configuration from the same sources
+    as :func:`get_jmap_client`. Returns ``None`` if no configuration is found.
+
+    Example::
+
+        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()
+    """
+    conn_params = get_connection_params(**kwargs)
+    if conn_params is None:
+        return None
+    return AsyncJMAPClient(**{k: v for k, v in conn_params.items() if k in _JMAP_KEYS})
+
+
+__all__ = [
+    "AsyncJMAPClient",
+    "JMAPAuthError",
+    "JMAPCalendar",
+    "JMAPCalendarObject",
+    "JMAPCapabilityError",
+    "JMAPClient",
+    "JMAPError",
+    "JMAPMethodError",
+    "__version__",
+    "get_async_jmap_client",
+    "get_jmap_client",
+]

calendaring_jmap/_config.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Standalone configuration loading for calendaring-jmap.
+
+Resolves connection parameters in priority order:
+
+1. Explicit keyword arguments
+2. Environment variables (``JMAP_URL``, ``JMAP_USERNAME``, ``JMAP_PASSWORD``,
+   ``JMAP_AUTH_TYPE``, ``JMAP_TIMEOUT``)
+3. A YAML config file (``JMAP_CONFIG_FILE`` env var, or
+   ``~/.config/calendaring-jmap/calendar.yaml``)
+
+Returns ``None`` if none of the three sources yields a URL, rather than
+raising. Callers decide whether "no configuration" is an error.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+_CONN_KEYS = {"url", "username", "password", "auth_type", "timeout"}
+_DEFAULT_CONFIG_PATH = Path.home() / ".config" / "calendaring-jmap" / "calendar.yaml"
+
+
+_ENV_VARS = {
+    "url": "JMAP_URL",
+    "username": "JMAP_USERNAME",
+    "password": "JMAP_PASSWORD",
+    "auth_type": "JMAP_AUTH_TYPE",
+    "timeout": "JMAP_TIMEOUT",
+}
+
+
+def _from_environment() -> dict[str, Any]:
+    env: dict[str, Any] = {}
+    for key, var in _ENV_VARS.items():
+        value = os.environ.get(var)
+        if value:
+            env[key] = int(value) if key == "timeout" else value
+    return env
+
+
+def _from_config_file(config_file: str | Path | None) -> dict[str, Any]:
+    path = Path(config_file) if config_file else _DEFAULT_CONFIG_PATH
+    if not path.is_file():
+        return {}
+
+    import yaml
+
+    with path.open("rb") as f:
+        data = yaml.safe_load(f) or {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if k in _CONN_KEYS}
+
+
+def get_connection_params(
+    config_file: str | Path | None = None,
+    **explicit_params: Any,
+) -> dict[str, Any] | None:
+    """Resolve JMAP connection parameters from kwargs, env vars, or a config file.
+
+    Args:
+        config_file: Explicit path to a YAML config file. Defaults to the
+            ``JMAP_CONFIG_FILE`` environment variable, then
+            ``~/.config/calendaring-jmap/calendar.yaml``.
+        **explicit_params: ``url``, ``username``, ``password``, ``auth_type``,
+            ``timeout``. A value of ``None`` is treated as "not supplied",
+            not "unset": this lets a thin CLI wrapper pass every option
+            through unconditionally without wiping out env vars for the
+            ones the user left off.
+
+    Returns:
+        A dict of connection parameters, or ``None`` if no source yields a URL.
+    """
+    explicit = {k: v for k, v in explicit_params.items() if k in _CONN_KEYS and v is not None}
+    if explicit.get("url"):
+        return explicit
+
+    env = _from_environment()
+    if env.get("url"):
+        return {**env, **explicit}
+
+    file_config = _from_config_file(config_file or os.environ.get("JMAP_CONFIG_FILE"))
+    if file_config.get("url"):
+        return {**file_config, **env, **explicit}
+
+    return None

calendaring_jmap/_http.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""HTTP library selection, imported once for the whole package.
+
+Everything that needs niquests-or-requests takes it from here rather than
+repeating the fallback. ``requests`` is niquests when niquests is installed:
+the name is the one the API is compatible with, not necessarily the package
+that provides it.
+"""
+
+from typing import Any
+
+_DOCS_URL = "https://calendaring-jmap.readthedocs.io/"
+
+USE_NIQUESTS = False
+USE_REQUESTS = False
+
+## niquests' AsyncSession has no requests equivalent, so it's None on the
+## fallback. The async client is the only thing that needs it; it goes
+## through require_async_session() for a clear error instead of a
+## TypeError on None.
+AsyncSession: Any = None
+
+try:
+    import niquests as requests
+    from niquests.auth import AuthBase, HTTPBasicAuth
+
+    USE_NIQUESTS = True
+except ImportError:
+    try:
+        import requests  # type: ignore[no-redef]
+        from requests.auth import (  # type: ignore[assignment]
+            AuthBase,
+            HTTPBasicAuth,
+        )
+
+        USE_REQUESTS = True
+    except ImportError as e:
+        raise ImportError(
+            "calendaring-jmap needs an HTTP library, and none of the supported "
+            "ones is installed (tried: niquests, requests). Install one; "
+            "`pip install niquests` is the recommended choice. "
+            f"See {_DOCS_URL} for details."
+        ) from e
+
+if USE_NIQUESTS:
+    ## Deliberately its own try: an ImportError here must not fall through to
+    ## the requests branch and flip USE_NIQUESTS off on an install that does
+    ## have niquests. Only the async client needs this.
+    try:
+        from niquests import AsyncSession
+    except ImportError:
+        ## Old niquests without AsyncSession: leave it None, and let
+        ## require_async_session() explain it if anything asks for it.
+        pass
+
+
+def require_async_session() -> Any:
+    """Return niquests' ``AsyncSession``, or explain why there isn't one.
+
+    The async client is built on it and has no fallback.
+    """
+    if AsyncSession is None:
+        reason = "an old niquests install without AsyncSession" if USE_NIQUESTS else "not installed"
+        raise ImportError(
+            f"The async JMAP client requires niquests with AsyncSession support ({reason}). "
+            "Unlike the sync client it has no fallback to another HTTP library. "
+            f"Install or upgrade it with `pip install -U niquests`. See {_DOCS_URL} for details."
+        )
+    return AsyncSession
+
+
+class HTTPBearerAuth(AuthBase):
+    """Bearer token authentication for niquests/requests."""
+
+    def __init__(self, password: str) -> None:
+        self.password = password
+
+    def __eq__(self, other: object) -> bool:
+        return self.password == getattr(other, "password", None)
+
+    def __ne__(self, other: object) -> bool:
+        return not self == other
+
+    def __call__(self, r):
+        r.headers["Authorization"] = f"Bearer {self.password}"
+        return r
+
+
+__all__ = [
+    "AsyncSession",
+    "AuthBase",
+    "HTTPBasicAuth",
+    "HTTPBearerAuth",
+    "USE_NIQUESTS",
+    "USE_REQUESTS",
+    "requests",
+    "require_async_session",
+]

calendaring_jmap/_methods/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+
+def parse_set_response(response_args: dict) -> tuple[dict, dict, list[str], dict, dict, dict]:
+    """Parse the arguments dict from any JMAP ``*/set`` method response.
+
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    """
+    created: dict = response_args.get("created") or {}
+    updated: dict = response_args.get("updated") or {}
+    destroyed: list[str] = response_args.get("destroyed") or []
+    not_created: dict = response_args.get("notCreated") or {}
+    not_updated: dict = response_args.get("notUpdated") or {}
+    not_destroyed: dict = response_args.get("notDestroyed") or {}
+    return created, updated, destroyed, not_created, not_updated, not_destroyed

calendaring_jmap/_methods/calendar.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""
+JMAP Calendar method builders and response parsers.
+
+These are pure functions — no HTTP, no state. They build the request
+tuples that go into a ``methodCalls`` list, and parse the corresponding
+``methodResponses`` entries.
+
+Method shapes follow RFC 8620 §3.3 (get), §3.4 (changes), §3.5 (set); Calendar-specific
+properties are defined in the JMAP Calendars specification.
+"""
+
+from __future__ import annotations
+
+from calendaring_jmap.objects.calendar import JMAPCalendar
+
+
+def build_calendar_get(
+    account_id: str,
+    ids: list[str] | None = None,
+    properties: list[str] | None = None,
+) -> tuple:
+    """Build a ``Calendar/get`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        ids: List of calendar IDs to fetch, or ``None`` to fetch all.
+        properties: List of property names to return, or ``None`` for all.
+
+    Returns:
+        A 3-tuple ``("Calendar/get", arguments_dict, call_id)`` suitable
+        for inclusion in a ``methodCalls`` list.
+    """
+    args: dict = {"accountId": account_id, "ids": ids}
+    if properties is not None:
+        args["properties"] = properties
+    return ("Calendar/get", args, "cal-get-0")
+
+
+def parse_calendar_get(response_args: dict) -> list[JMAPCalendar]:
+    """Parse the arguments dict from a ``Calendar/get`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"Calendar/get"``.
+
+    Returns:
+        List of :class:`~calendaring_jmap.objects.calendar.JMAPCalendar` objects.
+        Returns an empty list if ``"list"`` is absent or empty.
+    """
+    return [JMAPCalendar.from_jmap(item) for item in response_args.get("list", [])]
+
+
+def build_calendar_changes(account_id: str, since_state: str) -> tuple:
+    """Build a ``Calendar/changes`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        since_state: The ``state`` string from a previous ``Calendar/get``
+            or ``Calendar/changes`` response.
+
+    Returns:
+        A 3-tuple ``("Calendar/changes", arguments_dict, call_id)``.
+    """
+    return (
+        "Calendar/changes",
+        {"accountId": account_id, "sinceState": since_state},
+        "cal-changes-0",
+    )

calendaring_jmap/_methods/event.py

@@ -0,0 +1,271 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""
+JMAP CalendarEvent method builders and response parsers.
+
+These are pure functions — no HTTP, no state. They build the request
+tuples that go into a ``methodCalls`` list, and parse the corresponding
+``methodResponses`` entries.
+
+Method shapes follow RFC 8620 §3.3 (get), §3.4 (changes), §3.5 (set),
+§3.6 (query), §3.7 (queryChanges); CalendarEvent-specific properties are
+defined in the JMAP Calendars specification.
+"""
+
+from __future__ import annotations
+
+from calendaring_jmap._methods import parse_set_response
+
+
+def build_event_get(
+    account_id: str,
+    ids: list[str] | None = None,
+    properties: list[str] | None = None,
+) -> tuple:
+    """Build a ``CalendarEvent/get`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        ids: List of event IDs to fetch, or ``None`` to fetch all.
+        properties: List of property names to return, or ``None`` for all.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/get", arguments_dict, call_id)`` suitable
+        for inclusion in a ``methodCalls`` list.
+    """
+    args: dict = {"accountId": account_id, "ids": ids}
+    if properties is not None:
+        args["properties"] = properties
+    return ("CalendarEvent/get", args, "ev-get-0")
+
+
+def parse_event_get(response_args: dict) -> list[dict]:
+    """Parse the arguments dict from a ``CalendarEvent/get`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"CalendarEvent/get"``.
+
+    Returns:
+        List of raw JSCalendar dicts as returned by the server.
+        Returns an empty list if ``"list"`` is absent or empty.
+    """
+    return list(response_args.get("list", []))
+
+
+def build_event_changes(
+    account_id: str,
+    since_state: str,
+    max_changes: int | None = None,
+) -> tuple:
+    """Build a ``CalendarEvent/changes`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        since_state: The ``state`` string from a previous ``CalendarEvent/get``
+            or ``CalendarEvent/changes`` response.
+        max_changes: Optional upper bound on the number of changes returned.
+            The server may return fewer.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/changes", arguments_dict, call_id)``.
+    """
+    args: dict = {"accountId": account_id, "sinceState": since_state}
+    if max_changes is not None:
+        args["maxChanges"] = max_changes
+    return ("CalendarEvent/changes", args, "ev-changes-0")
+
+
+def parse_event_changes(
+    response_args: dict,
+) -> tuple[str, str, bool, list[str], list[str], list[str]]:
+    """Parse the arguments dict from a ``CalendarEvent/changes`` response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"CalendarEvent/changes"``.
+
+    Returns:
+        A 6-tuple ``(old_state, new_state, has_more_changes, created, updated, destroyed)``:
+
+        - ``old_state``: Echo of the ``sinceState`` argument.
+        - ``new_state``: State string to store as the next sync token.
+        - ``has_more_changes``: True if the server capped the response.
+        - ``created``: IDs of newly created events.
+        - ``updated``: IDs of modified events.
+        - ``destroyed``: IDs of deleted events.
+    """
+    return (
+        response_args.get("oldState", ""),
+        response_args.get("newState", ""),
+        response_args.get("hasMoreChanges", False),
+        response_args.get("created") or [],
+        response_args.get("updated") or [],
+        response_args.get("destroyed") or [],
+    )
+
+
+def build_event_query(
+    account_id: str,
+    filter_condition: dict | None = None,
+    sort: list[dict] | None = None,
+    position: int = 0,
+    limit: int | None = None,
+) -> tuple:
+    """Build a ``CalendarEvent/query`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        filter_condition: A ``FilterCondition`` or ``FilterOperator`` dict, e.g.
+            ``{"after": "2024-01-01T00:00:00Z", "before": "2024-12-31T23:59:59Z"}``.
+            ``None`` means no filter (return all events).
+        sort: List of ``Comparator`` dicts, e.g.
+            ``[{"property": "start", "isAscending": True}]``.
+            ``None`` means server default ordering.
+        position: Zero-based index of the first result to return.
+        limit: Maximum number of IDs to return. ``None`` means no limit.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/query", arguments_dict, call_id)``.
+    """
+    args: dict = {"accountId": account_id, "position": position}
+    if filter_condition is not None:
+        args["filter"] = filter_condition
+    if sort is not None:
+        args["sort"] = sort
+    if limit is not None:
+        args["limit"] = limit
+    return ("CalendarEvent/query", args, "ev-query-0")
+
+
+def parse_event_query(response_args: dict) -> tuple[list[str], str, int]:
+    """Parse the arguments dict from a ``CalendarEvent/query`` response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"CalendarEvent/query"``.
+
+    Returns:
+        A 3-tuple ``(ids, query_state, total)``:
+
+        - ``ids``: Ordered list of matching event IDs.
+        - ``query_state``: Opaque state string for use with
+          ``CalendarEvent/queryChanges``.
+        - ``total``: Total number of matching events (may exceed ``len(ids)``
+          when a limit was applied).
+    """
+    ids: list[str] = response_args.get("ids", [])
+    query_state: str = response_args.get("queryState", "")
+    total: int = response_args.get("total", len(ids))
+    return ids, query_state, total
+
+
+def build_event_query_changes(
+    account_id: str,
+    since_query_state: str,
+    filter_condition: dict | None = None,
+    sort: list[dict] | None = None,
+    max_changes: int | None = None,
+) -> tuple:
+    """Build a ``CalendarEvent/queryChanges`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        since_query_state: The ``queryState`` string from a previous
+            ``CalendarEvent/query`` or ``CalendarEvent/queryChanges`` response.
+        filter_condition: Same filter as the original ``CalendarEvent/query`` call.
+        sort: Same sort as the original ``CalendarEvent/query`` call.
+        max_changes: Optional upper bound on the number of changes returned.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/queryChanges", arguments_dict, call_id)``.
+    """
+    args: dict = {"accountId": account_id, "sinceQueryState": since_query_state}
+    if filter_condition is not None:
+        args["filter"] = filter_condition
+    if sort is not None:
+        args["sort"] = sort
+    if max_changes is not None:
+        args["maxChanges"] = max_changes
+    return ("CalendarEvent/queryChanges", args, "ev-qchanges-0")
+
+
+def build_event_set_create(
+    account_id: str,
+    events: dict[str, dict],
+) -> tuple:
+    """Build a ``CalendarEvent/set`` method call for creating events.
+
+    Args:
+        account_id: The JMAP accountId.
+        events: Map of client-assigned creation ID → JSCalendar dict.
+            The creation IDs are ephemeral — they are used to correlate
+            server responses with individual creation requests within the
+            same batch call.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/set", arguments_dict, call_id)``.
+    """
+    return (
+        "CalendarEvent/set",
+        {
+            "accountId": account_id,
+            "create": dict(events),
+        },
+        "ev-set-create-0",
+    )
+
+
+def build_event_set_update(
+    account_id: str,
+    updates: dict[str, dict],
+) -> tuple:
+    """Build a ``CalendarEvent/set`` method call for updating events.
+
+    Args:
+        account_id: The JMAP accountId.
+        updates: Map of event ID → partial patch dict.  Keys are property
+            names (or JSON Pointer paths for nested properties); values are
+            the new values.  Use ``None`` as a value to reset a property to
+            its server default.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/set", arguments_dict, call_id)``.
+    """
+    return (
+        "CalendarEvent/set",
+        {"accountId": account_id, "update": updates},
+        "ev-set-update-0",
+    )
+
+
+def build_event_set_destroy(
+    account_id: str,
+    ids: list[str],
+) -> tuple:
+    """Build a ``CalendarEvent/set`` method call for destroying events.
+
+    Args:
+        account_id: The JMAP accountId.
+        ids: List of event IDs to destroy.
+
+    Returns:
+        A 3-tuple ``("CalendarEvent/set", arguments_dict, call_id)``.
+    """
+    return (
+        "CalendarEvent/set",
+        {"accountId": account_id, "destroy": ids},
+        "ev-set-destroy-0",
+    )
+
+
+def parse_event_set(
+    response_args: dict,
+) -> tuple[dict, dict, list[str], dict, dict, dict]:
+    """Parse the arguments dict from a ``CalendarEvent/set`` method response.
+
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    See :func:`calendaring_jmap._methods.parse_set_response` for field semantics.
+    """
+    return parse_set_response(response_args)