matelab-python-sdk 0.1.0a10__tar.gz → 0.1.0a11__tar.gz

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0a11 - 2026-08-05
+
+- Adds `AsyncIterable[bytes]` support to the three complete record-attachment upload interfaces without adding new
+  methods. Async content is spooled, size/checksum validated, rewound, and cleaned up without blocking the event loop;
+  `sha256` may now be omitted and computed by the SDK.
+- Adds structured `MatelabAttachmentValidationError` reasons and expected/actual values so integrations can distinguish
+  size and checksum failures without parsing exception text. Validation failures occur before Provider staging, while
+  source exceptions propagate unchanged.
+
 ## 0.1.0a10 - 2026-08-05
 
 - Keeps synchronous multipart file length probes and chunk reads off the event-loop thread while preserving streamed

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a10
+Version: 0.1.0a11
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a10`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a11`. `[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.3.0` Contract Release. The sole release pin is
@@ -59,7 +59,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.0a10-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a11-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -94,6 +94,7 @@ Provider details:
 |---|---|---:|---|
 | `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
 | `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabAttachmentValidationError` | `VALIDATION` | No | Attachment content differs from its declared size or SHA-256; inspect `reason`, `expected`, and `actual`. |
 | `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
 | `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
@@ -234,6 +235,22 @@ result = await client.records.import_dataset(
 )
 ```
 
