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

matelab/models.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class Token:
+    """Immutable Provider token whose secret value is omitted from representations."""
+
+    value: str = field(repr=False)
+    expires_at_ms: int
+
+
+@dataclass(frozen=True, slots=True)
+class Identity:
+    """Immutable identity associated with a validated Matelab Session."""
+
+    userid: int
+    username: str | None
+    email: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Session:
+    """Immutable snapshot of one client's current process-local Matelab authentication state."""
+
+    access: Token
+    refresh: Token
+    identity: Identity | None = None

matelab/notebooks.py

@@ -0,0 +1,467 @@
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from pydantic import ValidationError
+
+from matelab._generated.models import AddNotebookShareRequest as WireAddNotebookShareRequest
+from matelab._generated.models import BasicSuccessResponse as WireBasicSuccessResponse
+from matelab._generated.models import DeleteNotebookShareRequest as WireDeleteNotebookShareRequest
+from matelab._generated.models import ElnNotebook
+from matelab._generated.models import ListNotebookSharesParametersQuery as WireNotebookSharesQuery
+from matelab._generated.models import NotebookListResponse as WireNotebookListResponse
+from matelab._generated.models import NotebookShareListResponse as WireNotebookShareListResponse
+from matelab._generated.models import SaveNotebookRequest as WireSaveNotebookRequest
+from matelab._generated.models import UpdateNotebookSharePermissionsRequest as WireUpdateNotebookSharePermissionsRequest
+from matelab._transport import Encoding, Operation, SessionTransport, multipart_fields
+from matelab.errors import MatelabError, MatelabProtocolError, MatelabUsageError, MatelabVerificationError
+from matelab.groups import GroupRef
+from matelab.users import UserRef
+
+_LIST_NOTEBOOKS = Operation(
+    method="GET",
+    path="/eln_api/elns",
+    encoding=Encoding.NONE,
+    response_model=WireNotebookListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SAVE_NOTEBOOK = Operation(
+    method="POST",
+    path="/eln/edit",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_LIST_SHARES = Operation(
+    method="GET",
+    path="/eln/share_list",
+    encoding=Encoding.QUERY,
+    response_model=WireNotebookShareListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_ADD_SHARE = Operation(
+    method="POST",
+    path="/eln/share_add",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_UPDATE_SHARE = Operation(
+    method="POST",
+    path="/eln/share_edit",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_SHARE = Operation(
+    method="POST",
+    path="/eln/sharedel",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookRef:
+    """Identity and exact Provider selector for an owned or shared notebook."""
+
+    notebook_id: int
+    title: str | None
+    owner_userid: int
+    scope: Literal["owned", "shared"]
+
+
+@dataclass(frozen=True, slots=True)
+class PublicNotebookRef:
+    """Identity and title selector for a public-catalog notebook."""
+
+    public_notebook_id: int
+    title: str
+    owner_userid: int
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookListField:
+    uid: object
+    path: tuple[object, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookMetadata:
+    """Complete metadata replacement accepted by the legacy save operation."""
+
+    title: str
+    summary: str | None = None
+    notebook_types: tuple[object, ...] = ()
+    display_fields: tuple[NotebookListField, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookSummary:
+    ref: NotebookRef
+    summary: str | None
+    record_count: int
+    created_at: str | None
+    owner_name: str | None
+    group_name: str | None
+    notebook_types: tuple[object, ...]
+    display_enabled: bool
+    display_fields: tuple[NotebookListField, ...] | None
+    display_configuration_valid: bool
+
+
+@dataclass(frozen=True, slots=True)
+class PublicNotebookSummary:
+    ref: PublicNotebookRef
+    summary: str
+    record_count: int
+    created_at: str
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookCollection:
+    owned: tuple[NotebookSummary, ...]
+    shared: tuple[NotebookSummary, ...]
+    public: tuple[PublicNotebookSummary, ...]
+
+    @property
+    def all(self) -> tuple[NotebookSummary | PublicNotebookSummary, ...]:
+        return (*self.owned, *self.shared, *self.public)
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookCreateResult:
+    requested: NotebookMetadata
+    provider_acknowledged: Literal[True] = True
+    notebook: None = None
+    identity_status: Literal["provider_did_not_return_identity"] = "provider_did_not_return_identity"
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookUpdateResult:
+    notebook: NotebookRef
+    requested: NotebookMetadata
+    observed: NotebookSummary | None
+    confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"]
+    provider_acknowledged: Literal[True] = True
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookSharePermissionGrant:
+    """Replacement flags; read access remains implicit and cannot be revoked here."""
+
+    write: bool = False
+    create: bool = False
+    delete: bool = False
+    sign: bool = False
+    manage_subtypes: bool = False
+    read_audit_log: bool = False
+    manage_shares: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookShareRef:
+    notebook: NotebookRef
+    share_row_id: int
+    recipient: UserRef
+    belongs_to_caller: bool
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookShare:
+    ref: NotebookShareRef
+    recipient_name: str | None
+    recipient_email: str | None
+    stored_permission_mask: int
+    effective_read_access: Literal[True] = True
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookShares:
+    notebook: NotebookRef
+    shares: tuple[NotebookShare, ...]
+    caller_is_owner: bool
+    caller_effective_permission_mask: int
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookShareResult:
+    notebook: NotebookRef
+    requested: tuple[UserRef, ...]
+    visible_after_write: tuple[NotebookShare, ...]
+    not_observed_after_write: tuple[UserRef, ...]
+    observation: Literal["all_visible", "partially_visible", "none_visible"]
+    provider_acknowledged: Literal[True] = True
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookShareUpdateResult:
+    ref: NotebookShareRef
+    requested: NotebookSharePermissionGrant
+    observed: NotebookShare | None
+    observation: Literal["relation_observed", "relation_not_observed"]
+    provider_acknowledged: Literal[True] = True
+
+
+@dataclass(frozen=True, slots=True)
+class NotebookUnshareResult:
+    ref: NotebookShareRef
+    absence_confirmed: bool | None
+    verification: Literal["confirmed_absent", "still_visible", "not_attempted_after_leaving"]
+    provider_acknowledged: Literal[True] = True
+
+
+class Notebooks:
+    """Notebook-oriented Matelab operations."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def list(self) -> NotebookCollection:
+        response = await self._transport.request(_LIST_NOTEBOOKS)
+        return NotebookCollection(
+            owned=tuple(self._owned_or_shared(item, scope="owned") for item in response.my),
+            shared=tuple(self._owned_or_shared(item, scope="shared") for item in response.share),
+            public=tuple(
+                PublicNotebookSummary(
+                    ref=PublicNotebookRef(public_notebook_id=item.id, title=item.showtext, owner_userid=item.userid),
+                    summary=item.comm,
+                    record_count=item.num,
+                    created_at=item.datetime_create,
+                )
+                for item in response.public
+            ),
+        )
+
+    async def create(self, metadata: NotebookMetadata, *, group: GroupRef | None = None) -> NotebookCreateResult:
+        request = self._save_request(metadata, notebook_id=0, group_id=group.group_id if group is not None else 0)
+        _ = await self._transport.request(_SAVE_NOTEBOOK, payload=request.model_dump(mode="json", exclude_unset=True))
+        return NotebookCreateResult(requested=metadata)
+
+    async def update(self, notebook: NotebookRef, metadata: NotebookMetadata) -> NotebookUpdateResult:
+        if notebook.scope != "owned":
+            raise MatelabUsageError("Notebook metadata can only be updated through an owned NotebookRef.")
+        request = self._save_request(metadata, notebook_id=notebook.notebook_id)
+        _ = await self._transport.request(_SAVE_NOTEBOOK, payload=request.model_dump(mode="json", exclude_unset=True))
+        notebooks = await self._verified_notebook_list("notebook update")
+        observed = next((item for item in notebooks.owned if item.ref.notebook_id == notebook.notebook_id), None)
+        if observed is None:
+            confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"] = "not_observed"
+        elif self._metadata_matches(observed, metadata):
+            confirmation = "observed_matching"
+        else:
+            confirmation = "observed_mismatch"
+        return NotebookUpdateResult(notebook=notebook, requested=metadata, observed=observed, confirmation=confirmation)
+
+    async def shares(self, notebook: NotebookRef) -> NotebookShares:
+        try:
+            request = WireNotebookSharesQuery(id=notebook.notebook_id)
+        except ValidationError:
+            raise MatelabUsageError("Notebook identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_SHARES, payload=request.model_dump(mode="json"))
+        return NotebookShares(
+            notebook=notebook,
+            shares=tuple(
+                NotebookShare(
+                    ref=NotebookShareRef(
+                        notebook=notebook,
+                        share_row_id=item.id,
+                        recipient=UserRef(userid=item.userid),
+                        belongs_to_caller=item.self,
+                    ),
+                    recipient_name=item.username,
+                    recipient_email=item.email,
+                    stored_permission_mask=item.power,
+                )
+                for item in response.list_
+            ),
+            caller_is_owner=response.owner,
+            caller_effective_permission_mask=response.power,
+        )
+
+    async def share(self, notebook: NotebookRef, recipients: Sequence[UserRef]) -> NotebookShareResult:
+        requested = tuple(recipients)
+        userids = tuple(recipient.userid for recipient in requested)
+        if (
+            not requested
+            or any(type(userid) is not int or userid < 1 for userid in userids)
+            or len(userids) != len(set(userids))
+        ):
+            raise MatelabUsageError("Notebook share recipients must be a non-empty set of distinct users.")
+        try:
+            request = WireAddNotebookShareRequest(
+                id=notebook.notebook_id, users=json.dumps(userids, ensure_ascii=False, separators=(",", ":"))
+            )
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Notebook share targets do not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_ADD_SHARE, files=multipart_fields(request.model_dump(mode="json")))
+        after = await self._verified_shares(notebook, "notebook share")
+        by_userid = {item.ref.recipient.userid: item for item in after.shares}
+        visible = tuple(by_userid[userid] for userid in userids if userid in by_userid)
+        not_observed = tuple(recipient for recipient in requested if recipient.userid not in by_userid)
+        observation: Literal["all_visible", "partially_visible", "none_visible"]
+        if len(visible) == len(requested):
+            observation = "all_visible"
+        elif visible:
+            observation = "partially_visible"
+        else:
+            observation = "none_visible"
+        return NotebookShareResult(
+            notebook=notebook,
+            requested=requested,
+            visible_after_write=visible,
+            not_observed_after_write=not_observed,
+            observation=observation,
+        )
+
+    async def update_share(
+        self, ref: NotebookShareRef, permissions: NotebookSharePermissionGrant
+    ) -> NotebookShareUpdateResult:
+        try:
+            request = WireUpdateNotebookSharePermissionsRequest.model_validate(
+                {
+                    "id": ref.share_row_id,
+                    "write": int(permissions.write),
+                    "create": int(permissions.create),
+                    "delete": int(permissions.delete),
+                    "sign": int(permissions.sign),
+                    "subtype": int(permissions.manage_subtypes),
+                    "log": int(permissions.read_audit_log),
+                    "user": int(permissions.manage_shares),
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Notebook share permissions do not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_UPDATE_SHARE, files=multipart_fields(request.model_dump(mode="json")))
+        after = await self._verified_shares(ref.notebook, "notebook share-permission update")
+        observed = next((item for item in after.shares if item.ref.share_row_id == ref.share_row_id), None)
+        if observed is not None and observed.ref.recipient != ref.recipient:
+            raise MatelabProtocolError("Matelab returned a different recipient for the notebook share row.")
+        return NotebookShareUpdateResult(
+            ref=ref,
+            requested=permissions,
+            observed=observed,
+            observation="relation_observed" if observed is not None else "relation_not_observed",
+        )
+
+    async def unshare(self, ref: NotebookShareRef) -> NotebookUnshareResult:
+        try:
+            request = WireDeleteNotebookShareRequest(id=ref.share_row_id)
+        except ValidationError:
+            raise MatelabUsageError("Notebook share identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_SHARE, files=multipart_fields(request.model_dump(mode="json")))
+        if ref.belongs_to_caller:
+            return NotebookUnshareResult(ref=ref, absence_confirmed=None, verification="not_attempted_after_leaving")
+        after = await self._verified_shares(ref.notebook, "notebook unshare")
+        still_visible = any(item.ref.share_row_id == ref.share_row_id for item in after.shares)
+        return NotebookUnshareResult(
+            ref=ref,
+            absence_confirmed=not still_visible,
+            verification="still_visible" if still_visible else "confirmed_absent",
+        )
+
+    @staticmethod
+    def _save_request(
+        metadata: NotebookMetadata, *, notebook_id: int, group_id: int | None = None
+    ) -> WireSaveNotebookRequest:
+        try:
+            if any(not 1 <= len(field.path) <= 4 for field in metadata.display_fields or ()):
+                raise ValueError
+            encoded_types = json.dumps(metadata.notebook_types, ensure_ascii=False, separators=(",", ":"))
+            encoded_fields = (
+                json.dumps(
+                    [{"uid": field.uid, "path": list(field.path)} for field in metadata.display_fields],
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                )
+                if metadata.display_fields is not None
+                else None
+            )
+            payload: dict[str, object] = {
+                "id": notebook_id,
+                "showtext": metadata.title,
+                "comm": metadata.summary,
+                "display": int(metadata.display_fields is not None),
+                "types": encoded_types,
+                "requests": encoded_fields,
+            }
+            if group_id is not None:
+                payload["group_id"] = group_id
+            return WireSaveNotebookRequest.model_validate(payload)
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Notebook metadata does not satisfy the Integration Contract.") from None
+
+    async def _verified_notebook_list(self, action: str) -> NotebookCollection:
+        try:
+            return await self.list()
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_shares(self, notebook: NotebookRef, action: str) -> NotebookShares:
+        try:
+            return await self.shares(notebook)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    @staticmethod
+    def _metadata_matches(observed: NotebookSummary, requested: NotebookMetadata) -> bool:
+        summary_matches = (observed.summary or "") == (requested.summary or "")
+        fields_match = not observed.display_enabled or (
+            observed.display_configuration_valid and observed.display_fields == (requested.display_fields or ())
+        )
+        return (
+            observed.ref.title == requested.title
+            and summary_matches
+            and observed.notebook_types == requested.notebook_types
+            and observed.display_enabled == (requested.display_fields is not None)
+            and fields_match
+        )
+
+    @staticmethod
+    def _owned_or_shared(item: ElnNotebook, *, scope: Literal["owned", "shared"]) -> NotebookSummary:
+        display_fields, configuration_valid = Notebooks._parse_display_fields(item.requests)
+        return NotebookSummary(
+            ref=NotebookRef(notebook_id=item.id, title=item.showtext, owner_userid=item.userid, scope=scope),
+            summary=item.comm,
+            record_count=item.num_total,
+            created_at=item.datetime_create,
+            owner_name=item.username or None,
+            group_name=item.group_name,
+            notebook_types=tuple(cast(list[object], item.types)),
+            display_enabled=bool(item.display.value),
+            display_fields=display_fields,
+            display_configuration_valid=configuration_valid,
+        )
+
+    @staticmethod
+    def _parse_display_fields(raw: str | None) -> tuple[tuple[NotebookListField, ...] | None, bool]:
+        if raw is None or raw == "":
+            return (), True
+        try:
+            decoded = cast(object, json.loads(raw))
+        except (TypeError, ValueError):
+            return None, False
+        if not isinstance(decoded, list):
+            return None, False
+        fields: list[NotebookListField] = []
+        for value in cast(list[object], decoded):
+            if not isinstance(value, Mapping):
+                return None, False
+            mapping = cast(Mapping[object, object], value)
+            path = mapping.get("path")
+            if "uid" not in mapping or not isinstance(path, list):
+                return None, False
+            path_values = cast(list[object], path)
+            if not 1 <= len(path_values) <= 4:
+                return None, False
+            fields.append(NotebookListField(uid=mapping["uid"], path=tuple(path_values)))
+        return tuple(fields), True

matelab/py.typed

@@ -0,0 +1 @@
+