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

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

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

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

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

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