matrix-python 1.0.0b0__py3-none-any.whl → 1.0.1__py3-none-any.whl

matrix/__init__.py

@@ -8,21 +8,32 @@ except PackageNotFoundError:
     from matrix._version import version as __version__
 
 from .bot import Bot
-from .group import Group
+from .group import Group, group
 from .config import Config
 from .context import Context
 from .command import Command
 from .help import HelpCommand
-from .checks import cooldown
+from .checks import cooldown, is_admin, is_moderator
 from .room import Room
+from .space import Space
+from .message import Message
+from .extension import Extension
+from .component import Table
 
 __all__ = [
     "Bot",
     "Group",
+    "group",
     "Config",
     "Command",
     "Context",
     "HelpCommand",
     "cooldown",
+    "is_admin",
+    "is_moderator",
     "Room",
+    "Space",
+    "Message",
+    "Extension",
+    "Table",
 ]

matrix/_error_handler.py

@@ -0,0 +1,14 @@
+import inspect
+from typing import Callable, Dict, Optional, TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def resolve_error_handler(
+    handlers: Dict[type[Exception], F], error: Exception
+) -> Optional[F]:
+    """Look up the handler registered for the error's type or nearest base class."""
+    for cls in inspect.getmro(type(error)):
+        if cls in handlers:
+            return handlers[cls]
+    return None

matrix/_version.py

@@ -1,5 +1,6 @@
-# file generated by setuptools-scm
+# file generated by vcs-versioning
 # don't change, don't track in version control
+from __future__ import annotations
 
 __all__ = [
     "__version__",
@@ -10,25 +11,14 @@ __all__ = [
     "commit_id",
 ]
 
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-    from typing import Union
-
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-    COMMIT_ID = Union[str, None]
-else:
-    VERSION_TUPLE = object
-    COMMIT_ID = object
-
 version: str
 __version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-commit_id: COMMIT_ID
-__commit_id__: COMMIT_ID
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
 
-__version__ = version = '1.0.0b0'
-__version_tuple__ = version_tuple = (1, 0, 0, 'b0')
+__version__ = version = '1.0.1'
+__version_tuple__ = version_tuple = (1, 0, 1)
 
-__commit_id__ = commit_id = None
+__commit_id__ = commit_id = 'g8e6ddd04d'

matrix/api.py

@@ -0,0 +1,111 @@
+import asyncio
+from typing import Awaitable, Callable, Iterable, TypeVar
+
+from nio import ErrorResponse, Response
+
+from matrix.errors import MatrixApiError
+
+T = TypeVar("T", bound=Response)
+R = TypeVar("R")
+
+
+async def matrix_call(coro: Awaitable[T], /, *, error_message: str) -> T:
+    """Await `coro`, translating any failure into a `MatrixApiError`.
+
+    matrix-nio's `AsyncClient` methods don't raise on API-level errors; they
+    return an `ErrorResponse` instead of raising. This wraps a single call so
+    both transport-level exceptions and nio `ErrorResponse` results become a
+    `MatrixApiError` carrying `error_message`. When the `ErrorResponse` is a
+    rate limit with a `retry_after_ms`, that value is carried through
+    unchanged on `MatrixApiError.retry_after_ms`.
+
+    ## Example
+
+    ```python
+    response = await matrix_call(
+        self.client.room_kick(room_id=self.room_id, user_id=user_id),
+        error_message="Failed to kick user",
+    )
+    ```
+    """
+    try:
+        response = await coro
+    except Exception as e:
+        raise MatrixApiError(f"{error_message}: {e}") from e
+
+    if isinstance(response, ErrorResponse):
+        raise MatrixApiError(
+            f"{error_message}: {response}", retry_after_ms=response.retry_after_ms
+        )
+
+    return response
+
+
+async def with_retry(
+    func: Callable[[], Awaitable[R]],
+    /,
+    *,
+    retries: int = 3,
+    base_delay: float = 1.0,
+) -> R:
+    """Call `func`, retrying on `MatrixApiError` with backoff.
+
+    Retries up to `retries` times after the initial attempt (so up to
+    `retries + 1` total calls). If the raised `MatrixApiError` carries a
+    `retry_after_ms` (from the Matrix server), that wait is used exactly
+    (converted to seconds); otherwise falls back to exponential delay
+    (`base_delay * 2 ** attempt`). Only `MatrixApiError` triggers a retry;
+    any other exception propagates.
+
+    ## Example
+
+    ```python
+    message = await with_retry(lambda: room.send(content, notice=notice))
+    ```
+    """
+    for attempt in range(retries + 1):
+        try:
+            return await func()
+        except MatrixApiError as e:
+            if attempt == retries:
+                raise
+
+            delay = base_delay * 2**attempt
+            if e.retry_after_ms is not None:
+                delay = e.retry_after_ms / 1000
+
+            await asyncio.sleep(delay)
+
+    raise AssertionError("unreachable")
+
+
+async def bounded_gather(
+    coros: Iterable[Awaitable[R]],
+    /,
+    *,
+    max_concurrent: int = 8,
+) -> list[R]:
+    """Run `coros` concurrently, limited to `max_concurrent` at a time.
+
+    Behaves like `asyncio.gather`, but never runs more than `max_concurrent`
+    awaitables at once. Useful for fanning out many API calls (e.g.
+    broadcasting to many rooms) without overwhelming a shared rate limit by
+    firing every request at once. The first exception raised by any
+    coroutine cancels the rest and propagates immediately, same as
+    `asyncio.gather`'s default behavior.
+
+    ## Example
+
+    ```python
+    messages = await bounded_gather(
+        (room.send(content) for room in rooms), max_concurrent=8
+    )
+    ```
+    """
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def _run(coro: Awaitable[R]) -> R:
+        async with semaphore:
+            return await coro
+
+    return await asyncio.gather(*[_run(coro) for coro in coros])