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

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/.github/workflows/release.yml

@@ -23,6 +23,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           version: "0.11.32"
+          python-version: ${{ matrix.python-version }}
       - name: Sync locked environment
         run: uv sync --frozen --python "${{ matrix.python-version }}"
       - name: Check generated wire models
@@ -53,6 +54,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           version: "0.11.32"
+          python-version: "3.14"
       - name: Verify tag and configure timestamp
         shell: bash
         run: |

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/AGENTS.md

@@ -62,8 +62,8 @@
 - mutation 默认不自动重试。multipart 或 stream 只有在确认可重放时才能重试；download stream 不自动重放，
   必须支持显式关闭。
 - HTTP/transport、Provider business/authentication、Wire Contract/schema 和 client usage 错误必须稳定区分。
-- 每个公开 `MatelabError` 必须直接提供稳定的集成级 `category` 和保守的 `retryable`；Provider kind 和 HTTP
-  status 只用于诊断，下游不得重新解释 Provider 数字 code 才能决定恢复类别。
+- 每个公开 `MatelabError` 必须直接提供稳定的集成级 `category` 和保守的 `retryable`；HTTP status 只用于诊断，
+  下游不得重新解释 Provider 数字 code 才能决定恢复类别。
 - password、token、SSO code/key、临时附件凭证、原始文件内容和敏感 payload 不得进入日志、异常或提交内容。
 
 ## 测试与质量门槛

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

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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
+  to the final `MatelabErrorCategory`, which integrations consume through `MatelabError.category`. This public API
+  removal requires a subsequent SemVer-appropriate release before distribution. Operation-specific code `0`/`10`
+  success handling and the bounded code `5` authentication refresh remain unchanged.
+- Adds a conservative `retryable` flag to every public SDK error.
+
 ## 0.1.0a8 - 2026-08-04
 
 - Adds a unified `MatelabErrorCategory` and conservative `retryable` flag to every public SDK error, centralizing

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a8
+Version: 0.1.0a10
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -23,13 +23,14 @@ 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.0a8`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a10`. `[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 +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.0a8-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a10-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -93,16 +94,17 @@ 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. |
-| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route by `category`, with `kind` available only for diagnosis. |
+| `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. |
 
-For `MatelabProviderError`, the SDK maps `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
-`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
-do not need it for recovery routing. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider
-codes are not part of the public error interface.
+For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
+unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
+are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
+operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
+`MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
-success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
+success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
 never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
 interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
@@ -627,8 +629,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.0a8 → matelab_python_sdk-0.1.0a10}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a8`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a10`. `[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.0a8-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a10-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -66,16 +66,17 @@ 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. |
-| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route by `category`, with `kind` available only for diagnosis. |
+| `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. |
 
-For `MatelabProviderError`, the SDK maps `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
-`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
-do not need it for recovery routing. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider
-codes are not part of the public error interface.
+For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
+unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
+are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
+operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
+`MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
-success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
+success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
 never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
 interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
@@ -600,8 +601,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.0a8 → matelab_python_sdk-0.1.0a10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a8"
+version = "0.1.0a10"
 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.0a8 → matelab_python_sdk-0.1.0a10}/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.0a8 → matelab_python_sdk-0.1.0a10}/src/matelab/__init__.py

