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

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

@@ -1,5 +1,21 @@
 # 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
+  uploads, correct content length, the bytes fast path, and existing non-replay retry restrictions.
+- Replaces implicit-override suppressions with explicit `@override` declarations, simplifies inferred model attributes,
+  and declares the Python 3.11 `typing-extensions` runtime dependency directly.
+
 ## 0.1.0a9 - 2026-08-04
 
 - Breaking: removes `MatelabProviderErrorKind` and `MatelabProviderError.kind`; Provider wire codes now map directly

matelab_python_sdk-0.1.0a9/README.md → matelab_python_sdk-0.1.0a11/PKG-INFO

@@ -1,8 +1,36 @@
+Metadata-Version: 2.4
+Name: matelab-python-sdk
+Version: 0.1.0a11
+Summary: Reusable async Python client for the Matelab Integration Contract
+Author-email: 朱天念 <zhutiannian@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.9.1
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: typing-extensions<5,>=4.14.1
+Description-Content-Type: text/markdown
+
 # matelab-python-sdk
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a9`. `[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 +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.0a9-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 +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. |
@@ -206,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:
 
@@ -601,8 +646,9 @@ object inheritance and preserves constraints the model generator cannot express
 writing the checked-in models. `WireModel` applies that metadata with the standard
 `jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current lock resolves
 `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`, and
-`pydantic>=2.13.4,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`,
+`pydantic>=2.13.4,<3`, and `typing-extensions>=4.14.1,<5`; the build backend requires
+`hatchling>=1.27,<2`. These lower bounds are verified
 against the complete test suite on the supported Python boundary versions rather than inferred from
 `uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
 Node wheel retain the compatible exact pair `basedpyright==1.39.9` and

matelab_python_sdk-0.1.0a9/PKG-INFO → matelab_python_sdk-0.1.0a11/README.md

@@ -1,35 +1,8 @@
-Metadata-Version: 2.4
-Name: matelab-python-sdk
-Version: 0.1.0a9
-Summary: Reusable async Python client for the Matelab Integration Contract
-Author-email: 朱天念 <zhutiannian@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: httpx2<3,>=2.9.1
-Requires-Dist: jsonschema<5,>=4.26
-Requires-Dist: pydantic<3,>=2.13.4
-Description-Content-Type: text/markdown
-
 # matelab-python-sdk
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a9`. `[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
@@ -58,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.0a9-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
@@ -93,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. |
@@ -233,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:
 
@@ -628,8 +618,9 @@ object inheritance and preserves constraints the model generator cannot express
 writing the checked-in models. `WireModel` applies that metadata with the standard
 `jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current lock resolves
 `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`, and
-`pydantic>=2.13.4,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`,
+`pydantic>=2.13.4,<3`, and `typing-extensions>=4.14.1,<5`; the build backend requires
+`hatchling>=1.27,<2`. These lower bounds are verified
 against the complete test suite on the supported Python boundary versions rather than inferred from
 `uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
 Node wheel retain the compatible exact pair `basedpyright==1.39.9` and

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a9"
+version = "0.1.0a11"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,7 @@ dependencies = [
     "httpx2>=2.9.1,<3",
     "jsonschema>=4.26,<5",
     "pydantic>=2.13.4,<3",
+    "typing-extensions>=4.14.1,<5",
 ]
 
 [dependency-groups]

{matelab_python_sdk-0.1.0a9 → matelab_python_sdk-0.1.0a11}/scripts/check_release.py

@@ -16,7 +16,12 @@ _PROJECT = cast(dict[str, object], tomllib.loads((_ROOT / "pyproject.toml").read
 _PROJECT_NAME = cast(str, _PROJECT["name"])
 _VERSION = cast(str, _PROJECT["version"])
 _DIST_INFO = f"{_PROJECT_NAME.replace('-', '_')}-{_VERSION}.dist-info"
-_EXPECTED_REQUIRES_DIST = {"httpx2<3,>=2.9.1", "jsonschema<5,>=4.26", "pydantic<3,>=2.13.4"}
+_EXPECTED_REQUIRES_DIST = {
+    "httpx2<3,>=2.9.1",
+    "jsonschema<5,>=4.26",
+    "pydantic<3,>=2.13.4",
+    "typing-extensions<5,>=4.14.1",
+}
 _EXPECTED_LICENSE_FILES = set(cast(list[str], _PROJECT["license-files"]))
 _AUTHOR = cast(list[dict[str, str]], _PROJECT["authors"])[0]
 _EXPECTED_AUTHOR_EMAIL = f"{_AUTHOR['name']} <{_AUTHOR['email']}>"

{matelab_python_sdk-0.1.0a9 → 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.0a9 → matelab_python_sdk-0.1.0a11}/src/matelab/_transport.py

@@ -1,14 +1,15 @@
 import asyncio
 import re
 import time
-from collections.abc import Mapping
+from collections.abc import AsyncIterator, Mapping
 from contextlib import suppress
 from dataclasses import dataclass
 from enum import StrEnum
 from typing import IO, Generic, TypeAlias, TypeVar, cast
 
-from httpx2 import AsyncClient, RequestError, Response
+from httpx2 import AsyncByteStream, AsyncClient, Request, RequestError, Response, SyncByteStream
 from pydantic import BaseModel, JsonValue, ValidationError
+from typing_extensions import override
 
 from matelab._generated import models as wire_models
 from matelab._wire_validation import validate_request
@@ -37,6 +38,21 @@ def _payload_mapping(payload: _Payload) -> Mapping[str, JsonValue]:
     return payload
 
 
+class _ThreadedMultipartStream(AsyncByteStream):
+    def __init__(self, stream: SyncByteStream) -> None:
+        self._stream = stream
+
+    @override
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        iterator = iter(self._stream)
+        while (chunk := await asyncio.to_thread(next, iterator, None)) is not None:
+            yield chunk
+
+    @override
+    async def aclose(self) -> None:
+        await asyncio.to_thread(self._stream.close)
+
+
 def _provider_error(code: int, *, provider_message: str) -> MatelabAuthenticationError | MatelabProviderError:
     if code == 1:
         return MatelabAuthenticationError("Matelab authentication failed.")
@@ -138,6 +154,37 @@ class SessionTransport:
             )
             return self.session
 
+    async def _send_multipart(
+        self,
+        operation: Operation[WireResponse],
+        *,
+        headers: dict[str, str],
+        payload: Mapping[str, JsonValue] | None,
+        files: _Files | None,
+    ) -> Response:
+        multipart = {
+            **{key: (None, str(value)) for key, value in (payload or {}).items()},
+            **(files or {}),
+        }
+        if files is None or all(isinstance(content, bytes) for _, content, _ in files.values()):
+            return await self._http.request(operation.method, operation.path, headers=headers, files=multipart)
+
+        base_request = self._http.build_request(operation.method, operation.path, headers=headers)
+        multipart_headers = base_request.headers.copy()
+        _ = multipart_headers.pop("Content-Length", None)
+        _ = multipart_headers.pop("Transfer-Encoding", None)
+        request = await asyncio.to_thread(
+            Request,
+            base_request.method,
+            base_request.url,
+            headers=multipart_headers,
+            files=multipart,
+            extensions=base_request.extensions,
+        )
+        if isinstance(request.stream, SyncByteStream):
+            request.stream = _ThreadedMultipartStream(request.stream)
+        return await self._http.send(request)
+
     async def request(
         self, operation: Operation[WireResponse], *, payload: _Payload | None = None, files: _Files | None = None
     ) -> WireResponse:
@@ -169,12 +216,11 @@ class SessionTransport:
                         operation.method, operation.path, headers=headers, data=encoded_payload
                     )
                 elif operation.encoding is Encoding.MULTIPART:
-                    multipart = {
-                        **{key: (None, str(value)) for key, value in (encoded_payload or {}).items()},
-                        **(files or {}),
-                    }
-                    response = await self._http.request(
-                        operation.method, operation.path, headers=headers, files=multipart
+                    response = await self._send_multipart(
+                        operation,
+                        headers=headers,
+                        payload=encoded_payload,
+                        files=files,
                     )
                 else:
                     response = await self._http.request(operation.method, operation.path, headers=headers)