matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/errors.py

@@ -0,0 +1,38 @@
+from collections.abc import Mapping
+
+
+class MatelabError(Exception):
+    """Base class for stable Matelab SDK errors."""
+
+    def __init__(self, message: str, *, code: int | None = None, payload: Mapping[str, object] | None = None) -> None:
+        super().__init__(message)
+        self.code: int | None = code
+        self.payload: Mapping[str, object] | None = payload
+
+
+class MatelabProviderError(MatelabError):
+    """The Provider returned a business error envelope."""
+
+
+class MatelabAuthenticationError(MatelabError):
+    """The Matelab session cannot authenticate Provider requests."""
+
+
+class MatelabUsageError(MatelabError):
+    """The requested SDK operation cannot be represented safely."""
+
+
+class MatelabTransportError(MatelabError):
+    """The HTTP exchange with the Provider failed."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code: int | None = status_code
+
+
+class MatelabProtocolError(MatelabError):
+    """The Provider response did not satisfy the expected wire shape."""
+
+
+class MatelabVerificationError(MatelabError):
+    """A mutation was acknowledged, but its subsequent readback failed."""

matelab/groups.py

@@ -0,0 +1,78 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from matelab._generated.models import ElnGroupsResponse as WireElnGroupsResponse
+from matelab._transport import Encoding, Operation, SessionTransport
+from matelab.errors import MatelabProtocolError
+from matelab.users import UserRef
+
+_LIST_GROUPS = Operation(
+    method="GET",
+    path="/actions/eln_groups",
+    encoding=Encoding.NONE,
+    response_model=WireElnGroupsResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class GroupRef:
+    group_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class GroupSummary:
+    ref: GroupRef
+    name: str | None
+    server: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class GroupMember:
+    """A member row; ref is absent when the Provider LEFT JOIN is dangling."""
+
+    ref: UserRef | None
+    display_name: str | None
+    email: str | None
+    iop_userid: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class GroupCollection:
+    """Groups plus members for only the Provider-selected group."""
+
+    groups: tuple[GroupSummary, ...]
+    members_for: GroupRef | None
+    members: tuple[GroupMember, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+class Groups:
+    """Current-user ELN group discovery."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def list(self) -> GroupCollection:
+        response = await self._transport.request(_LIST_GROUPS)
+        groups = tuple(
+            GroupSummary(ref=GroupRef(group_id=group.id), name=group.showtext, server=group.server)
+            for group in response.groups
+        )
+        members_for = next((group.ref for group in groups if group.ref.group_id == response.group_id), None)
+        if (response.group_id == 0) != (not groups) or (response.group_id > 0 and members_for is None):
+            raise MatelabProtocolError("Matelab returned an inconsistent group member selector.")
+        return GroupCollection(
+            groups=groups,
+            members_for=members_for,
+            members=tuple(
+                GroupMember(
+                    ref=UserRef(userid=user.id) if user.id is not None else None,
+                    display_name=user.username,
+                    email=user.email,
+                    iop_userid=user.iop_id,
+                )
+                for user in response.users
+            ),
+        )