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

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

@@ -1,5 +1,12 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a9
+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.0a9`. `[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.0a9-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
@@ -628,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.0a9 → 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.0a9`. `[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.0a9-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
@@ -601,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.0a9 → matelab_python_sdk-0.1.0a10}/pyproject.toml

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

{matelab_python_sdk-0.1.0a9 → 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.0a9 → 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.0a9 → matelab_python_sdk-0.1.0a10}/tests/test_client.py

@@ -420,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.0a9 → 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"}
 
 
@@ -133,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.0a9 → matelab_python_sdk-0.1.0a10}/tests/test_streaming.py

@@ -2,6 +2,7 @@ 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,
@@ -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")
 

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

@@ -1,11 +1,15 @@
 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
@@ -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",
@@ -310,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.0a9 → matelab_python_sdk-0.1.0a10}/uv.lock

@@ -352,12 +352,13 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a9"
+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]