feat(jmap): add AsyncJMAPClient mirroring public methods as coroutines

Author: SashankBhamidi

caldav/jmap/__init__.py

@@ -1,8 +1,8 @@
 """
 JMAP calendar support for python-caldav.
 
-Provides a synchronous JMAP client with the same public API as the
-CalDAV client, so user code works regardless of server protocol.
+Provides synchronous and asynchronous JMAP clients with the same public API as
+the CalDAV client, so user code works regardless of server protocol.
 
 Basic usage::
 
@@ -14,8 +14,20 @@
         password="secret",
     )
     calendars = client.get_calendars()
+
+Async 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()
 """
 
+from caldav.jmap.async_client import AsyncJMAPClient
 from caldav.jmap.client import JMAPClient
 from caldav.jmap.error import (
     JMAPAuthError,
@@ -24,6 +36,8 @@
     JMAPMethodError,
 )
 
+_JMAP_KEYS = {"url", "username", "password", "auth", "auth_type", "timeout"}
+
 
 def get_jmap_client(**kwargs) -> JMAPClient | None:
     """Create a :class:`JMAPClient` from configuration.
@@ -47,17 +61,36 @@ def get_jmap_client(**kwargs) -> JMAPClient | None:
     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.
 
-    # Strip CalDAV-only keys that JMAPClient does not accept.
-    _JMAP_KEYS = {"url", "username", "password", "auth", "auth_type", "timeout"}
-    jmap_params = {k: v for k, v in conn_params.items() if k in _JMAP_KEYS}
+    Accepts the same arguments and reads configuration from the same sources
+    as :func:`get_jmap_client`. Returns ``None`` if no configuration is found.
 
-    return JMAPClient(**jmap_params)
+    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()
+    """
+    from caldav.config import get_connection_params
+
+    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__ = [
     "JMAPClient",
+    "AsyncJMAPClient",
     "get_jmap_client",
+    "get_async_jmap_client",
     "JMAPError",
     "JMAPCapabilityError",
     "JMAPAuthError",