matelab-python-sdk 0.1.0a12__tar.gz → 0.1.0a13__tar.gz

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0a13 - 2026-08-08
+
+- Breaking: `Identity.username` now removes surrounding whitespace and rejects values that become empty.
+- Keeps `ByteRange` typed through the transport adapter and closes the underlying HTTPX2 response when download reads
+  or iteration finish or fail, while retaining explicit `DownloadStream.aclose()` for deferred framework consumers.
+- Consolidates Provider session validation through the public `Session` models and simplifies private wire-rule and
+  token-refresh validation without changing the pinned Integration Contract.
+
 ## 0.1.0a12 - 2026-08-07
 
 - Breaking: removes `MatelabAttachmentValidationError`; local attachment size and checksum mismatches now use the

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a12
+Version: 0.1.0a13
 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.0a12`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a13`. `[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.4.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.0a12-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a13-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a12`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a13`. `[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.4.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.0a12-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a13-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/pyproject.toml

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

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/_transport.py

@@ -12,7 +12,6 @@ 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,
@@ -22,7 +21,7 @@ from matelab.errors import (
     MatelabUsageError,
 )
 from matelab.session import Session, Token
-from matelab.streaming import DownloadStream
+from matelab.streaming import ByteRange, DownloadStream
 
 WireResponse = TypeVar("WireResponse", bound=BaseModel)
 _ACCESS_EXPIRY_SKEW_MS = 30_000
@@ -152,12 +151,10 @@ class SessionTransport:
                 return session
             if session.refresh.expires_at_ms <= time.time_ns() // 1_000_000:
                 raise MatelabAuthenticationError("Matelab refresh token expired.")
-            request = validate_request(
-                wire_models.TokenRefreshRequest,
-                {"refresh_token": session.refresh.value},
-                "The Matelab refresh token is invalid.",
-                error_type=MatelabAuthenticationError,
-            )
+            try:
+                request = wire_models.TokenRefreshRequest.model_validate({"refresh_token": session.refresh.value})
+            except ValidationError:
+                raise MatelabAuthenticationError("The Matelab refresh token is invalid.") from None
             response = await self.request(_REFRESH_TOKENS, payload=request)
             self.session = Session(
                 access=Token(value=response.access.token, expires_at_ms=response.access.expiredAt),
@@ -266,15 +263,15 @@ class SessionTransport:
                 raise MatelabProtocolError("Matelab response does not match the Integration Contract.") from None
 
     async def stream(
-        self, operation: StreamOperation, *, payload: _Payload, range_header: str | None = None
+        self, operation: StreamOperation, *, payload: _Payload, byte_range: ByteRange | None = None
     ) -> DownloadStream:
         encoded_payload = _payload_mapping(payload)
         retry_access_expired = True
         while True:
             access_session = await self.session_for_request()
             headers = {"Authorization": f"Bearer {access_session.access.value}"}
-            if range_header is not None:
-                headers["Range"] = range_header
+            if byte_range is not None:
+                headers["Range"] = byte_range.to_header()
 
             request = self._http.build_request(
                 operation.method,

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/_wire_validation.py

@@ -8,7 +8,7 @@ from jsonschema.protocols import Validator
 from pydantic import BaseModel, JsonValue, ValidationError, model_validator
 from pydantic_core import PydanticCustomError
 
-from matelab.errors import MatelabAuthenticationError, MatelabUsageError
+from matelab.errors import MatelabUsageError
 
 _RUNTIME_RULES_KEY = "matelab-runtime-rules"
 JsonObject = dict[str, JsonValue]
@@ -20,23 +20,19 @@ def validate_request(
     model: type[ModelT],
     data: Mapping[str, WireValue],
     message: str,
-    *,
-    error_type: type[MatelabUsageError] | type[MatelabAuthenticationError] = MatelabUsageError,
 ) -> ModelT:
     """Validate caller input without exposing it in the public exception."""
     try:
         return model.model_validate(data)
     except ValidationError:
-        raise error_type(message) from None
+        raise MatelabUsageError(message) from None
 
 
 def encode_json_field(value: JsonValue, *, ensure_ascii: bool = True) -> str:
     return json.dumps(value, ensure_ascii=ensure_ascii, separators=(",", ":"))
 
 
-def _rules(extra: JsonObject | None) -> JsonObject | None:
-    if extra is None:
-        return None
+def _rules(extra: JsonObject) -> JsonObject | None:
     rules = extra.get(_RUNTIME_RULES_KEY)
     if rules is None:
         return None
@@ -64,7 +60,7 @@ class WireModel(BaseModel):
         data = cast(Mapping[str, WireValue], value)
 
         model_extra = cls.model_config.get("json_schema_extra")
-        model_rules = _rules(model_extra if isinstance(model_extra, dict) else None)
+        model_rules = _rules(model_extra) if isinstance(model_extra, dict) else None
         if model_rules is not None:
             _validate_schema(data, model_rules)
 
@@ -73,12 +69,12 @@ class WireModel(BaseModel):
             if key not in data:
                 continue
             extra = field.json_schema_extra
-            json_extra = extra if isinstance(extra, dict) else None
+            json_extra = extra if isinstance(extra, dict) else {}
             field_rules = _rules(json_extra)
             raw_value = data[key]
             if field_rules is not None:
                 _validate_schema(raw_value, field_rules)
-            content_schema = json_extra.get("contentSchema") if json_extra is not None else None
+            content_schema = json_extra.get("contentSchema")
             if isinstance(content_schema, dict):
                 if raw_value in (None, "") and not field.is_required():
                     continue

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/client.py

@@ -1,6 +1,7 @@
 from typing import Self
 
 from httpx2 import AsyncClient
+from pydantic import ValidationError
 
 from matelab._generated import models as wire_models
 from matelab._transport import Encoding, Operation, SessionTransport
@@ -39,17 +40,18 @@ _CHAT_SSO = Operation(
 def _session_from_wire(
     source: wire_models.TokenLoginResponse | wire_models.ChatSsoCodeExchangeResponse,
 ) -> Session:
-    if source.username is None or not source.username.strip():
-        raise MatelabProtocolError("Matelab returned an identity with an empty username.")
     if isinstance(source, wire_models.TokenLoginResponse):
         access, refresh = source.access, source.refresh
     else:
         access, refresh = source.token.access, source.token.refresh
-    return Session(
-        access=Token(value=access.token, expires_at_ms=access.expiredAt),
-        refresh=Token(value=refresh.token, expires_at_ms=refresh.expiredAt),
-        identity=Identity(userid=source.userid, username=source.username, email=source.email),
-    )
+    try:
+        return Session(
+            access=Token(value=access.token, expires_at_ms=access.expiredAt),
+            refresh=Token(value=refresh.token, expires_at_ms=refresh.expiredAt),
+            identity=Identity.model_validate(source, from_attributes=True),
+        )
+    except ValidationError:
+        raise MatelabProtocolError("Matelab returned invalid session data.") from None
 
 
 class AsyncMatelab:

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/domains/cloud_drive.py

@@ -332,6 +332,4 @@ class CloudDrive:
             {"id": file.cloud_file_id, "thumb": int(thumbnail), "c": int(preview)},
             "Cloud-drive file identity does not satisfy the Integration Contract.",
         )
-        return await self._transport.stream(
-            _DOWNLOAD_FILE, payload=request, range_header=byte_range.to_header() if byte_range is not None else None
-        )
+        return await self._transport.stream(_DOWNLOAD_FILE, payload=request, byte_range=byte_range)

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/domains/literature.py

@@ -718,9 +718,7 @@ class Literature:
             },
             "Literature PDF identity does not satisfy the Integration Contract.",
         )
-        return await self._transport.stream(
-            _DOWNLOAD_PDF, payload=request, range_header=byte_range.to_header() if byte_range is not None else None
-        )
+        return await self._transport.stream(_DOWNLOAD_PDF, payload=request, byte_range=byte_range)
 
     async def create(self, metadata: LiteratureMetadata, *, staged_pdf: StagedFile | None = None) -> None:
         """Create a literature item; the Provider acknowledgement contains no new item identity."""

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/domains/records.py

@@ -1921,7 +1921,7 @@ class Records:
         return await self._transport.stream(
             _DOWNLOAD_RECORD_ATTACHMENT,
             payload=request,
-            range_header=byte_range.to_header() if byte_range is not None else None,
+            byte_range=byte_range,
         )
 
     async def download_comment_attachment(
@@ -1947,7 +1947,7 @@ class Records:
         return await self._transport.stream(
             _DOWNLOAD_COMMENT_ATTACHMENT,
             payload=request,
-            range_header=byte_range.to_header() if byte_range is not None else None,
+            byte_range=byte_range,
         )
 
     async def read(

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/session.py

@@ -1,4 +1,6 @@
-from pydantic import BaseModel, ConfigDict, Field
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
 
 
 class Token(BaseModel):
@@ -16,7 +18,7 @@ class Identity(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
     userid: int = Field(gt=0)
-    username: str = Field(min_length=1)
+    username: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
     email: str | None
 
 

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/src/matelab/streaming.py

@@ -1,5 +1,5 @@
 from collections.abc import AsyncIterator
-from contextlib import suppress
+from contextlib import aclosing
 from dataclasses import dataclass
 from typing import Self
 
@@ -75,19 +75,17 @@ class DownloadStream:
 
     async def aiter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
         try:
-            async for chunk in self._response.aiter_bytes(chunk_size):
-                yield chunk
+            async with aclosing(self._response) as response:
+                async for chunk in response.aiter_bytes(chunk_size):
+                    yield chunk
         except RequestError:
-            with suppress(MatelabTransportError):
-                await self.aclose()
             raise MatelabTransportError("Could not read data from the Matelab Provider.") from None
 
     async def read(self) -> bytes:
         try:
-            return await self._response.aread()
+            async with aclosing(self._response) as response:
+                return await response.aread()
         except RequestError:
-            with suppress(MatelabTransportError):
-                await self.aclose()
             raise MatelabTransportError("Could not read data from the Matelab Provider.") from None
 
     async def aclose(self) -> None:

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/tests/test_client.py

@@ -169,7 +169,7 @@ async def test_authenticate_rejects_empty_provider_username(username: str | None
 
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         client = AsyncMatelab("https://ignored.example", session=existing_session, http_client=http_client)
-        with pytest.raises(MatelabProtocolError, match="empty username"):
+        with pytest.raises(MatelabProtocolError, match="invalid session data"):
             _ = await client.authenticate("alice@example.org", "password")
 
     assert client.session is existing_session
@@ -297,12 +297,13 @@ def test_session_models_validate_values_and_extra_fields() -> None:
         _ = Token(value="access", expires_at_ms=0)
     with pytest.raises(ValidationError, match="greater_than"):
         _ = Identity(userid=0, username="User", email=None)
-    with pytest.raises(ValidationError, match="string_too_short"):
-        _ = Identity(userid=1, username="", email=None)
+    for username in ("", "   "):
+        with pytest.raises(ValidationError, match="string_too_short"):
+            _ = Identity(userid=1, username=username, email=None)
     with pytest.raises(ValidationError, match="extra_forbidden"):
         _ = Session.model_validate({**_session().model_dump(), "schema_version": 1})
     identity = Identity(userid=1, username=" Example User ", email=None)
-    assert identity.username == " Example User "
+    assert identity.username == "Example User"
     assert Identity.model_json_schema()["properties"]["username"]["minLength"] == 1
 
 

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/tests/test_streaming.py

@@ -97,7 +97,7 @@ async def test_stream_returns_lazy_binary_response_and_closes_on_context_exit(pr
 
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         transport = SessionTransport(http_client=http_client, session=provider_session)
-        stream = await transport.stream(_DOWNLOAD, payload={"h": _HASH}, range_header="bytes=0-")
+        stream = await transport.stream(_DOWNLOAD, payload={"h": _HASH}, byte_range=ByteRange.from_start(0))
         assert stream.status_code == 200
         assert stream.content_type == "application/octet-stream"
         assert stream.content_length == 16
@@ -175,7 +175,7 @@ async def test_stream_validates_and_exposes_partial_response_metadata(provider_s
 
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         stream = await SessionTransport(http_client=http_client, session=provider_session).stream(
-            _DOWNLOAD, payload={"h": _HASH}, range_header="bytes=1-4"
+            _DOWNLOAD, payload={"h": _HASH}, byte_range=ByteRange.between(1, 4)
         )
         async with stream:
             assert await stream.read() == b"part"

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a13}/uv.lock

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