@@ -118,7 +118,6 @@ from matelab.errors import (
     MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -169,7 +168,6 @@ __all__ = [
     "MatelabErrorCategory",
     "MatelabProtocolError",
     "MatelabProviderError",
-    "MatelabProviderErrorKind",
     "MatelabTransportError",
     "MatelabUsageError",
     "NotebookCollection",

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/src/matelab/_transport.py

@@ -1,22 +1,23 @@
 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
 from matelab.errors import (
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -37,17 +38,32 @@ 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.")
     if code == 5:
         return MatelabAuthenticationError("Access token expired.")
-    kind = {
-        2: MatelabProviderErrorKind.REJECTED,
-        3: MatelabProviderErrorKind.SERVER,
-        4: MatelabProviderErrorKind.VALIDATION,
-    }.get(code, MatelabProviderErrorKind.UNKNOWN)
-    return MatelabProviderError(provider_message, kind=kind)
+    category = {
+        2: MatelabErrorCategory.BUSINESS,
+        3: MatelabErrorCategory.UPSTREAM,
+        4: MatelabErrorCategory.VALIDATION,
+    }.get(code, MatelabErrorCategory.UPSTREAM)
+    return MatelabProviderError(provider_message, category=category)
 
 
 class Encoding(StrEnum):
@@ -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)

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

@@ -9,6 +9,7 @@ from typing import IO, Literal, TypeAlias, cast
 from urllib.parse import parse_qs, unquote
 
 from pydantic import JsonValue
+from typing_extensions import override
 
 from matelab._generated import models as wire_models
 from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation
@@ -713,9 +714,8 @@ class _RichTextAttachmentParser(HTMLParser):
         super().__init__(convert_charrefs=True)
         self.attachments: list[_ParsedAttachment] = []
 
-    def handle_starttag(  # pyright: ignore[reportImplicitOverride]
-        self, tag: str, attrs: list[tuple[str, str | None]]
-    ) -> None:
+    @override
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         target_attribute = "src" if tag.casefold() == "img" else "href" if tag.casefold() == "a" else None
         if target_attribute is None:
             return
@@ -2595,26 +2595,22 @@ class Records:
         wire_html = html
         canonical_html = html
         for name, attachment in selected_attachments.items():
+            temporary_url = attachment._temporary_url  # pyright: ignore[reportPrivateUsage]
+            canonical_reference = attachment._canonical_reference  # pyright: ignore[reportPrivateUsage]
             if (
                 attachment.source != source
                 or attachment.temporary_file_id < 1
                 or not attachment.binding.uid
                 or len(attachment.binding.uid) > 45
-                or not attachment._temporary_url  # pyright: ignore[reportPrivateUsage]
-                or not attachment._canonical_reference  # pyright: ignore[reportPrivateUsage]
+                or not temporary_url
+                or not canonical_reference
                 or attachment.size < 0
                 or re.fullmatch(r"[0-9a-f]{64}", attachment.sha256) is None
             ):
                 raise MatelabUsageError("Staged comment attachment belongs to a different record.")
             marker = f"matelab-attachment:{name}"
-            wire_html = wire_html.replace(
-                marker,
-                attachment._temporary_url,  # pyright: ignore[reportPrivateUsage]
-            )
-            canonical_html = canonical_html.replace(
-                marker,
-                attachment._canonical_reference,  # pyright: ignore[reportPrivateUsage]
-            )
+            wire_html = wire_html.replace(marker, temporary_url)
+            canonical_html = canonical_html.replace(marker, canonical_reference)
         if _ATTACHMENT_MARKER_PATTERN.search(wire_html):
             raise MatelabUsageError("Comment content contains an unresolved attachment marker.")
         return wire_html.strip(), canonical_html.strip(), next(iter(binding_uids), "")

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

@@ -17,27 +17,12 @@ class MatelabError(Exception):
     retryable: bool = False
 
 
-class MatelabProviderErrorKind(StrEnum):
-    """Stable interpretation of a Provider error envelope."""
-
-    REJECTED = "rejected"
-    SERVER = "server"
-    VALIDATION = "validation"
-    UNKNOWN = "unknown"
-
-
 class MatelabProviderError(MatelabError):
     """The Provider returned a non-authentication error envelope."""
 
-    def __init__(self, message: str, *, kind: MatelabProviderErrorKind) -> None:
+    def __init__(self, message: str, *, category: MatelabErrorCategory) -> None:
         super().__init__(message)
-        self.kind = kind
-        self.category = {
-            MatelabProviderErrorKind.REJECTED: MatelabErrorCategory.BUSINESS,
-            MatelabProviderErrorKind.SERVER: MatelabErrorCategory.UPSTREAM,
-            MatelabProviderErrorKind.VALIDATION: MatelabErrorCategory.VALIDATION,
-            MatelabProviderErrorKind.UNKNOWN: MatelabErrorCategory.UPSTREAM,
-        }[kind]
+        self.category = category
 
 
 class MatelabAuthenticationError(MatelabError):

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/src/matelab/session.py

@@ -1,12 +1,10 @@
-from typing import ClassVar
-
 from pydantic import BaseModel, ConfigDict, Field
 
 
 class Token(BaseModel):
     """Immutable Provider token with a persistable value hidden only from representations."""
 
-    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid")
 
     value: str = Field(min_length=1, repr=False)
     expires_at_ms: int = Field(gt=0)
@@ -15,7 +13,7 @@ class Token(BaseModel):
 class Identity(BaseModel):
     """Immutable identity associated with a validated Matelab Session."""
 
-    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid")
 
     userid: int = Field(gt=0)
     username: str = Field(min_length=1)
@@ -25,7 +23,7 @@ class Identity(BaseModel):
 class Session(BaseModel):
     """Stable normalized snapshot of one client's Matelab authentication state."""
 
-    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True, extra="forbid")
+    model_config = ConfigDict(frozen=True, extra="forbid")
 
     access: Token
     refresh: Token

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_client.py

@@ -13,7 +13,6 @@ from matelab import (
     MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     Session,
     Token,
@@ -133,7 +132,7 @@ async def test_authenticate_does_not_expose_provider_error_body() -> None:
     rendered = str(caught.value)
     assert password not in rendered
     assert rendered == "Matelab request failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 
@@ -227,7 +226,7 @@ async def test_exchange_chat_sso_code_does_not_expose_provider_error_body() -> N
     assert code not in rendered
     assert key not in rendered
     assert rendered == "Matelab request failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "payload")
 
 
@@ -366,18 +365,18 @@ def test_session_models_reject_invalid_values_and_extra_fields() -> None:
 
 
 @pytest.mark.parametrize(
-    ("code", "kind", "category"),
+    ("code", "category"),
     [
-        (2, MatelabProviderErrorKind.REJECTED, MatelabErrorCategory.BUSINESS),
-        (3, MatelabProviderErrorKind.SERVER, MatelabErrorCategory.UPSTREAM),
-        (4, MatelabProviderErrorKind.VALIDATION, MatelabErrorCategory.VALIDATION),
-        (11, MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
-        (99, MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
+        (2, MatelabErrorCategory.BUSINESS),
+        (3, MatelabErrorCategory.UPSTREAM),
+        (4, MatelabErrorCategory.VALIDATION),
+        (11, MatelabErrorCategory.UPSTREAM),
+        (99, MatelabErrorCategory.UPSTREAM),
     ],
 )
 @pytest.mark.asyncio
 async def test_provider_error_codes_are_hidden_behind_stable_semantics(
-    code: int, kind: MatelabProviderErrorKind, category: MatelabErrorCategory
+    code: int, category: MatelabErrorCategory
 ) -> None:
     async def handler(_: Request) -> Response:
         return Response(200, json={"code": code, "msg": "rejected", "errcode": code, "errmsg": "rejected"})
@@ -388,7 +387,6 @@ async def test_provider_error_codes_are_hidden_behind_stable_semantics(
             _ = await client.authenticate("alice@example.org", "bad-password")
 
     assert isinstance(caught.value, MatelabError)
-    assert caught.value.kind is kind
     assert caught.value.category is category
     assert caught.value.retryable is False
     assert not hasattr(caught.value, "code")
@@ -422,9 +420,14 @@ async def test_injected_http_client_remains_open_when_sdk_closes() -> None:
 
 
 @pytest.mark.asyncio
-async def test_sdk_owned_http_client_closes_with_sdk() -> None:
+async def test_sdk_owned_http_client_closes_with_sdk(monkeypatch: pytest.MonkeyPatch) -> None:
+    owned_http_client = AsyncClient(base_url="https://matelab.example/api")
+
+    def build_http_client(**_: object) -> AsyncClient:
+        return owned_http_client
+
+    monkeypatch.setattr("matelab.client.AsyncClient", build_http_client)
     client = AsyncMatelab("https://matelab.example/api")
-    owned_http_client = client._http  # pyright: ignore[reportPrivateUsage]
 
     await client.aclose()
 

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_cloud_drive.py

@@ -12,9 +12,9 @@ from matelab import (
     CloudFile,
     CloudFileRef,
     CloudFolderRef,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     Session,
     StagedFile,
@@ -430,4 +430,4 @@ async def test_download_cloud_file_uses_identity_thumbnail_preview_and_range_str
                 CloudFileRef(cloud_file_id=501), thumbnail=True, preview=False, byte_range=ByteRange.between(1, 3)
             )
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS

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

@@ -1,17 +1,22 @@
 import pytest
 
+import matelab
 from matelab import (
     MatelabAuthenticationError,
     MatelabError,
     MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
 
 
+def test_provider_error_kind_is_not_part_of_public_interface() -> None:
+    assert "MatelabProviderErrorKind" not in matelab.__all__
+    assert not hasattr(matelab, "MatelabProviderErrorKind")
+
+
 def test_error_category_values_are_stable_for_integrations() -> None:
     assert {category.name: category.value for category in MatelabErrorCategory} == {
         "AUTHENTICATION": "authentication",
@@ -39,22 +44,19 @@ def test_public_errors_expose_integration_category_and_conservative_retryability
 
 
 @pytest.mark.parametrize(
-    ("kind", "category"),
+    "category",
     [
-        (MatelabProviderErrorKind.REJECTED, MatelabErrorCategory.BUSINESS),
-        (MatelabProviderErrorKind.SERVER, MatelabErrorCategory.UPSTREAM),
-        (MatelabProviderErrorKind.VALIDATION, MatelabErrorCategory.VALIDATION),
-        (MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
+        MatelabErrorCategory.BUSINESS,
+        MatelabErrorCategory.UPSTREAM,
+        MatelabErrorCategory.VALIDATION,
     ],
 )
-def test_provider_error_kind_is_diagnostic_and_category_is_integration_semantics(
-    kind: MatelabProviderErrorKind, category: MatelabErrorCategory
-) -> None:
-    error = MatelabProviderError("failure", kind=kind)
+def test_provider_error_exposes_final_integration_category(category: MatelabErrorCategory) -> None:
+    error = MatelabProviderError("failure", category=category)
 
-    assert error.kind is kind
     assert error.category is category
     assert error.retryable is False
+    assert not hasattr(error, "kind")
 
 
 def test_transport_error_preserves_http_status_without_changing_integration_semantics() -> None:

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_records.py

@@ -7,9 +7,9 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 from matelab import (
     AsyncMatelab,
     Identity,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabUsageError,
     NotebookRef,
     RecordLocator,
@@ -184,7 +184,7 @@ async def test_record_domain_classifies_provider_business_errors() -> None:
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await client.records.list(notebook=notebook)
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
 
 
 @pytest.mark.asyncio

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_release.py

@@ -21,7 +21,12 @@ _ROOT = Path(__file__).resolve().parents[1]
 _PYPROJECT = tomllib.loads((_ROOT / "pyproject.toml").read_text())
 _PROJECT = cast(dict[str, object], _PYPROJECT["project"])
 _RELEASE_VERSION = cast(str, _PROJECT["version"])
-_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 = {"LICENSE", "NOTICE"}
 
 
@@ -101,6 +106,15 @@ def test_release_version_has_one_runtime_source() -> None:
     assert all("__version__" not in path.read_text() for path in (_ROOT / "src" / "matelab").rglob("*.py"))
 
 
+def test_release_workflow_uses_python_specific_uv_cache_keys() -> None:
+    workflow = (_ROOT / ".github" / "workflows" / "release.yml").read_text()
+    test_job = workflow.partition("  test:")[2].partition("\n  build:")[0]
+    build_job = workflow.partition("  build:")[2].partition("\n  publish:")[0]
+
+    assert "          python-version: ${{ matrix.python-version }}" in test_job
+    assert '          python-version: "3.14"' in build_job
+
+
 def test_lockfile_mirrors_project_version() -> None:
     pyproject = tomllib.loads((_ROOT / "pyproject.toml").read_text())
     project = cast(dict[str, object], pyproject["project"])
@@ -124,6 +138,7 @@ def test_release_dependencies_publish_verified_compatibility_ranges() -> None:
         "httpx2>=2.9.1,<3",
         "jsonschema>=4.26,<5",
         "pydantic>=2.13.4,<3",
+        "typing-extensions>=4.14.1,<5",
     ]
     assert project["license"] == "Apache-2.0"
     assert project["license-files"] == ["LICENSE", "NOTICE"]

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_streaming.py

@@ -2,13 +2,14 @@ from collections.abc import AsyncIterator, Callable
 
 import pytest
 from httpx2 import AsyncByteStream, AsyncClient, MockTransport, ReadError, Request, Response
+from typing_extensions import override
 
 from matelab import (
     ByteRange,
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
     Session,
@@ -25,15 +26,18 @@ class _TrackingByteStream(AsyncByteStream):
         self._content = content
         self.closed = False
 
-    async def __aiter__(self) -> AsyncIterator[bytes]:  # pyright: ignore[reportImplicitOverride]
+    @override
+    async def __aiter__(self) -> AsyncIterator[bytes]:
         yield self._content
 
-    async def aclose(self) -> None:  # pyright: ignore[reportImplicitOverride]
+    @override
+    async def aclose(self) -> None:
         self.closed = True
 
 
 class _FailingByteStream(AsyncByteStream):
-    async def __aiter__(self) -> AsyncIterator[bytes]:  # pyright: ignore[reportImplicitOverride]
+    @override
+    async def __aiter__(self) -> AsyncIterator[bytes]:
         yield b"partial"
         raise ReadError("private transport details")
 
@@ -257,7 +261,7 @@ async def test_stream_classifies_json_error_without_exposing_response_body(provi
     assert _HASH not in rendered
     assert access_token not in rendered
     assert rendered == "Matelab download failed."
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_transport.py

@@ -1,19 +1,23 @@
 import asyncio
 import json
+import threading
 import time
 from collections.abc import AsyncIterator
 from io import BytesIO
+from pathlib import Path
+from typing import Literal
 
 import pytest
 from httpx2 import AsyncByteStream, AsyncClient, MockTransport, Request, Response
+from typing_extensions import override
 
 from matelab._generated.models import BasicSuccessResponse, RecordListResponse, TokenRefreshResponse
 from matelab._transport import Encoding, Operation, SessionTransport
 from matelab.errors import (
     MatelabAuthenticationError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
 )
@@ -21,10 +25,40 @@ from matelab.session import Identity, Session, Token
 
 
 class _InvalidGzipStream(AsyncByteStream):
-    async def __aiter__(self) -> AsyncIterator[bytes]:  # pyright: ignore[reportImplicitOverride]
+    @override
+    async def __aiter__(self) -> AsyncIterator[bytes]:
         yield b"not-gzip"
 
 
+class _LoopSensitiveFile(BytesIO):
+    def __init__(self, content: bytes, blocked_operation: Literal["read", "seek"]) -> None:
+        super().__init__(content)
+        self.blocked_operation = blocked_operation
+        self.operation_started = threading.Event()
+        self.event_loop_progress = threading.Event()
+        self.event_loop_progressed_while_blocked = False
+        self._blocked_once = False
+
+    def _block_once(self) -> None:
+        if self._blocked_once:
+            return
+        self._blocked_once = True
+        self.operation_started.set()
+        self.event_loop_progressed_while_blocked = self.event_loop_progress.wait(timeout=0.5)
+
+    @override
+    def read(self, size: int | None = -1, /) -> bytes:
+        if self.blocked_operation == "read":
+            self._block_once()
+        return super().read(size)
+
+    @override
+    def seek(self, pos: int, whence: int = 0, /) -> int:
+        if self.blocked_operation == "seek":
+            self._block_once()
+        return super().seek(pos, whence)
+
+
 def _session(
     *,
     access: str = "access",
@@ -39,8 +73,9 @@ def _session(
     )
 
 
+@pytest.mark.parametrize("code", [0, 10])
 @pytest.mark.asyncio
-async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> None:
+async def test_transport_accepts_each_success_code_only_when_declared_for_operation(code: int) -> None:
     async def handler(request: Request) -> Response:
         assert request.method == "POST"
         assert request.url.path == "/api/eln_api/items"
@@ -48,7 +83,8 @@ async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> N
         assert request.headers["Content-Type"] == "application/json"
         assert json.loads(request.content) == {"eln": "Example Notebook"}
         return Response(
-            200, json={"code": 10, "msg": "", "errcode": 10, "errmsg": "", "items": [], "subtypes": [], "trash_num": 0}
+            200,
+            json={"code": code, "msg": "", "errcode": code, "errmsg": "", "items": [], "subtypes": [], "trash_num": 0},
         )
 
     operation = Operation(
@@ -56,7 +92,7 @@ async def test_transport_uses_operation_encoding_bearer_and_success_codes() -> N
         path="/eln_api/items",
         encoding=Encoding.JSON,
         response_model=RecordListResponse,
-        success_codes=frozenset({0, 10}),
+        success_codes=frozenset({code}),
     )
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         transport = SessionTransport(http_client=http_client, session=_session())
@@ -104,7 +140,7 @@ async def test_transport_classifies_provider_business_errors() -> None:
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await transport.request(operation, payload={"eln": ""})
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
     assert not hasattr(caught.value, "code")
     assert not hasattr(caught.value, "payload")
 
@@ -308,6 +344,70 @@ async def test_transport_encodes_query_form_and_multipart_operations() -> None:
     assert seen_paths == ["/api/query", "/api/form", "/api/multipart", "/api/multipart-fields"]
 
 
+@pytest.mark.parametrize("blocked_operation", ["read", "seek"])
+@pytest.mark.asyncio
+async def test_transport_keeps_event_loop_responsive_while_reading_multipart_file(
+    blocked_operation: Literal["read", "seek"],
+) -> None:
+    content = _LoopSensitiveFile(b"contents", blocked_operation)
+
+    async def observe_blocked_file_operation() -> None:
+        while not content.operation_started.is_set():
+            await asyncio.sleep(0)
+        content.event_loop_progress.set()
+
+    async def handler(request: Request) -> Response:
+        assert b'filename="example.txt"' in request.content
+        assert b"\r\ncontents\r\n" in request.content
+        return Response(200, json={"code": 0, "msg": "", "errcode": 0, "errmsg": ""})
+
+    operation = Operation(
+        method="POST",
+        path="/multipart",
+        encoding=Encoding.MULTIPART,
+        response_model=BasicSuccessResponse,
+        success_codes=frozenset({0}),
+    )
+    observer = asyncio.create_task(observe_blocked_file_operation())
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        transport = SessionTransport(http_client=http_client, session=_session())
+        _ = await transport.request(
+            operation,
+            files={"file": ("example.txt", content, "text/plain")},
+        )
+    await observer
+
+    assert content.event_loop_progressed_while_blocked
+
+
+@pytest.mark.asyncio
+async def test_transport_uploads_regular_binary_file(tmp_path: Path) -> None:
+    path = tmp_path / "example.txt"
+    _ = path.write_bytes(b"contents")
+
+    async def handler(request: Request) -> Response:
+        assert request.headers["Content-Type"].startswith("multipart/form-data; boundary=")
+        assert int(request.headers["Content-Length"]) == len(request.content)
+        assert b'filename="example.txt"' in request.content
+        assert b"\r\ncontents\r\n" in request.content
+        return Response(200, json={"code": 0, "msg": "", "errcode": 0, "errmsg": ""})
+
+    operation = Operation(
+        method="POST",
+        path="/multipart",
+        encoding=Encoding.MULTIPART,
+        response_model=BasicSuccessResponse,
+        success_codes=frozenset({0}),
+    )
+    with path.open("rb") as content:
+        async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+            transport = SessionTransport(http_client=http_client, session=_session())
+            _ = await transport.request(
+                operation,
+                files={"file": (path.name, content, "text/plain")},
+            )
+
+
 @pytest.mark.asyncio
 async def test_transport_refreshes_access_inside_expiration_skew_before_request() -> None:
     paths: list[str] = []

{matelab_python_sdk-0.1.0a8 → matelab_python_sdk-0.1.0a10}/tests/test_users.py

@@ -5,9 +5,9 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 
 from matelab import (
     AsyncMatelab,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
-    MatelabProviderErrorKind,
     MatelabTransportError,
     MatelabUsageError,
     Session,
@@ -112,7 +112,7 @@ async def test_search_users_classifies_provider_business_errors(provider_session
         with pytest.raises(MatelabProviderError, match="Matelab request failed") as caught:
             _ = await client.users.search("Example")
 
-    assert caught.value.kind is MatelabProviderErrorKind.REJECTED
+    assert caught.value.category is MatelabErrorCategory.BUSINESS
 
 
 @pytest.mark.asyncio

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

@@ -2,6 +2,7 @@ from matelab import (
     AsyncMatelab,
     MatelabError,
     MatelabErrorCategory,
+    MatelabProviderError,
     NotebookCollection,
     NotebookRef,
     RecordAttachmentChange,
@@ -29,6 +30,10 @@ def consume_error(error: MatelabError) -> tuple[MatelabErrorCategory, bool]:
     return category, retryable
 
 
+def construct_provider_error(category: MatelabErrorCategory) -> MatelabProviderError:
+    return MatelabProviderError("failure", category=category)
+
+
 async def consume_public_types(client: AsyncMatelab) -> tuple[Session | None, NotebookCollection]:
     notebooks: NotebookCollection = await client.notebooks.list()
     session: Session | None = client.session

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

@@ -352,12 +352,13 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a8"
+version = "0.1.0a10"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },
     { name = "jsonschema" },
     { name = "pydantic" },
+    { name = "typing-extensions" },
 ]
 
 [package.dev-dependencies]
@@ -377,6 +378,7 @@ requires-dist = [
     { name = "httpx2", specifier = ">=2.9.1,<3" },
     { name = "jsonschema", specifier = ">=4.26,<5" },
     { name = "pydantic", specifier = ">=2.13.4,<3" },
+    { name = "typing-extensions", specifier = ">=4.14.1,<5" },
 ]
 
 [package.metadata.requires-dev]