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

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.0a14 - 2026-08-10
+
+- Adds immutable semantic template modules, editable `TemplateDocument` values, ordered name-based patch intents,
+  stable content fingerprints, and `Templates.read_document()`, `save_document()`, and `patch_content()` while
+  retaining the low-level `TemplateModule`, `read()`, and `save_content()` interface.
+
+## 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.0a14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a12
+Version: 0.1.0a14
 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.0a14`. `[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.0a14-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -450,6 +450,52 @@ market = await client.templates.search_market("calibration", page=1, page_size=2
 modules = await client.templates.read(templates.owned[0].ref)
 ```
 
+Semantic template documents hide canonical `uid`, `width`, `data`, `rows`, `folders`, and option encoding:
+
+```python
+from matelab import (
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFormField,
+    TemplateFormModule,
+    TemplatePatch,
+    TemplateRichTextModule,
+)
+
+document = TemplateDocument.create(
+    (
+        TemplateFormModule(
+            name="Basic",
+            fields=(TemplateFormField(name="Temperature", field_type="number", required=True, unit="K"),),
+        ),
+        TemplateRichTextModule(name="Notes", content="<p>Instructions</p>"),
+    )
+)
+template = await client.templates.create(title="Measurement")
+await client.templates.save_document(template, document)
+
+observed = await client.templates.read_document(template)
+await client.templates.patch_content(
+    template,
+    TemplatePatch(
+        changes=(
+            TemplateFieldAdd(
+                module="Basic",
+                field=TemplateFormField(name="Operator", field_type="text", required=True),
+            ),
+        )
+    ),
+    expected_fingerprint=observed.fingerprint,
+)
+updated = await client.templates.read_document(template)
+```
+
+`TemplateDocument` is immutable at its interface, preserves unknown canonical properties, keeps existing UIDs stable,
+and converts losslessly back to `TemplateModule`. Patches are ordered name-based intents and reject missing, duplicate,
+or incompatible targets before saving. The fingerprint preflight detects a stale prior read, but is client-side only:
+the current Provider has no atomic template patch or CAS (PCG-007). `patch_content()` returns `None`; explicitly
+re-read before using a new fingerprint because the mutation response contains no saved representation.
+
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
 value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a14}/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.0a14`. `[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.0a14-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -422,6 +422,52 @@ market = await client.templates.search_market("calibration", page=1, page_size=2
 modules = await client.templates.read(templates.owned[0].ref)
 ```
 
+Semantic template documents hide canonical `uid`, `width`, `data`, `rows`, `folders`, and option encoding:
+
+```python
+from matelab import (
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFormField,
+    TemplateFormModule,
+    TemplatePatch,
+    TemplateRichTextModule,
+)
+
+document = TemplateDocument.create(
+    (
+        TemplateFormModule(
+            name="Basic",
+            fields=(TemplateFormField(name="Temperature", field_type="number", required=True, unit="K"),),
+        ),
+        TemplateRichTextModule(name="Notes", content="<p>Instructions</p>"),
+    )
+)
+template = await client.templates.create(title="Measurement")
+await client.templates.save_document(template, document)
+
+observed = await client.templates.read_document(template)
+await client.templates.patch_content(
+    template,
+    TemplatePatch(
+        changes=(
+            TemplateFieldAdd(
+                module="Basic",
+                field=TemplateFormField(name="Operator", field_type="text", required=True),
+            ),
+        )
+    ),
+    expected_fingerprint=observed.fingerprint,
+)
+updated = await client.templates.read_document(template)
+```
+
+`TemplateDocument` is immutable at its interface, preserves unknown canonical properties, keeps existing UIDs stable,
+and converts losslessly back to `TemplateModule`. Patches are ordered name-based intents and reject missing, duplicate,
+or incompatible targets before saving. The fingerprint preflight detects a stale prior read, but is client-side only:
+the current Provider has no atomic template patch or CAS (PCG-007). `patch_content()` returns `None`; explicitly
+re-read before using a new fingerprint because the mutation response contains no saved representation.
+
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
 value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain

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

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

@@ -99,13 +99,38 @@ from matelab.domains.records import (
     StagedRecordAttachment,
     StagedRecordCommentAttachment,
 )
+from matelab.domains.template_documents import (
+    TemplateChange,
+    TemplateCodeLanguage,
+    TemplateCodeModule,
+    TemplateCodeStyle,
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFieldRemove,
+    TemplateFieldRename,
+    TemplateFieldUpdate,
+    TemplateFilesModule,
+    TemplateFormField,
+    TemplateFormFieldType,
+    TemplateFormModule,
+    TemplateModule,
+    TemplateModuleAdd,
+    TemplateModuleContentUpdate,
+    TemplateModuleDefinition,
+    TemplateModuleRemove,
+    TemplateModuleRename,
+    TemplatePatch,
+    TemplateRichTextModule,
+    TemplateTableColumn,
+    TemplateTableColumnType,
+    TemplateTableModule,
+)
 from matelab.domains.templates import (
     TemplateCollection,
     TemplateLibraryEntryRef,
     TemplateLibraryRelationKind,
     TemplateMarketEntry,
     TemplateMarketPage,
-    TemplateModule,
     TemplateRef,
     TemplateSource,
     TemplateSummary,
@@ -235,15 +260,38 @@ __all__ = [
     "StagedRecordAttachment",
     "StagedRecordCommentAttachment",
     "StagedUploadSession",
+    "TemplateChange",
+    "TemplateCodeLanguage",
+    "TemplateCodeModule",
+    "TemplateCodeStyle",
     "TemplateCollection",
+    "TemplateDocument",
+    "TemplateFieldAdd",
+    "TemplateFieldRemove",
+    "TemplateFieldRename",
+    "TemplateFieldUpdate",
+    "TemplateFilesModule",
+    "TemplateFormField",
+    "TemplateFormFieldType",
+    "TemplateFormModule",
     "TemplateLibraryEntryRef",
     "TemplateLibraryRelationKind",
     "TemplateMarketEntry",
     "TemplateMarketPage",
     "TemplateModule",
+    "TemplateModuleAdd",
+    "TemplateModuleContentUpdate",
+    "TemplateModuleDefinition",
+    "TemplateModuleRemove",
+    "TemplateModuleRename",
+    "TemplatePatch",
     "TemplateRef",
+    "TemplateRichTextModule",
     "TemplateSource",
     "TemplateSummary",
+    "TemplateTableColumn",
+    "TemplateTableColumnType",
+    "TemplateTableModule",
     "Token",
     "UploadBindingRef",
     "UserRef",

{matelab_python_sdk-0.1.0a12 → matelab_python_sdk-0.1.0a14}/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.0a14}/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.0a14}/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.0a14}/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.0a14}/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.0a14}/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(