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

matelab/__init__.py

@@ -8,16 +8,10 @@ from matelab.cloud_drive import (
     CloudDriveRootPermissions,
     CloudDriveRootRef,
     CloudFile,
-    CloudFileBindResult,
-    CloudFileMoveResult,
     CloudFilePage,
-    CloudFilePermanentDeleteResult,
     CloudFileRef,
-    CloudFileUpdateResult,
     CloudFolder,
-    CloudFolderDeleteResult,
     CloudFolderMetadata,
-    CloudFolderMoveResult,
     CloudFolderRef,
     CloudFolderSaveResult,
     CloudFolderTree,
@@ -38,11 +32,8 @@ from matelab.literature import (
     ExtractedLiteratureMetadata,
     LiteratureCitation,
     LiteratureComment,
-    LiteratureCommentDeleteResult,
     LiteratureCommentDraft,
     LiteratureCommentRef,
-    LiteratureCommentSaveResult,
-    LiteratureCreateResult,
     LiteratureCreationSchema,
     LiteratureDetail,
     LiteratureField,
@@ -56,13 +47,8 @@ from matelab.literature import (
     LiteratureNestedField,
     LiteraturePage,
     LiteraturePdf,
-    LiteraturePdfDeleteResult,
-    LiteraturePdfReplaceResult,
-    LiteraturePermanentDeleteResult,
-    LiteratureShareResult,
     LiteratureSource,
     LiteratureStoredMetadata,
-    LiteratureUpdateResult,
     PendingLiteratureShare,
     PendingLiteratureShareComment,
     PendingLiteratureShareRef,
@@ -75,24 +61,18 @@ from matelab.literature import (
 from matelab.models import Identity, Session, Token
 from matelab.notebooks import (
     NotebookCollection,
-    NotebookCreateResult,
     NotebookListField,
     NotebookMetadata,
     NotebookRef,
     NotebookShare,
     NotebookSharePermissionGrant,
     NotebookShareRef,
-    NotebookShareResult,
     NotebookShares,
-    NotebookShareUpdateResult,
     NotebookSummary,
-    NotebookUnshareResult,
-    NotebookUpdateResult,
     PublicNotebookRef,
     PublicNotebookSummary,
 )
 from matelab.records import (
-    BlankRecordCreateResult,
     DeletedRecordPage,
     DeletedRecordRef,
     DeletedRecordSummary,
@@ -106,11 +86,9 @@ from matelab.records import (
     RecordCollection,
     RecordComment,
     RecordCommentAttachmentRef,
-    RecordCommentDeleteResult,
     RecordCommentDraft,
     RecordCommentRef,
     RecordComments,
-    RecordCommentSaveResult,
     RecordCopyResult,
     RecordDeleteResult,
     RecordExport,
@@ -118,6 +96,7 @@ from matelab.records import (
     RecordFilesAttachmentAppend,
     RecordFilesAttachmentRemoval,
     RecordFilesAttachmentReplacement,
+    RecordFormAttachmentFieldAddition,
     RecordFormAttachmentRemoval,
     RecordImportItem,
     RecordImportResult,
@@ -131,8 +110,6 @@ from matelab.records import (
     RecordPatch,
     RecordRef,
     RecordRelation,
-    RecordRelationAddResult,
-    RecordRelationDeleteResult,
     RecordRelationRef,
     RecordRelations,
     RecordRestoreResult,
@@ -150,6 +127,7 @@ from matelab.records import (
     RecordVersionRef,
     RecordVersionSummary,
     RelatedRecordIdentity,
+    StagedNotebookAttachment,
     StagedRecordAttachment,
     StagedRecordCommentAttachment,
 )
@@ -157,30 +135,20 @@ from matelab.streaming import ByteRange, DownloadStream
 from matelab.templates import (
     TemplateCollection,
     TemplateContent,
-    TemplateContentSaveResult,
-    TemplateCopyResult,
-    TemplateGroupAddResult,
-    TemplateGroupRemoveResult,
-    TemplateIntroUpdateResult,
     TemplateLibraryEntryRef,
     TemplateLibraryRelationKind,
-    TemplateLibraryRemovalResult,
-    TemplateMarketAcquireResult,
     TemplateMarketEntry,
     TemplateMarketPage,
-    TemplateMarketSubmissionResult,
     TemplateMetadata,
     TemplateMetadataResult,
     TemplateModule,
     TemplateRef,
-    TemplateShareResult,
     TemplateSource,
     TemplateSummary,
 )
 from matelab.uploads import (
     StagedFile,
     StagedFileFragment,
-    StagedUploadAbortResult,
     StagedUploadSession,
     UploadBindingRef,
 )
@@ -188,7 +156,6 @@ from matelab.users import UserRef, UserSearchResult, UserSearchScope, UserSummar
 
 __all__ = [
     "AsyncMatelab",
-    "BlankRecordCreateResult",
     "ByteRange",
     "CloudDriveListing",
     "CloudDriveLocation",
@@ -198,16 +165,10 @@ __all__ = [
     "CloudDriveRootPermissions",
     "CloudDriveRootRef",
     "CloudFile",
-    "CloudFileBindResult",
-    "CloudFileMoveResult",
     "CloudFilePage",
-    "CloudFilePermanentDeleteResult",
     "CloudFileRef",
-    "CloudFileUpdateResult",
     "CloudFolder",
-    "CloudFolderDeleteResult",
     "CloudFolderMetadata",
-    "CloudFolderMoveResult",
     "CloudFolderRef",
     "CloudFolderSaveResult",
     "CloudFolderTree",
@@ -226,11 +187,8 @@ __all__ = [
     "Identity",
     "LiteratureCitation",
     "LiteratureComment",
-    "LiteratureCommentDeleteResult",
     "LiteratureCommentDraft",
     "LiteratureCommentRef",
-    "LiteratureCommentSaveResult",
-    "LiteratureCreateResult",
     "LiteratureCreationSchema",
     "LiteratureDetail",
     "LiteratureField",
@@ -244,13 +202,8 @@ __all__ = [
     "LiteratureNestedField",
     "LiteraturePage",
     "LiteraturePdf",
-    "LiteraturePdfDeleteResult",
-    "LiteraturePdfReplaceResult",
-    "LiteraturePermanentDeleteResult",
-    "LiteratureShareResult",
     "LiteratureSource",
     "LiteratureStoredMetadata",
-    "LiteratureUpdateResult",
     "MatelabAuthenticationError",
     "MatelabError",
     "MatelabProtocolError",
@@ -259,19 +212,14 @@ __all__ = [
     "MatelabUsageError",
     "MatelabVerificationError",
     "NotebookCollection",
-    "NotebookCreateResult",
     "NotebookListField",
     "NotebookMetadata",
     "NotebookRef",
     "NotebookShare",
     "NotebookSharePermissionGrant",
     "NotebookShareRef",
-    "NotebookShareResult",
-    "NotebookShareUpdateResult",
     "NotebookShares",
     "NotebookSummary",
-    "NotebookUnshareResult",
-    "NotebookUpdateResult",
     "PendingLiteratureShare",
     "PendingLiteratureShareComment",
     "PendingLiteratureShareRef",
@@ -288,10 +236,8 @@ __all__ = [
     "RecordCollection",
     "RecordComment",
     "RecordCommentAttachmentRef",
-    "RecordCommentDeleteResult",
     "RecordCommentDraft",
     "RecordCommentRef",
-    "RecordCommentSaveResult",
     "RecordComments",
     "RecordCopyResult",
     "RecordDeleteResult",
@@ -300,6 +246,7 @@ __all__ = [
     "RecordFilesAttachmentAppend",
     "RecordFilesAttachmentRemoval",
     "RecordFilesAttachmentReplacement",
+    "RecordFormAttachmentFieldAddition",
     "RecordFormAttachmentRemoval",
     "RecordImportItem",
     "RecordImportResult",
@@ -313,8 +260,6 @@ __all__ = [
     "RecordPatch",
     "RecordRef",
     "RecordRelation",
-    "RecordRelationAddResult",
-    "RecordRelationDeleteResult",
     "RecordRelationRef",
     "RecordRelations",
     "RecordRestoreResult",
@@ -337,30 +282,21 @@ __all__ = [
     "SharedLiteratureLibraryRef",
     "StagedFile",
     "StagedFileFragment",
+    "StagedNotebookAttachment",
     "StagedPdfMetadataSource",
     "StagedRecordAttachment",
     "StagedRecordCommentAttachment",
-    "StagedUploadAbortResult",
     "StagedUploadSession",
     "TemplateCollection",
     "TemplateContent",
-    "TemplateContentSaveResult",
-    "TemplateCopyResult",
-    "TemplateGroupAddResult",
-    "TemplateGroupRemoveResult",
-    "TemplateIntroUpdateResult",
     "TemplateLibraryEntryRef",
     "TemplateLibraryRelationKind",
-    "TemplateLibraryRemovalResult",
-    "TemplateMarketAcquireResult",
     "TemplateMarketEntry",
     "TemplateMarketPage",
-    "TemplateMarketSubmissionResult",
     "TemplateMetadata",
     "TemplateMetadataResult",
     "TemplateModule",
     "TemplateRef",
-    "TemplateShareResult",
     "TemplateSource",
     "TemplateSummary",
     "Token",

matelab/_generated/models.py

@@ -7,7 +7,7 @@ from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, RootModel, SecretStr
 
-OPENAPI_INFO_VERSION = "0.1.0"
+OPENAPI_INFO_VERSION = "0.1.1"
 
 
 class ResponseEnvelope(BaseModel):
@@ -108,9 +108,11 @@ class CloudDriveFile(BaseModel):
     id: Annotated[int, Field(ge=1)]
     filename: Annotated[str, Field(max_length=255, min_length=1)]
     hash: Sha256
-    size: Annotated[str, Field(pattern="^[0-9]+$")]
+    size: Annotated[int, Field(ge=0)]
     """
-    Unsigned BIGINT serialized as a decimal string by this query.
+    File size in bytes. The Provider fetches the unsigned BIGINT with
+    PDO::ATTR_STRINGIFY_FETCHES disabled and returns a JSON integer.
+
     """
     userid: Annotated[int, Field(ge=1)]
     date_time: Annotated[str | None, Field(pattern="^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$")]
@@ -263,19 +265,31 @@ class UploadAttachmentRequest(BaseModel):
     )
     eln: Annotated[str, Field(min_length=1)]
     """
-    Notebook title used to select its data server.
+    Notebook title used to check write permission and select its data
+    server. The value is not persisted on the staging row.
+
     """
     user: Annotated[int | None, Field(ge=1)] = None
     """
-    Optional notebook owner identifier for a non-owned notebook.
+    Optional notebook owner identifier for a non-owned notebook. It
+    selects the notebook but never replaces the authenticated uploader
+    as the staging owner.
+
     """
     uid: Annotated[str, Field(max_length=45, min_length=1)]
     """
-    Record wire UID and upload-event identifier.
+    Caller-generated upload-event key stored in `upload_temp.data`.
+    It is independent of, and need not equal, the UID of a record later
+    created or updated with this staged file.
+
     """
     name: Annotated[str, Field(max_length=45)] = ""
     """
-    Missing or empty falls back to uid as the unique temporary upload name.
+    Caller-generated staging name stored in `upload_temp.unique_str`.
+    Missing or empty falls back to `uid`. On success, use the response
+    `name` once as `#file{name}` in the same user's same-notebook
+    import or update workflow.
+
     """
     hash: Sha256
     last: Literal[1] = 1
@@ -303,6 +317,9 @@ class UploadAttachmentResponse(BaseModel):
     Provider-built legacy query string for the temporary file.
     """
     name: Annotated[str, Field(min_length=1)]
+    """
+    Resolved one-shot staging name used by `#file{name}`.
+    """
     filename: Annotated[str, Field(min_length=1)]
     size: Annotated[int, Field(ge=0)]
     hash: Sha256

matelab/_transport.py

@@ -7,10 +7,10 @@ from dataclasses import dataclass
 from enum import StrEnum
 from typing import IO, Generic, TypeAlias, TypeVar, cast
 
-import httpx
+import httpx2
 from pydantic import BaseModel, ValidationError
 
-from matelab._generated.models import ErrorResponse, TokenRefreshRequest, TokenRefreshResponse
+from matelab._generated import models as wire_models
 from matelab.errors import (
     MatelabAuthenticationError,
     MatelabProtocolError,
@@ -152,7 +152,7 @@ _REFRESH_TOKENS = Operation(
     method="POST",
     path="/tokens/tokens_refresh",
     encoding=Encoding.FORM,
-    response_model=TokenRefreshResponse,
+    response_model=wire_models.TokenRefreshResponse,
     success_codes=frozenset({0}),
     authenticated=False,
     authentication_errors=True,
@@ -160,8 +160,8 @@ _REFRESH_TOKENS = Operation(
 
 
 class SessionTransport:
-    def __init__(self, http_client: httpx.AsyncClient, *, session: Session | None = None) -> None:
-        self._http: httpx.AsyncClient = http_client
+    def __init__(self, http_client: httpx2.AsyncClient, *, session: Session | None = None) -> None:
+        self._http: httpx2.AsyncClient = http_client
         self.session: Session | None = session
         self._refresh_lock: asyncio.Lock = asyncio.Lock()
 
@@ -200,7 +200,7 @@ class SessionTransport:
             if session.refresh.expires_at_ms <= self._now_ms():
                 raise MatelabAuthenticationError("Matelab refresh token expired.")
             try:
-                request = TokenRefreshRequest(refresh_token=session.refresh.value)
+                request = wire_models.TokenRefreshRequest(refresh_token=session.refresh.value)
             except ValidationError:
                 raise MatelabAuthenticationError("The Matelab refresh token is invalid.") from None
             response = await self.request(_REFRESH_TOKENS, payload=request.model_dump(mode="json"))
@@ -307,7 +307,7 @@ class SessionTransport:
                 response = await self._http.request(operation.method, operation.path, headers=headers)
             else:
                 raise MatelabProtocolError(f"Unsupported request encoding: {operation.encoding}.")
-        except httpx.TransportError:
+        except httpx2.TransportError:
             raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
         if not response.is_success:
             raise MatelabTransportError(
@@ -329,7 +329,7 @@ class SessionTransport:
             )
         if code not in operation.success_codes:
             try:
-                error_response = ErrorResponse.model_validate(response_payload)
+                error_response = wire_models.ErrorResponse.model_validate(response_payload)
             except ValidationError:
                 raise MatelabProtocolError(
                     "Matelab error response does not match the Integration Contract.", payload=sanitized_payload
@@ -391,7 +391,7 @@ class SessionTransport:
         )
         try:
             response = await self._http.send(request, stream=True)
-        except httpx.TransportError:
+        except httpx2.TransportError:
             raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
 
         if response.status_code not in {200, 206}:
@@ -423,7 +423,7 @@ class SessionTransport:
                     "Matelab returned a JSON success envelope instead of attachment bytes.", payload=sanitized_payload
                 )
             try:
-                error_response = ErrorResponse.model_validate(response_payload)
+                error_response = wire_models.ErrorResponse.model_validate(response_payload)
             except ValidationError:
                 raise MatelabProtocolError(
                     "Matelab download error response does not match the Integration Contract.",
@@ -466,7 +466,7 @@ class SessionTransport:
         return DownloadStream(response, content_length=content_length)
 
     @staticmethod
-    def _parse_content_length(response: httpx.Response) -> int | None:
+    def _parse_content_length(response: httpx2.Response) -> int | None:
         value = SessionTransport._header(response, "Content-Length")
         if value is None:
             return None
@@ -477,5 +477,5 @@ class SessionTransport:
         return content_length if content_length >= 0 else None
 
     @staticmethod
-    def _header(response: httpx.Response, name: str) -> str | None:
+    def _header(response: httpx2.Response, name: str) -> str | None:
         return cast(str | None, response.headers.get(name))

matelab/client.py

@@ -1,18 +1,9 @@
 from typing import Self
 
-import httpx
+import httpx2
 from pydantic import SecretStr, ValidationError
 
-from matelab._generated.models import (
-    AppIdentityResponse,
-    AuthToken,
-    ChatSsoCodeExchangeRequest,
-    ChatSsoCodeExchangeResponse,
-    TokenLoginRequest,
-    TokenLoginResponse,
-    TokenRefreshRequest,
-    TokenRefreshResponse,
-)
+from matelab._generated import models as wire_models
 from matelab._transport import Encoding, Operation, SessionTransport, multipart_fields
 from matelab.cloud_drive import CloudDrive
 from matelab.errors import MatelabAuthenticationError, MatelabUsageError
@@ -31,7 +22,7 @@ _LOGIN = Operation(
     method="POST",
     path="/tokens/tokens",
     encoding=Encoding.MULTIPART,
-    response_model=TokenLoginResponse,
+    response_model=wire_models.TokenLoginResponse,
     success_codes=frozenset({0}),
     authenticated=False,
     authentication_errors=True,
@@ -40,7 +31,7 @@ _EXTERNAL_TOKEN_REFRESH = Operation(
     method="POST",
     path="/tokens/tokens_refresh",
     encoding=Encoding.FORM,
-    response_model=TokenRefreshResponse,
+    response_model=wire_models.TokenRefreshResponse,
     success_codes=frozenset({0}),
     authenticated=False,
     authentication_errors=True,
@@ -49,7 +40,7 @@ _APP_IDENTITY = Operation(
     method="GET",
     path="/actions/app",
     encoding=Encoding.NONE,
-    response_model=AppIdentityResponse,
+    response_model=wire_models.AppIdentityResponse,
     success_codes=frozenset({0}),
     authentication_errors=True,
     retry_on_access_expired=True,
@@ -58,7 +49,7 @@ _CHAT_SSO = Operation(
     method="POST",
     path="/unlogin_eln/code_check",
     encoding=Encoding.FORM,
-    response_model=ChatSsoCodeExchangeResponse,
+    response_model=wire_models.ChatSsoCodeExchangeResponse,
     success_codes=frozenset({0}),
     authenticated=False,
     authentication_errors=True,
@@ -69,7 +60,7 @@ class AsyncMatelab:
     """One-user async client that owns at most one process-local Matelab Session.
 
     Do not share one instance across logical user sessions. Separate instances may share an injected
-    ``httpx.AsyncClient`` while retaining independent Session state and refresh locks.
+    ``httpx2.AsyncClient`` while retaining independent Session state and refresh locks.
     """
 
     def __init__(
@@ -78,7 +69,7 @@ class AsyncMatelab:
         *,
         session: Session | None = None,
         timeout: float = 30.0,
-        http_client: httpx.AsyncClient | None = None,
+        http_client: httpx2.AsyncClient | None = None,
     ) -> None:
         """Create a client without performing network I/O.
 
@@ -86,10 +77,10 @@ class AsyncMatelab:
         the latest value exposed by :attr:`session`.
         """
         self._owns_http_client: bool = http_client is None
-        self._http: httpx.AsyncClient = (
+        self._http: httpx2.AsyncClient = (
             http_client
             if http_client is not None
-            else httpx.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout)
+            else httpx2.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout)
         )
         self._transport: SessionTransport = SessionTransport(self._http, session=session)
         self.cloud_drive: CloudDrive = CloudDrive(self._transport)
@@ -119,7 +110,7 @@ class AsyncMatelab:
     async def authenticate(self, username: str, password: str) -> Session:
         """Authenticate, install, and return the same latest instance Session."""
         try:
-            request = TokenLoginRequest(username=username, password=SecretStr(password))
+            request = wire_models.TokenLoginRequest(username=username, password=SecretStr(password))
         except ValidationError:
             raise MatelabUsageError("Matelab username or password does not satisfy the Integration Contract.") from None
         response = await self._transport.request(
@@ -134,7 +125,7 @@ class AsyncMatelab:
     async def exchange_chat_sso_code(self, *, code: str, key: str) -> Session:
         """Consume one Chat SSO code, install its Session, and return that same Session."""
         try:
-            request = ChatSsoCodeExchangeRequest(code=code, key=SecretStr(key))
+            request = wire_models.ChatSsoCodeExchangeRequest(code=code, key=SecretStr(key))
         except ValidationError:
             raise MatelabUsageError("Chat SSO credentials do not satisfy the Integration Contract.") from None
         response = await self._transport.request(
@@ -175,15 +166,17 @@ class AsyncMatelab:
         response = await self._transport.request(_APP_IDENTITY, bearer_token=access_token)
         return Identity(userid=response.user.userid, username=response.user.username, email=response.user.email)
 
-    async def _exchange_external_refresh_token(self, refresh_token: str) -> TokenRefreshResponse:
+    async def _exchange_external_refresh_token(self, refresh_token: str) -> wire_models.TokenRefreshResponse:
         try:
-            request = TokenRefreshRequest(refresh_token=refresh_token)
+            request = wire_models.TokenRefreshRequest(refresh_token=refresh_token)
         except ValidationError:
             raise MatelabAuthenticationError("The Matelab refresh token is invalid.") from None
         return await self._transport.request(_EXTERNAL_TOKEN_REFRESH, payload=request.model_dump(mode="json"))
 
     @staticmethod
-    def _session_from_wire(access: AuthToken, refresh: AuthToken, *, identity: Identity | None) -> Session:
+    def _session_from_wire(
+        access: wire_models.AuthToken, refresh: wire_models.AuthToken, *, identity: Identity | None
+    ) -> Session:
         return Session(
             access=Token(value=access.token, expires_at_ms=access.expiredAt),
             refresh=Token(value=refresh.token, expires_at_ms=refresh.expiredAt),