+`content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. `size` is always required and must
+be exact. `sha256` is optional; when omitted, the SDK computes it while consuming the content. Async content is fully
+consumed into a `SpooledTemporaryFile`, size-checked, checksum-checked when a checksum was supplied, rewound, and only
+then sent to the Provider. An over-size stream stops at the first chunk that exceeds the declared size. Temporary-file
+write, seek, read, and close operations run outside the event-loop thread, including after the spool rolls to disk.
+
+Local content mismatches raise `MatelabAttachmentValidationError`, a `MatelabUsageError` subtype. Its `reason` is
+`"size_mismatch"` or `"checksum_mismatch"`, while `expected` and `actual` carry the corresponding integer size or
+lowercase SHA-256 value. These failures happen before any Provider request. An exception raised by the async source is
+propagated unchanged after the SDK closes its temporary file. The SDK does not impose an upload-size policy; callers
+remain responsible for limits such as an HTTP endpoint's maximum accepted body size.
+
+The same content interface is available on `records.upload_attachment()` and
+`records.upload_comment_attachment()`. `uploads.stage()` remains a separate resumable-fragment interface and does not
+accept async content because its per-fragment offset and completion semantics are different.
+
 The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
 existing form module:
 

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a10`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a11`. `[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.3.0` Contract Release. The sole release pin is
@@ -31,7 +31,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.0a10-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a11-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -66,6 +66,7 @@ Provider details:
 |---|---|---:|---|
 | `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
 | `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabAttachmentValidationError` | `VALIDATION` | No | Attachment content differs from its declared size or SHA-256; inspect `reason`, `expected`, and `actual`. |
 | `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
 | `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
@@ -206,6 +207,22 @@ result = await client.records.import_dataset(
 )
 ```
 
+`content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. `size` is always required and must
+be exact. `sha256` is optional; when omitted, the SDK computes it while consuming the content. Async content is fully
+consumed into a `SpooledTemporaryFile`, size-checked, checksum-checked when a checksum was supplied, rewound, and only
+then sent to the Provider. An over-size stream stops at the first chunk that exceeds the declared size. Temporary-file
+write, seek, read, and close operations run outside the event-loop thread, including after the spool rolls to disk.
+
+Local content mismatches raise `MatelabAttachmentValidationError`, a `MatelabUsageError` subtype. Its `reason` is
+`"size_mismatch"` or `"checksum_mismatch"`, while `expected` and `actual` carry the corresponding integer size or
+lowercase SHA-256 value. These failures happen before any Provider request. An exception raised by the async source is
+propagated unchanged after the SDK closes its temporary file. The SDK does not impose an upload-size policy; callers
+remain responsible for limits such as an HTTP endpoint's maximum accepted body size.
+
+The same content interface is available on `records.upload_attachment()` and
+`records.upload_comment_attachment()`. `uploads.stage()` remains a separate resumable-fragment interface and does not
+accept async content because its per-fragment offset and completion semantics are different.
+
 The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
 existing form module:
 

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a10"
+version = "0.1.0a11"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/src/matelab/__init__.py

@@ -113,6 +113,7 @@ from matelab.domains.templates import (
 from matelab.domains.uploads import StagedFile, StagedFileFragment, StagedUploadSession, UploadBindingRef
 from matelab.domains.users import UserRef, UserSummary
 from matelab.errors import (
+    MatelabAttachmentValidationError,
     MatelabAuthenticationError,
     MatelabError,
     MatelabErrorCategory,
@@ -163,6 +164,7 @@ __all__ = [
     "LiteraturePdf",
     "LiteratureSource",
     "LiteratureStoredMetadata",
+    "MatelabAttachmentValidationError",
     "MatelabAuthenticationError",
     "MatelabError",
     "MatelabErrorCategory",

matelab_python_sdk-0.1.0a11/src/matelab/_attachment_content.py

@@ -0,0 +1,71 @@
+import asyncio
+import hashlib
+from collections.abc import AsyncGenerator, AsyncIterable, AsyncIterator
+from contextlib import asynccontextmanager
+from tempfile import SpooledTemporaryFile
+from typing import IO
+
+from matelab.errors import MatelabAttachmentValidationError
+
+_READ_SIZE = 64 * 1024
+_SPOOL_MEMORY_LIMIT = 1024 * 1024
+
+
+async def _chunks(content: IO[bytes] | AsyncIterable[bytes]) -> AsyncIterator[bytes]:
+    if isinstance(content, AsyncIterable):
+        async for chunk in content:
+            yield chunk
+        return
+
+    while chunk := await asyncio.to_thread(content.read, _READ_SIZE):
+        yield chunk
+
+
+def _validate_content(*, expected_size: int, actual_size: int, expected_sha256: str | None, actual_sha256: str) -> None:
+    if actual_size != expected_size:
+        raise MatelabAttachmentValidationError("size_mismatch", expected=expected_size, actual=actual_size)
+    if expected_sha256 is not None and actual_sha256 != expected_sha256:
+        raise MatelabAttachmentValidationError("checksum_mismatch", expected=expected_sha256, actual=actual_sha256)
+
+
+@asynccontextmanager
+async def validated_attachment_content(
+    content: IO[bytes] | bytes | AsyncIterable[bytes], *, size: int, sha256: str | None
+) -> AsyncGenerator[tuple[IO[bytes] | bytes, int, str]]:
+    if isinstance(content, bytes):
+        actual_sha256 = hashlib.sha256(content).hexdigest()
+        _validate_content(
+            expected_size=size,
+            actual_size=len(content),
+            expected_sha256=sha256,
+            actual_sha256=actual_sha256,
+        )
+        yield content, len(content), actual_sha256
+        return
+
+    if not isinstance(content, AsyncIterable) and sha256 is not None:
+        yield content, size, sha256
+        return
+
+    cached = await asyncio.to_thread(SpooledTemporaryFile, max_size=_SPOOL_MEMORY_LIMIT, mode="w+b")
+    digest = hashlib.sha256()
+    actual_size = 0
+    try:
+        async for chunk in _chunks(content):
+            actual_size += len(chunk)
+            if actual_size > size:
+                raise MatelabAttachmentValidationError("size_mismatch", expected=size, actual=actual_size)
+            digest.update(chunk)
+            _ = await asyncio.to_thread(cached.write, chunk)
+
+        actual_sha256 = digest.hexdigest()
+        _validate_content(
+            expected_size=size,
+            actual_size=actual_size,
+            expected_sha256=sha256,
+            actual_sha256=actual_sha256,
+        )
+        _ = await asyncio.to_thread(cached.seek, 0)
+        yield cached, actual_size, actual_sha256
+    finally:
+        await asyncio.to_thread(cached.close)

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/src/matelab/domains/records.py

@@ -1,7 +1,7 @@
 import hashlib
 import json
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import AsyncIterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from html.parser import HTMLParser
 from types import MappingProxyType
@@ -11,6 +11,7 @@ from urllib.parse import parse_qs, unquote
 from pydantic import JsonValue
 from typing_extensions import override
 
+from matelab._attachment_content import validated_attachment_content
 from matelab._generated import models as wire_models
 from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation
 from matelab._wire_validation import encode_json_field, validate_request
@@ -1071,14 +1072,14 @@ class Records:
         source: RecordLocator,
         *,
         filename: str,
-        content: IO[bytes] | bytes,
+        content: IO[bytes] | bytes | AsyncIterable[bytes],
         size: int,
-        sha256: str,
+        sha256: str | None = None,
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedRecordAttachment:
         selected_binding = binding or UploadBindingRef.new()
-        response = await self._upload_record_attachment(
+        response, actual_size, actual_sha256 = await self._upload_record_attachment(
             notebook=source.notebook,
             upload_event_uid=source.record.record_uid,
             binding=selected_binding,
@@ -1093,8 +1094,8 @@ class Records:
             temporary_file_id=response.id,
             binding=selected_binding,
             filename=response.filename,
-            size=response.size,
-            sha256=response.hash.root,
+            size=actual_size,
+            sha256=actual_sha256,
         )
 
     async def stage_attachment(
@@ -1102,9 +1103,9 @@ class Records:
         *,
         notebook: NotebookRef,
         filename: str,
-        content: IO[bytes] | bytes,
+        content: IO[bytes] | bytes | AsyncIterable[bytes],
         size: int,
-        sha256: str,
+        sha256: str | None = None,
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedNotebookAttachment:
@@ -1117,7 +1118,7 @@ class Records:
 
         uploader = self._authenticated_uploader()
         selected_binding = binding or UploadBindingRef.new()
-        response = await self._upload_record_attachment(
+        response, actual_size, actual_sha256 = await self._upload_record_attachment(
             notebook=notebook,
             upload_event_uid=UploadBindingRef.new().uid,
             binding=selected_binding,
@@ -1133,8 +1134,8 @@ class Records:
             temporary_file_id=response.id,
             binding=selected_binding,
             filename=response.filename,
-            size=response.size,
-            sha256=response.hash.root,
+            size=actual_size,
+            sha256=actual_sha256,
         )
 
     async def update(
@@ -1515,52 +1516,57 @@ class Records:
         source: RecordLocator,
         *,
         filename: str,
-        content: IO[bytes] | bytes,
+        content: IO[bytes] | bytes | AsyncIterable[bytes],
         size: int,
-        sha256: str,
+        sha256: str | None = None,
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedRecordCommentAttachment:
         selected_binding = binding or UploadBindingRef.new()
-        self._validate_upload_metadata(
-            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
-        )
-        request = validate_request(
-            wire_models.UploadRecordCommentAttachmentRequest,
-            {
-                "uid": selected_binding.uid,
-                "eln": source.notebook.notebook_id,
-                "i": source.record.record_database_id,
-                "upload": b"validation-placeholder",
-            },
-            "Record-comment attachment upload does not satisfy the Integration Contract.",
-        )
-        response = await self._transport.request(
-            _UPLOAD_COMMENT_ATTACHMENT,
-            payload=request.model_dump(mode="json", exclude={"upload"}),
-            files={"upload": (filename, content, content_type)},
-        )
-        returned_notebook_id, temporary_id, returned_sha256, returned_size, returned_filename, canonical_reference = (
-            self._parse_comment_upload_query(response.query)
-        )
-        if (
-            returned_notebook_id != source.notebook.notebook_id
-            or response.filename != filename
-            or returned_filename != filename
-            or returned_sha256 != sha256
-            or returned_size != size
-        ):
-            raise MatelabProtocolError(
-                "Matelab staged the comment attachment but returned different upload metadata; "
-                + "the temporary upload cannot be aborted through this Contract."
+        self._validate_upload_metadata(filename=filename, size=size, sha256=sha256, content_type=content_type)
+        async with validated_attachment_content(content, size=size, sha256=sha256) as prepared:
+            prepared_content, actual_size, actual_sha256 = prepared
+            request = validate_request(
+                wire_models.UploadRecordCommentAttachmentRequest,
+                {
+                    "uid": selected_binding.uid,
+                    "eln": source.notebook.notebook_id,
+                    "i": source.record.record_database_id,
+                    "upload": b"validation-placeholder",
+                },
+                "Record-comment attachment upload does not satisfy the Integration Contract.",
             )
+            response = await self._transport.request(
+                _UPLOAD_COMMENT_ATTACHMENT,
+                payload=request.model_dump(mode="json", exclude={"upload"}),
+                files={"upload": (filename, prepared_content, content_type)},
+            )
+            (
+                returned_notebook_id,
+                temporary_id,
+                returned_sha256,
+                returned_size,
+                returned_filename,
+                canonical_reference,
+            ) = self._parse_comment_upload_query(response.query)
+            if (
+                returned_notebook_id != source.notebook.notebook_id
+                or response.filename != filename
+                or returned_filename != filename
+                or returned_sha256 != actual_sha256
+                or returned_size != actual_size
+            ):
+                raise MatelabProtocolError(
+                    "Matelab staged the comment attachment but returned different upload metadata; "
+                    + "the temporary upload cannot be aborted through this Contract."
+                )
         return StagedRecordCommentAttachment(
             source=source,
             binding=selected_binding,
             temporary_file_id=temporary_id,
             filename=filename,
-            size=size,
-            sha256=sha256,
+            size=actual_size,
+            sha256=actual_sha256,
             _temporary_url=self._transport.absolute_url(response.path, response.query),
             _canonical_reference=canonical_reference,
         )
@@ -2494,63 +2500,59 @@ class Records:
         upload_event_uid: str,
         binding: UploadBindingRef,
         filename: str,
-        content: IO[bytes] | bytes,
+        content: IO[bytes] | bytes | AsyncIterable[bytes],
         size: int,
-        sha256: str,
+        sha256: str | None,
         content_type: str,
-    ) -> wire_models.UploadAttachmentResponse:
+    ) -> tuple[wire_models.UploadAttachmentResponse, int, str]:
         notebook_title = self._notebook_title(notebook)
-        self._validate_upload_metadata(
-            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
-        )
-        request = validate_request(
-            wire_models.UploadAttachmentRequest,
-            {
-                "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",
-            },
-            "Record attachment upload does not satisfy the Integration Contract.",
-        )
-        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."
+        self._validate_upload_metadata(filename=filename, size=size, sha256=sha256, content_type=content_type)
+        async with validated_attachment_content(content, size=size, sha256=sha256) as prepared:
+            prepared_content, actual_size, actual_sha256 = prepared
+            request = validate_request(
+                wire_models.UploadAttachmentRequest,
+                {
+                    "eln": notebook_title,
+                    "user": notebook.owner_userid if notebook.scope == "shared" else None,
+                    "uid": upload_event_uid,
+                    "name": binding.uid,
+                    "hash": actual_sha256,
+                    "last": 1,
+                    "file": b"validation-placeholder",
+                },
+                "Record attachment upload does not satisfy the Integration Contract.",
+            )
+            response = await self._transport.request(
+                _UPLOAD_RECORD_ATTACHMENT,
+                payload=request.model_dump(mode="json", exclude={"file"}, exclude_none=True),
+                files={"file": (filename, prepared_content, content_type)},
             )
-        return response
+            if (
+                response.hash.root != actual_sha256
+                or response.size != actual_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, actual_size, actual_sha256
 
     @staticmethod
-    def _validate_upload_metadata(
-        *, filename: str, content: IO[bytes] | bytes, size: int, sha256: str, content_type: str
-    ) -> None:
+    def _validate_upload_metadata(*, filename: str, size: int, sha256: str | None, content_type: str) -> None:
         if (
             not filename
             or len(filename) > 1000
             or "\r" in filename
             or "\n" in filename
             or size < 0
-            or re.fullmatch(r"[0-9a-f]{64}", sha256) is None
+            or (sha256 is not None and re.fullmatch(r"[0-9a-f]{64}", sha256) is None)
             or not content_type
             or "\r" in content_type
             or "\n" in content_type
         ):
             raise MatelabUsageError("Attachment metadata does not satisfy the Integration Contract.")
-        if isinstance(content, bytes) and (len(content) != size or hashlib.sha256(content).hexdigest() != sha256):
-            raise MatelabUsageError("Attachment bytes do not match the declared size and SHA-256.")
 
     @staticmethod
     def _parse_comment_upload_query(query: str) -> tuple[int, int, str, int, str, str]:

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/src/matelab/errors.py

@@ -1,4 +1,5 @@
 from enum import StrEnum
+from typing import Literal
 
 
 class MatelabErrorCategory(StrEnum):
@@ -37,6 +38,27 @@ class MatelabUsageError(MatelabError):
     category = MatelabErrorCategory.VALIDATION
 
 
+class MatelabAttachmentValidationError(MatelabUsageError):
+    """Attachment bytes differ from caller-declared upload metadata."""
+
+    def __init__(
+        self,
+        reason: Literal["size_mismatch", "checksum_mismatch"],
+        *,
+        expected: int | str,
+        actual: int | str,
+    ) -> None:
+        message = (
+            "Attachment content size does not match the declared size."
+            if reason == "size_mismatch"
+            else "Attachment content SHA-256 does not match the declared checksum."
+        )
+        super().__init__(message)
+        self.reason = reason
+        self.expected = expected
+        self.actual = actual
+
+
 class MatelabTransportError(MatelabError):
     """The HTTP exchange with the Provider failed."""
 

matelab_python_sdk-0.1.0a11/tests/test_async_attachment_upload.py

@@ -0,0 +1,378 @@
+import asyncio
+import hashlib
+from collections.abc import Callable
+from io import BytesIO
+from tempfile import SpooledTemporaryFile
+from threading import Event, Lock
+from typing import IO, cast
+
+import pytest
+from httpx2 import AsyncClient, MockTransport, Request, Response
+
+from matelab import (
+    AsyncMatelab,
+    MatelabAttachmentValidationError,
+    NotebookRef,
+    RecordLocator,
+    RecordRef,
+    Session,
+    UploadBindingRef,
+)
+
+_CONTENT = b"alpha"
+_SHA256 = hashlib.sha256(_CONTENT).hexdigest()
+_NOTEBOOK = NotebookRef(notebook_id=12, title="Example Notebook", owner_userid=42, scope="owned")
+_SOURCE = RecordLocator(notebook=_NOTEBOOK, record=RecordRef(record_database_id=9001, record_uid="REC-001"))
+_SPOOL_WRITE = cast(Callable[[SpooledTemporaryFile[bytes], bytes], int], SpooledTemporaryFile.write)
+_SPOOL_SEEK = cast(Callable[[SpooledTemporaryFile[bytes], int, int], int], SpooledTemporaryFile.seek)
+_SPOOL_READ = cast(Callable[[SpooledTemporaryFile[bytes], int], bytes], SpooledTemporaryFile.read)
+_SPOOL_CLOSE = cast(Callable[[SpooledTemporaryFile[bytes]], None], SpooledTemporaryFile.close)
+
+
+def _upload_response(
+    envelope: Callable[..., dict[str, object]], *, binding: UploadBindingRef, sha256: str = _SHA256
+) -> Response:
+    return Response(
+        200,
+        json=envelope(
+            id=7301,
+            path="url_eln/temp",
+            query=f"h={sha256}&id=7301&s={len(_CONTENT)}&f=alpha.txt",
+            name=binding.uid,
+            filename="alpha.txt",
+            size=len(_CONTENT),
+            hash=sha256,
+        ),
+    )
+
+
+@pytest.mark.asyncio
+async def test_stage_attachment_accepts_async_content(
+    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    binding = UploadBindingRef(uid="async-upload-with-checksum")
+
+    async def content():
+        yield b"al"
+        await asyncio.sleep(0)
+        yield b"pha"
+
+    async def handler(request: Request) -> Response:
+        assert request.url.path == "/api/eln_api/upload"
+        assert b'name="file"; filename="alpha.txt"' in request.content
+        assert b"\r\n\r\nalpha\r\n" in request.content
+        return _upload_response(provider_envelope, binding=binding)
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        staged = await client.records.stage_attachment(
+            notebook=_NOTEBOOK,
+            filename="alpha.txt",
+            content=content(),
+            size=len(_CONTENT),
+            sha256=_SHA256,
+            binding=binding,
+        )
+
+    assert staged.size == len(_CONTENT)
+    assert staged.sha256 == _SHA256
+
+
+@pytest.mark.asyncio
+async def test_stage_attachment_computes_missing_async_checksum(
+    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    binding = UploadBindingRef(uid="async-upload-computed-checksum")
+
+    async def content():
+        yield _CONTENT
+
+    async def handler(request: Request) -> Response:
+        assert _SHA256.encode() in request.content
+        return _upload_response(provider_envelope, binding=binding)
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        staged = await client.records.stage_attachment(
+            notebook=_NOTEBOOK,
+            filename="alpha.txt",
+            content=content(),
+            size=len(_CONTENT),
+            binding=binding,
+        )
+
+    assert staged.size == len(_CONTENT)
+    assert staged.sha256 == _SHA256
+
+
+@pytest.mark.asyncio
+async def test_record_attachment_upload_uses_shared_async_content_handling(
+    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    binding = UploadBindingRef(uid="async-record-upload")
+
+    async def content():
+        yield _CONTENT
+
+    async def handler(request: Request) -> Response:
+        assert request.url.path == "/api/eln_api/upload"
+        return _upload_response(provider_envelope, binding=binding)
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        staged = await client.records.upload_attachment(
+            _SOURCE,
+            filename="alpha.txt",
+            content=content(),
+            size=len(_CONTENT),
+            binding=binding,
+        )
+
+    assert staged.size == len(_CONTENT)
+    assert staged.sha256 == _SHA256
+
+
+@pytest.mark.asyncio
+async def test_comment_attachment_upload_uses_shared_async_content_handling(
+    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    binding = UploadBindingRef(uid="async-comment-upload")
+
+    async def content():
+        yield _CONTENT
+
+    async def handler(request: Request) -> Response:
+        assert request.url.path == "/api/eln_items/more_upload"
+        assert b'name="upload"; filename="alpha.txt"' in request.content
+        return Response(
+            200,
+            json=provider_envelope(
+                filename="alpha.txt",
+                path="eln_url/eln_temp",
+                query=f"eln=12&id=7302&h={_SHA256}&s={len(_CONTENT)}&f=alpha.txt",
+            ),
+        )
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        staged = await client.records.upload_comment_attachment(
+            _SOURCE,
+            filename="alpha.txt",
+            content=content(),
+            size=len(_CONTENT),
+            binding=binding,
+        )
+
+    assert staged.size == len(_CONTENT)
+    assert staged.sha256 == _SHA256
+
+
+@pytest.mark.parametrize(
+    ("chunks", "declared_size", "actual_size"),
+    [
+        pytest.param((b"alpha",), 4, 5, id="too-large"),
+        pytest.param((b"al", b"ph"), 5, 4, id="too-small"),
+    ],
+)
+@pytest.mark.asyncio
+async def test_async_attachment_size_mismatch_is_structured_and_sends_no_http(
+    provider_session: Session,
+    chunks: tuple[bytes, ...],
+    declared_size: int,
+    actual_size: int,
+) -> None:
+    calls = 0
+
+    async def content():
+        for chunk in chunks:
+            yield chunk
+
+    async def handler(_: Request) -> Response:
+        nonlocal calls
+        calls += 1
+        raise AssertionError("validation failures must not send HTTP")
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabAttachmentValidationError) as caught:
+            _ = await client.records.stage_attachment(
+                notebook=_NOTEBOOK,
+                filename="alpha.txt",
+                content=content(),
+                size=declared_size,
+            )
+
+    assert caught.value.reason == "size_mismatch"
+    assert caught.value.expected == declared_size
+    assert caught.value.actual == actual_size
+    assert calls == 0
+
+
+@pytest.mark.asyncio
+async def test_async_attachment_checksum_mismatch_is_structured_and_sends_no_http(
+    provider_session: Session,
+) -> None:
+    calls = 0
+    expected_sha256 = "0" * 64
+
+    async def content():
+        yield _CONTENT
+
+    async def handler(_: Request) -> Response:
+        nonlocal calls
+        calls += 1
+        raise AssertionError("validation failures must not send HTTP")
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabAttachmentValidationError) as caught:
+            _ = await client.records.stage_attachment(
+                notebook=_NOTEBOOK,
+                filename="alpha.txt",
+                content=content(),
+                size=len(_CONTENT),
+                sha256=expected_sha256,
+            )
+
+    assert caught.value.reason == "checksum_mismatch"
+    assert caught.value.expected == expected_sha256
+    assert caught.value.actual == _SHA256
+    assert calls == 0
+
+
+@pytest.mark.asyncio
+async def test_spooled_async_attachment_operations_do_not_block_the_event_loop(
+    monkeypatch: pytest.MonkeyPatch,
+    provider_session: Session,
+    provider_envelope: Callable[..., dict[str, object]],
+) -> None:
+    binding = UploadBindingRef(uid="async-upload-threaded-spool")
+    operations = ("write", "seek", "read", "close")
+    started = {operation: Event() for operation in operations}
+    progressed = {operation: Event() for operation in operations}
+    observed: set[str] = set()
+    observed_lock = Lock()
+
+    def wait_for_event_loop(operation: str) -> None:
+        with observed_lock:
+            first_call = operation not in observed
+            observed.add(operation)
+        if first_call:
+            started[operation].set()
+            if not progressed[operation].wait(timeout=5):
+                raise AssertionError(f"event loop did not progress during spooled-file {operation}")
+
+    def blocking_write(file: SpooledTemporaryFile[bytes], data: bytes) -> int:
+        file.rollover()
+        wait_for_event_loop("write")
+        return _SPOOL_WRITE(file, data)
+
+    def blocking_seek(file: SpooledTemporaryFile[bytes], offset: int, whence: int = 0) -> int:
+        wait_for_event_loop("seek")
+        return _SPOOL_SEEK(file, offset, whence)
+
+    def blocking_read(file: SpooledTemporaryFile[bytes], size: int = -1) -> bytes:
+        wait_for_event_loop("read")
+        return _SPOOL_READ(file, size)
+
+    def blocking_close(file: SpooledTemporaryFile[bytes]) -> None:
+        wait_for_event_loop("close")
+        _SPOOL_CLOSE(file)
+
+    monkeypatch.setattr(SpooledTemporaryFile, "write", blocking_write)
+    monkeypatch.setattr(SpooledTemporaryFile, "seek", blocking_seek)
+    monkeypatch.setattr(SpooledTemporaryFile, "read", blocking_read)
+    monkeypatch.setattr(SpooledTemporaryFile, "close", blocking_close)
+
+    async def observe_operations() -> None:
+        for operation in operations:
+            while not started[operation].is_set():
+                await asyncio.sleep(0)
+            progressed[operation].set()
+
+    async def content():
+        yield _CONTENT
+
+    async def handler(_: Request) -> Response:
+        return _upload_response(provider_envelope, binding=binding)
+
+    observer = asyncio.create_task(observe_operations())
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        _ = await client.records.stage_attachment(
+            notebook=_NOTEBOOK,
+            filename="alpha.txt",
+            content=content(),
+            size=len(_CONTENT),
+            binding=binding,
+        )
+    await observer
+
+    assert observed == set(operations)
+
+
+@pytest.mark.asyncio
+async def test_async_source_exception_propagates_and_closes_spooled_file(
+    monkeypatch: pytest.MonkeyPatch, provider_session: Session
+) -> None:
+    calls = 0
+    closed = Event()
+    source_error = RuntimeError("caller disconnected")
+
+    def observed_close(file: SpooledTemporaryFile[bytes]) -> None:
+        closed.set()
+        _SPOOL_CLOSE(file)
+
+    monkeypatch.setattr(SpooledTemporaryFile, "close", observed_close)
+
+    async def content():
+        yield b"al"
+        raise source_error
+
+    async def handler(_: Request) -> Response:
+        nonlocal calls
+        calls += 1
+        raise AssertionError("a failed source must not send HTTP")
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(RuntimeError) as caught:
+            _ = await client.records.stage_attachment(
+                notebook=_NOTEBOOK,
+                filename="alpha.txt",
+                content=content(),
+                size=len(_CONTENT),
+            )
+
+    assert caught.value is source_error
+    assert closed.is_set()
+    assert calls == 0
+
+
+@pytest.mark.parametrize(
+    "content", [pytest.param(_CONTENT, id="bytes"), pytest.param(BytesIO(_CONTENT), id="binary-io")]
+)
+@pytest.mark.asyncio
+async def test_stage_attachment_preserves_existing_content_inputs(
+    content: IO[bytes] | bytes,
+    provider_session: Session,
+    provider_envelope: Callable[..., dict[str, object]],
+) -> None:
+    binding = UploadBindingRef(uid="compatible-upload-input")
+
+    async def handler(request: Request) -> Response:
+        assert b"\r\n\r\nalpha\r\n" in request.content
+        return _upload_response(provider_envelope, binding=binding)
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        staged = await client.records.stage_attachment(
+            notebook=_NOTEBOOK,
+            filename="alpha.txt",
+            content=content,
+            size=len(_CONTENT),
+            sha256=_SHA256,
+            binding=binding,
+        )
+
+    assert staged.sha256 == _SHA256

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/tests/test_errors.py

@@ -1,7 +1,10 @@
+from typing import Literal
+
 import pytest
 
 import matelab
 from matelab import (
+    MatelabAttachmentValidationError,
     MatelabAuthenticationError,
     MatelabError,
     MatelabErrorCategory,
@@ -13,6 +16,7 @@ from matelab import (
 
 
 def test_provider_error_kind_is_not_part_of_public_interface() -> None:
+    assert "MatelabAttachmentValidationError" in matelab.__all__
     assert "MatelabProviderErrorKind" not in matelab.__all__
     assert not hasattr(matelab, "MatelabProviderErrorKind")
 
@@ -65,3 +69,22 @@ def test_transport_error_preserves_http_status_without_changing_integration_sema
     assert error.status_code == 503
     assert error.category is MatelabErrorCategory.UPSTREAM
     assert error.retryable is False
+
+
+@pytest.mark.parametrize(
+    ("reason", "expected", "actual"),
+    [
+        pytest.param("size_mismatch", 5, 4, id="size"),
+        pytest.param("checksum_mismatch", "a" * 64, "b" * 64, id="checksum"),
+    ],
+)
+def test_attachment_validation_error_exposes_stable_reason_and_values(
+    reason: Literal["size_mismatch", "checksum_mismatch"], expected: int | str, actual: int | str
+) -> None:
+    error = MatelabAttachmentValidationError(reason, expected=expected, actual=actual)
+
+    assert error.reason == reason
+    assert error.expected == expected
+    assert error.actual == actual
+    assert error.category is MatelabErrorCategory.VALIDATION
+    assert error.retryable is False

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/tests/typing/consumer.py

@@ -1,5 +1,8 @@
+from collections.abc import AsyncIterator
+
 from matelab import (
     AsyncMatelab,
+    MatelabAttachmentValidationError,
     MatelabError,
     MatelabErrorCategory,
     MatelabProviderError,
@@ -34,6 +37,10 @@ def construct_provider_error(category: MatelabErrorCategory) -> MatelabProviderE
     return MatelabProviderError("failure", category=category)
 
 
+def consume_attachment_error(error: MatelabAttachmentValidationError) -> tuple[str, int | str, int | str]:
+    return error.reason, error.expected, error.actual
+
+
 async def consume_public_types(client: AsyncMatelab) -> tuple[Session | None, NotebookCollection]:
     notebooks: NotebookCollection = await client.notebooks.list()
     session: Session | None = client.session
@@ -47,12 +54,14 @@ async def consume_public_types(client: AsyncMatelab) -> tuple[Session | None, No
 async def consume_staged_attachment(
     client: AsyncMatelab, notebook: NotebookRef, source: RecordLocator, attachment: StagedNotebookAttachment
 ) -> None:
+    async def content() -> AsyncIterator[bytes]:
+        yield b"example"
+
     staged: StagedNotebookAttachment = await client.records.stage_attachment(
         notebook=notebook,
         filename="example.txt",
-        content=b"example",
+        content=content(),
         size=7,
-        sha256="50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacbce6576c",
     )
     import_item: RecordImportItem = RecordImportItem(
         record_uid="REC-IMPORT-001", title="Imported", data={"Attachments": {"File": [staged]}}

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a11}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a10"
+version = "0.1.0a11"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },