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

matelab/__init__.py

@@ -118,6 +118,7 @@ from matelab.records import (
     RecordFilesAttachmentAppend,
     RecordFilesAttachmentRemoval,
     RecordFilesAttachmentReplacement,
+    RecordFormAttachmentFieldAddition,
     RecordFormAttachmentRemoval,
     RecordImportItem,
     RecordImportResult,
@@ -150,6 +151,7 @@ from matelab.records import (
     RecordVersionRef,
     RecordVersionSummary,
     RelatedRecordIdentity,
+    StagedNotebookAttachment,
     StagedRecordAttachment,
     StagedRecordCommentAttachment,
 )
@@ -300,6 +302,7 @@ __all__ = [
     "RecordFilesAttachmentAppend",
     "RecordFilesAttachmentRemoval",
     "RecordFilesAttachmentReplacement",
+    "RecordFormAttachmentFieldAddition",
     "RecordFormAttachmentRemoval",
     "RecordImportItem",
     "RecordImportResult",
@@ -337,6 +340,7 @@ __all__ = [
     "SharedLiteratureLibraryRef",
     "StagedFile",
     "StagedFileFragment",
+    "StagedNotebookAttachment",
     "StagedPdfMetadataSource",
     "StagedRecordAttachment",
     "StagedRecordCommentAttachment",

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/records.py

@@ -229,6 +229,7 @@ _NATIVE_ATTACHMENT_PATTERN = re.compile(r"#(?:hash|file|base64)\{", re.IGNORECAS
 _COMMENT_TEMP_URL_PATTERN = re.compile(r"https?://[^\"']+/eln_url/eln_temp\?", re.IGNORECASE)
 _DATABASE_UPDATE_MESSAGES = frozenset({"数据库数据更新成功", "Database data update successful"})
 _COLLABORATION_UPDATE_MESSAGES = frozenset({"协同编辑数据更新完成", "Collaboration data update completed"})
+_StagedNotebookAttachmentIdentity = tuple[NotebookRef, int, str]
 
 
 @dataclass(frozen=True, slots=True)
@@ -329,7 +330,12 @@ class RecordImportResult:
     identity_count_status: Literal["one_id_per_item", "fewer_ids_than_items", "more_ids_than_items"] = "one_id_per_item"
     atomicity: Literal["provider_unspecified"] = "provider_unspecified"
     field_persistence: Literal["provider_not_verified"] = "provider_not_verified"
-    known_limitations: tuple[Literal["PVD-023"], Literal["PVD-024"]] = ("PVD-023", "PVD-024")
+    staged_attachment_finalization: Literal["not_requested", "provider_acknowledged_non_atomic"] = "not_requested"
+    known_limitations: tuple[Literal["PVD-023"], Literal["PVD-024"], Literal["PVD-040"]] = (
+        "PVD-023",
+        "PVD-024",
+        "PVD-040",
+    )
 
 
 @dataclass(frozen=True, slots=True)
@@ -532,6 +538,27 @@ class StagedRecordAttachment:
     binding_state: Literal["staged_not_bound"] = "staged_not_bound"
 
 
+@dataclass(frozen=True, slots=True)
+class StagedNotebookAttachment:
+    """A one-shot record attachment stage scoped to its uploader and notebook.
+
+    Pass this object directly in template-shaped ``RecordImportItem.data`` or
+    in ``RecordFormAttachmentFieldAddition``. A finalization request is
+    non-idempotent: after the SDK starts one import or update request, discard
+    this object regardless of the outcome.
+    """
+
+    notebook: NotebookRef
+    uploader: UserRef
+    temporary_file_id: int
+    binding: UploadBindingRef
+    filename: str
+    size: int
+    sha256: str = field(repr=False)
+    binding_state: Literal["staged_not_bound"] = "staged_not_bound"
+    finalize_semantics: Literal["single_import_or_update_attempt"] = "single_import_or_update_attempt"
+
+
 @dataclass(frozen=True, slots=True)
 class RecordValueUpdate:
     path: tuple[str | int, ...]
@@ -570,6 +597,15 @@ class RecordValueAddition:
     path: tuple[str, ...] | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class RecordFormAttachmentFieldAddition:
+    """Add one new file field and finalize one notebook-scoped staged attachment."""
+
+    module: str
+    name: str
+    attachment: StagedNotebookAttachment
+
+
 @dataclass(frozen=True, slots=True)
 class RecordFormAttachmentRemoval:
     attachment: RecordAttachmentRef
@@ -620,7 +656,8 @@ class RecordPatch:
     module_deletions: tuple[RecordModuleDeletion, ...] = ()
     value_additions: tuple[RecordValueAddition, ...] = ()
     attachment_changes: tuple[
-        RecordFormAttachmentRemoval
+        RecordFormAttachmentFieldAddition
+        | RecordFormAttachmentRemoval
         | RecordTableAttachmentReplacement
         | RecordFilesAttachmentAppend
         | RecordFilesAttachmentReplacement
@@ -695,6 +732,7 @@ class RecordUpdateResult:
         "client_read_precondition_not_provider_cas"
     )
     retryable: Literal[False] = False
+    staged_attachment_finalization: Literal["not_requested", "provider_acknowledged_non_atomic"] = "not_requested"
 
 
 @dataclass(frozen=True, slots=True)
@@ -1039,6 +1077,7 @@ class Records:
 
     def __init__(self, transport: SessionTransport) -> None:
         self._transport: SessionTransport = transport
+        self._staged_finalization_attempts: set[_StagedNotebookAttachmentIdentity] = set()
 
     async def list(
         self,
@@ -1121,6 +1160,7 @@ class Records:
             raise MatelabUsageError("Record import requires a valid template and one through one hundred items.")
         if len({item.record_uid for item in selected}) != len(selected):
             raise MatelabUsageError("Imported record UIDs must be distinct within the batch.")
+        staged_attachments: set[_StagedNotebookAttachmentIdentity] = set()
         payload: dict[str, object] = {
             "eln": notebook_title,
             "template": template.title,
@@ -1128,7 +1168,11 @@ class Records:
                 {
                     "uid": item.record_uid,
                     "title": item.title,
-                    "data": dict(item.data),
+                    "data": self._render_import_data(
+                        notebook,
+                        item.data,
+                        staged_attachments,
+                    ),
                     "keyword": item.keyword,
                     "path": list(item.path) if item.path is not None else None,
                 }
@@ -1137,11 +1181,16 @@ class Records:
             "user": notebook.owner_userid if notebook.scope == "shared" else None,
             "template_user": template.owner.userid if template.owner is not None else None,
         }
+        if staged_attachments and len(selected) != 1:
+            raise MatelabUsageError(
+                "A staged notebook attachment can be finalized only by a single-record import request."
+            )
         try:
             request = WireImportRecordsRequest.model_validate(payload)
             _ = json.dumps(request.model_dump(mode="json"), ensure_ascii=False)
         except (ValidationError, TypeError, ValueError):
             raise MatelabUsageError("Record import dataset does not satisfy the Integration Contract.") from None
+        self._mark_staged_finalization_attempts(staged_attachments)
         response = await self._transport.request(_IMPORT_RECORDS, payload=request.model_dump(mode="json"))
         if response.eln_id != notebook.notebook_id:
             raise MatelabProtocolError("Matelab returned a different target notebook for the record import.")
@@ -1151,6 +1200,9 @@ class Records:
             requested_record_uids=tuple(item.record_uid for item in selected),
             created_record_database_ids=tuple(item.root for item in response.id),
             provider_notebook_id=response.eln_id,
+            staged_attachment_finalization=(
+                "provider_acknowledged_non_atomic" if staged_attachments else "not_requested"
+            ),
             identity_count_status=(
                 "one_id_per_item"
                 if len(response.id) == len(selected)
@@ -1284,40 +1336,17 @@ class Records:
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedRecordAttachment:
-        notebook_title = self._notebook_title(source.notebook)
         selected_binding = binding or UploadBindingRef.new()
-        self._validate_upload_metadata(
-            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
-        )
-        try:
-            request = WireUploadAttachmentRequest.model_validate(
-                {
-                    "eln": notebook_title,
-                    "user": source.notebook.owner_userid if source.notebook.scope == "shared" else None,
-                    "uid": source.record.record_uid,
-                    "name": selected_binding.uid,
-                    "hash": sha256,
-                    "last": 1,
-                    "file": b"validation-placeholder",
-                }
-            )
-        except ValidationError:
-            raise MatelabUsageError("Record attachment upload does not satisfy the Integration Contract.") from None
-        response = await self._transport.request(
-            _UPLOAD_RECORD_ATTACHMENT,
-            payload=request.model_dump(mode="json", exclude={"file"}, exclude_none=True),
-            files={"file": (filename, content, content_type)},
+        response = await self._upload_record_attachment(
+            notebook=source.notebook,
+            upload_event_uid=source.record.record_uid,
+            binding=selected_binding,
+            filename=filename,
+            content=content,
+            size=size,
+            sha256=sha256,
+            content_type=content_type,
         )
-        if (
-            response.hash.root != sha256
-            or response.size != size
-            or response.filename != filename
-            or response.name != selected_binding.uid
-        ):
-            raise MatelabProtocolError(
-                "Matelab staged the record attachment but returned different upload metadata; "
-                + "the temporary upload may remain."
-            )
         return StagedRecordAttachment(
             source=source,
             temporary_file_id=response.id,
@@ -1327,6 +1356,46 @@ class Records:
             sha256=response.hash.root,
         )
 
+    async def stage_attachment(
+        self,
+        *,
+        notebook: NotebookRef,
+        filename: str,
+        content: IO[bytes] | bytes,
+        size: int,
+        sha256: str,
+        binding: UploadBindingRef | None = None,
+        content_type: str = "application/octet-stream",
+    ) -> StagedNotebookAttachment:
+        """Stage an attachment before its target record exists.
+
+        The returned handle is restricted to the authenticated uploader and
+        exact notebook selector. It can finalize one single-record import or
+        one safe form-file-field update.
+        """
+
+        uploader = self._authenticated_uploader()
+        selected_binding = binding or UploadBindingRef.new()
+        response = await self._upload_record_attachment(
+            notebook=notebook,
+            upload_event_uid=UploadBindingRef.new().uid,
+            binding=selected_binding,
+            filename=filename,
+            content=content,
+            size=size,
+            sha256=sha256,
+            content_type=content_type,
+        )
+        return StagedNotebookAttachment(
+            notebook=notebook,
+            uploader=uploader,
+            temporary_file_id=response.id,
+            binding=selected_binding,
+            filename=response.filename,
+            size=response.size,
+            sha256=response.hash.root,
+        )
+
     async def update(
         self,
         source: RecordLocator,
@@ -1343,7 +1412,7 @@ class Records:
                 raise MatelabUsageError(
                     "Record content changed before the update; this client-side precondition is not Provider CAS."
                 )
-        mutation_payload, operation_count = self._record_patch_payload(source, before, patch)
+        mutation_payload, operation_count, staged_attachments = self._record_patch_payload(source, before, patch)
         try:
             request = WireUpdateRecordRequest.model_validate(
                 {
@@ -1357,6 +1426,7 @@ class Records:
             _ = json.dumps(request.model_dump(mode="json", by_alias=True), ensure_ascii=False)
         except (ValidationError, TypeError, ValueError):
             raise MatelabUsageError("Record patch does not satisfy the Integration Contract.") from None
+        self._mark_staged_finalization_attempts(staged_attachments)
         response = await self._transport.request(
             _UPDATE_RECORD, payload=request.model_dump(mode="json", by_alias=True, exclude_none=True)
         )
@@ -1370,6 +1440,9 @@ class Records:
                 confirmation="pending_browser_save_not_read_back",
                 requested_operation_count=operation_count,
                 provider_message=response.msg,
+                staged_attachment_finalization=(
+                    "provider_acknowledged_non_atomic" if staged_attachments else "not_requested"
+                ),
             )
         after = await self._verified_read(source, "record update")
         return RecordUpdateResult(
@@ -1380,6 +1453,9 @@ class Records:
             confirmation="observed_changed" if after.content_sha256 != before.content_sha256 else "observed_unchanged",
             requested_operation_count=operation_count,
             provider_message=response.msg,
+            staged_attachment_finalization=(
+                "provider_acknowledged_non_atomic" if staged_attachments else "not_requested"
+            ),
         )
 
     async def export(self, records: Sequence[RecordLocator]) -> RecordExport:
@@ -1979,7 +2055,7 @@ class Records:
 
     def _record_patch_payload(
         self, source: RecordLocator, before: Record, patch: RecordPatch
-    ) -> tuple[dict[str, object], int]:
+    ) -> tuple[dict[str, object], int, set[_StagedNotebookAttachmentIdentity]]:
         modules: dict[str, Mapping[str, object]] = {}
         for module in before.modules:
             name = module.get("name")
@@ -1994,6 +2070,7 @@ class Records:
         add_values: list[dict[str, object]] = []
         claimed_paths: set[tuple[str | int, ...]] = set()
         used_staged: set[tuple[int, str]] = set()
+        notebook_staged: set[_StagedNotebookAttachmentIdentity] = set()
 
         def claim(path: tuple[str | int, ...]) -> None:
             if path in claimed_paths:
@@ -2075,6 +2152,30 @@ class Records:
             )
 
         for change in patch.attachment_changes:
+            if isinstance(change, RecordFormAttachmentFieldAddition):
+                module = modules.get(change.module)
+                if module is None or module.get("type") != "form":
+                    raise MatelabUsageError(
+                        "A staged notebook attachment can be finalized only into an existing form module."
+                    )
+                if not change.name or self._module_has_field(module, change.name):
+                    raise MatelabUsageError("A staged notebook attachment requires a new non-empty form field name.")
+                identity = self._claim_notebook_staged_attachment(
+                    source.notebook,
+                    change.attachment,
+                    notebook_staged,
+                )
+                notebook_staged.add(identity)
+                add_values.append(
+                    {
+                        "module": change.module,
+                        "name": change.name,
+                        "type": "file",
+                        "data": [f"#file{{{change.attachment.binding.uid}}}"],
+                    }
+                )
+                continue
+
             if isinstance(change, RecordFormAttachmentRemoval):
                 current = self._current_attachment(source, before, change.attachment)
                 location = current.location
@@ -2189,6 +2290,10 @@ class Records:
         operation_count = len(modify) + len(delete_values) + len(create_modules) + len(delete_modules) + len(add_values)
         if operation_count == 0:
             raise MatelabUsageError("Record patch must contain at least one mutation.")
+        if notebook_staged and (len(notebook_staged) != 1 or operation_count != 1):
+            raise MatelabUsageError(
+                "A staged notebook attachment update must contain exactly one new form-file-field operation."
+            )
         payload: dict[str, object] = {}
         if modify:
             payload["modify"] = modify
@@ -2200,7 +2305,7 @@ class Records:
             payload["delModule"] = delete_modules
         if add_values:
             payload["add"] = add_values
-        return payload, operation_count
+        return payload, operation_count, notebook_staged
 
     @staticmethod
     def _module_type(name: str, modules: Mapping[str, Mapping[str, object]], created_types: Mapping[str, str]) -> str:
@@ -2224,6 +2329,15 @@ class Records:
                 return cast(str, field_mapping["type"])
         return None
 
+    @staticmethod
+    def _module_has_field(module: Mapping[str, object], field_name: str) -> bool:
+        if not isinstance(raw_fields := module.get("data"), list):
+            return False
+        for raw_field in cast(list[object], raw_fields):
+            if isinstance(raw_field, dict) and cast(dict[str, object], raw_field).get("name") == field_name:
+                return True
+        return False
+
     @classmethod
     def _validate_nonattachment_path(
         cls, path: tuple[str | int, ...], modules: Mapping[str, Mapping[str, object]]
@@ -2287,6 +2401,49 @@ class Records:
             raise MatelabUsageError("One staged record attachment can be consumed only once in a patch.")
         used.add(identity)
 
+    def _claim_notebook_staged_attachment(
+        self,
+        notebook: NotebookRef,
+        attachment: StagedNotebookAttachment,
+        used: set[_StagedNotebookAttachmentIdentity],
+    ) -> _StagedNotebookAttachmentIdentity:
+        uploader = self._authenticated_uploader()
+        if attachment.notebook != notebook:
+            raise MatelabUsageError("Staged notebook attachment belongs to a different notebook.")
+        if attachment.uploader != uploader:
+            raise MatelabUsageError("Staged notebook attachment belongs to a different authenticated user.")
+        if (
+            attachment.temporary_file_id < 1
+            or not attachment.binding.uid
+            or len(attachment.binding.uid) > 45
+            or not attachment.filename
+            or "\r" in attachment.filename
+            or "\n" in attachment.filename
+            or attachment.size < 0
+            or re.fullmatch(r"[0-9a-f]{64}", attachment.sha256) is None
+            or attachment.binding_state != "staged_not_bound"
+            or attachment.finalize_semantics != "single_import_or_update_attempt"
+        ):
+            raise MatelabUsageError("Staged notebook attachment metadata is invalid.")
+        identity = (
+            attachment.notebook,
+            attachment.uploader.userid,
+            attachment.binding.uid,
+        )
+        if identity in used:
+            raise MatelabUsageError("One staged notebook attachment can appear only once in a finalization request.")
+        return identity
+
+    def _mark_staged_finalization_attempts(
+        self,
+        attachments: set[_StagedNotebookAttachmentIdentity],
+    ) -> None:
+        if self._staged_finalization_attempts.intersection(attachments):
+            raise MatelabUsageError(
+                "This staged notebook attachment already had a finalization attempt; it cannot be retried."
+            )
+        self._staged_finalization_attempts.update(attachments)
+
     @staticmethod
     def _native_attachment_ref(attachment: StagedRecordAttachment) -> str:
         if "\r" in attachment.filename or "\n" in attachment.filename:
@@ -2310,6 +2467,105 @@ class Records:
             raise MatelabUsageError("Rich-text content contains an unresolved attachment marker.")
         return rendered
 
+    def _render_import_data(
+        self,
+        notebook: NotebookRef,
+        data: Mapping[str, object],
+        used_staged: set[_StagedNotebookAttachmentIdentity],
+    ) -> dict[str, object]:
+        return {name: self._render_import_value(notebook, value, used_staged) for name, value in data.items()}
+
+    def _render_import_value(
+        self,
+        notebook: NotebookRef,
+        value: object,
+        used_staged: set[_StagedNotebookAttachmentIdentity],
+    ) -> object:
+        if isinstance(value, StagedNotebookAttachment):
+            identity = self._claim_notebook_staged_attachment(notebook, value, used_staged)
+            used_staged.add(identity)
+            return f"#file{{{value.binding.uid}}}"
+        if isinstance(value, StagedRecordAttachment):
+            raise MatelabUsageError(
+                "A record-scoped staged attachment cannot be consumed by record import; "
+                + "use stage_attachment before importing."
+            )
+        if isinstance(value, str):
+            if _contains_native_attachment_reference(value):
+                raise MatelabUsageError(
+                    "Provider-native attachment references require a staged notebook attachment object."
+                )
+            return value
+        if isinstance(value, Mapping):
+            return {
+                key: self._render_import_value(notebook, item, used_staged)
+                for key, item in cast(Mapping[object, object], value).items()
+            }
+        if isinstance(value, (list, tuple)):
+            return [
+                self._render_import_value(notebook, item, used_staged)
+                for item in cast(list[object] | tuple[object, ...], value)
+            ]
+        return value
+
+    def _authenticated_uploader(self) -> UserRef:
+        identity = self._transport.require_session().identity
+        if identity is None:
+            raise MatelabUsageError(
+                "Notebook-scoped attachment staging requires a resolved session identity; "
+                + "call client.resolve_identity() first."
+            )
+        if identity.userid < 1:
+            raise MatelabUsageError("The resolved session identity has an invalid user identifier.")
+        return UserRef(userid=identity.userid)
+
+    async def _upload_record_attachment(
+        self,
+        *,
+        notebook: NotebookRef,
+        upload_event_uid: str,
+        binding: UploadBindingRef,
+        filename: str,
+        content: IO[bytes] | bytes,
+        size: int,
+        sha256: str,
+        content_type: str,
+    ) -> WireUploadAttachmentResponse:
+        notebook_title = self._notebook_title(notebook)
+        self._validate_upload_metadata(
+            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
+        )
+        try:
+            request = WireUploadAttachmentRequest.model_validate(
+                {
+                    "eln": notebook_title,
+                    "user": notebook.owner_userid if notebook.scope == "shared" else None,
+                    "uid": upload_event_uid,
+                    "name": binding.uid,
+                    "hash": sha256,
+                    "last": 1,
+                    "file": b"validation-placeholder",
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record attachment upload does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _UPLOAD_RECORD_ATTACHMENT,
+            payload=request.model_dump(mode="json", exclude={"file"}, exclude_none=True),
+            files={"file": (filename, content, content_type)},
+        )
+        if (
+            response.hash.root != sha256
+            or response.size != size
+            or response.filename != filename
+            or response.name != binding.uid
+        ):
+            raise MatelabProtocolError(
+                "Matelab staged the record attachment but returned different upload metadata; "
+                + "the temporary upload may remain."
+            )
+        return response
+
     @staticmethod
     def _validate_upload_metadata(
         *, filename: str, content: IO[bytes] | bytes, size: int, sha256: str, content_type: str

{matelab_python_sdk-0.1.0a1.dist-info → matelab_python_sdk-0.1.0a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a1
+Version: 0.1.0a2
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -28,10 +28,10 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a2`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec v0.1.0` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.1` Contract Release. The sole release pin is
 `contracts/matelab-integration-v1.lock.json`, which records
 the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
 
@@ -57,7 +57,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a1-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a2-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -164,10 +164,70 @@ lifecycle operations, record discovery/lifecycle operations, comment reads, and
 comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
 personal cloud-drive management.
 
+### Staging a record attachment before record creation
+
+`records.stage_attachment` supports the Contract's pre-upload workflow without inventing a target record UID.
+The returned `StagedNotebookAttachment` is scoped by the SDK to the resolved authenticated user and the exact
+notebook selector used for upload:
+
+```python
+import hashlib
+
+from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+
+content = b"measurement data"
+staged = await client.records.stage_attachment(
+    notebook=notebook,
+    filename="measurement.csv",
+    content=content,
+    size=len(content),
+    sha256=hashlib.sha256(content).hexdigest(),
+)
+result = await client.records.import_dataset(
+    notebook=notebook,
+    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    items=(
+        RecordImportItem(
+            record_uid="REC-IMPORT-001",
+            title="Imported measurement",
+            data={"Attachments": {"File": [staged]}},
+        ),
+    ),
+)
+```
+
+The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
+module:
+
+```python
+from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+
+# Alternative to the import above; do not run both with the same staged handle.
+result = await client.records.update(
+    source,
+    RecordPatch(
+        attachment_changes=(
+            RecordFormAttachmentFieldAddition(
+                module="Attachments",
+                name="Measurement",
+                attachment=staged,
+            ),
+        )
+    ),
+)
+```
+
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
+operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
+attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
+and a second finalization attempt through the same client. A Session imported without identity must first call
+`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
+guarantee, so callers must discard the handle as soon as a finalization request starts.
+
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.0` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
 must be added, records Provider-risk gates, and specifies the final completion checks.
 
 The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
@@ -533,6 +593,6 @@ uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
 ```
 
 Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.0`,
-commit `236795db1aa7a784ad9df936e9547e8d529be53f`, and OpenAPI SHA-256
-`62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.1`,
+commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
+`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.

{matelab_python_sdk-0.1.0a1.dist-info → matelab_python_sdk-0.1.0a2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-matelab/__init__.py,sha256=3iX8xyk434Yh8j_tsinsgW1bnMwgrv_dqGQEIspSFf8,9741
+matelab/__init__.py,sha256=lPCMdUftURTOuBw1XCHzHaSweIGZCq2ugqyPMe-R_vU,9883
 matelab/_transport.py,sha256=qMaioZcP5RfIxl5rr2FzY2Gn_zHAa-vJbjDNxapii-4,20223
 matelab/client.py,sha256=U54F-s8APVXppCjaMo-ALcQQCFM-VOzWoB_taeCdhXM,8168
 matelab/cloud_drive.py,sha256=NDVobVI-3MDRbbN_M6uRgM4apI6RUglk3ZAEdeaP90g,33306
@@ -8,15 +8,15 @@ matelab/literature.py,sha256=uMAXqDowj5JwSMed6b3koGHZBHF22GVqExO1kv2fmCY,51970
 matelab/models.py,sha256=AuIlyERpIVUYF2DgIhtC7LsmG4hLpHz28ae4hvyrEik,655
 matelab/notebooks.py,sha256=ykmpvziHGMtYt9vrMe97NSwcVTHsc4FRBStLNAhyDvc,19154
 matelab/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-matelab/records.py,sha256=9HiFdu9c8VqlbgSYhayOOXxZBSZeOMMHbkNm0a0-Xd4,107223
+matelab/records.py,sha256=KgvghcQ8oRR5p0pywMX3vVNJlqUw9WwDOPd9RWfHUl0,117926
 matelab/streaming.py,sha256=KcRx8QiBpaH198OY3YKdIFyx3bAikNf1sGHXXUKvoU4,3056
 matelab/templates.py,sha256=YpnCZ6WIMI7JEPYfdKNIzfuCMA9iwQx2qA473AvWpfk,31584
 matelab/uploads.py,sha256=_H6WdE_hvPdJeWdRdeh-0g9pm8EdxdcKKsv6hPMxObc,10182
 matelab/users.py,sha256=oU-FU0RNyNaSu6MBEL_2uP627AI7ZZWzQM7irwyJ1WY,2528
 matelab/_generated/__init__.py,sha256=jmGbXLLe3JorsGU7OUdF8iKGewFMRqkCzgyFAw7C15w,79
-matelab/_generated/models.py,sha256=uAsP0DYFGcanOxhn5-ISEXkoi_MDHhJylqwow-4MOBc,92551
-matelab_python_sdk-0.1.0a1.dist-info/METADATA,sha256=YMcK5wX333aTqUf4QrNsRiUUrUHctCe79BJCHKjSjAQ,27968
-matelab_python_sdk-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-matelab_python_sdk-0.1.0a1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-matelab_python_sdk-0.1.0a1.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
-matelab_python_sdk-0.1.0a1.dist-info/RECORD,,
+matelab/_generated/models.py,sha256=xXrIGbmgsyXjDO7RxSCMci2MkjB6azu6frrGOtIaJ2Q,93166
+matelab_python_sdk-0.1.0a2.dist-info/METADATA,sha256=G7r1hU4Zp_eaFB4a_ETF9F2cepBFxzFD6Qi1oBEz780,30183
+matelab_python_sdk-0.1.0a2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+matelab_python_sdk-0.1.0a2.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+matelab_python_sdk-0.1.0a2.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
+matelab_python_sdk-0.1.0a2.dist-info/RECORD,,