matelab-python-sdk 0.1.0a22__tar.gz → 0.1.0a23__tar.gz

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/CHANGELOG.md

@@ -3,6 +3,12 @@
 This file records release-to-release changes and migration impact. It is not the authority for the current interface;
 see [README.md](README.md) for current behavior and [AGENTS.md](AGENTS.md) for maintenance policy.
 
+## 0.1.0a23 - 2026-09-04
+
+- Temporarily accepts `readRecord` table file attachments that contain valid `filename`, `hash`, and `size` fields but
+  omit the Contract-required `timestamp`. The SDK preserves the omission instead of synthesizing a timestamp; explicit
+  null timestamps and other malformed attachment values remain rejected.
+
 ## 0.1.0a22 - 2026-09-03
 
 - Adopts immutable `matelab-spec v0.4.5` at commit `6afac7ff151680130e6e4bc6d95782589b97f4e7` and OpenAPI

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a22
+Version: 0.1.0a23
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -35,7 +35,7 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a22`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a23`. `[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.5` Contract Release. The sole release pin is
@@ -64,7 +64,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.0a22-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a23-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -354,6 +354,12 @@ not accept a caption. Record reads likewise accept only one canonical attachment
 an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
 differ from the current occurrence.
 
+As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
+otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
+preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
+attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
+historical record content.
+
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
 must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/README.md

@@ -7,7 +7,7 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a22`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a23`. `[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.5` Contract Release. The sole release pin is
@@ -36,7 +36,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.0a22-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a23-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -326,6 +326,12 @@ not accept a caption. Record reads likewise accept only one canonical attachment
 an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
 differ from the current occurrence.
 
+As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
+otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
+preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
+attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
+historical record content.
+
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
 must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/pyproject.toml

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

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/src/matelab/domains/records.py

@@ -1,13 +1,14 @@
 import re
 import secrets
 from collections.abc import AsyncIterable, Iterable, Iterator, Mapping, Sequence
+from copy import deepcopy
 from dataclasses import dataclass, field
 from html.parser import HTMLParser
 from types import MappingProxyType
-from typing import IO, Literal, TypeAlias, cast
+from typing import IO, Literal, Self, TypeAlias, cast
 from urllib.parse import unquote
 
-from pydantic import BaseModel, JsonValue
+from pydantic import BaseModel, JsonValue, model_validator
 from typing_extensions import override
 
 from matelab._generated import models as wire_models
@@ -21,6 +22,56 @@ from matelab.domains.users import UserRef
 from matelab.errors import MatelabProtocolError, MatelabUsageError
 from matelab.streaming import ByteRange, DownloadStream
 
+_MISSING_TIMESTAMP_MARKER = "__matelab_missing_record_attachment_timestamp__"
+
+
+def _table_file_attachments(modules: JsonValue) -> Iterator[dict[str, JsonValue]]:
+    if not isinstance(modules, list):
+        return
+    for module in modules:
+        if not isinstance(module, dict) or module.get("type") != "table":
+            continue
+        columns = module.get("data")
+        if not isinstance(columns, list):
+            continue
+        for column in columns:
+            if not isinstance(column, dict) or column.get("type") != "file":
+                continue
+            values = column.get("data")
+            if not isinstance(values, list):
+                continue
+            for value in values:
+                if isinstance(value, dict):
+                    yield value
+
+
+class _ReadRecordResponse(wire_models.ItemViewResponse):
+    """Contain the Provider's temporary omission of stored attachment timestamps."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _allow_missing_attachment_timestamp(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        payload = deepcopy(cast(dict[str, JsonValue], value))
+        modules = payload.get("modules")
+        if modules is None:
+            return payload
+        for attachment in _table_file_attachments(modules):
+            if "timestamp" not in attachment and _MISSING_TIMESTAMP_MARKER not in attachment:
+                attachment["timestamp"] = 1
+                attachment[_MISSING_TIMESTAMP_MARKER] = True
+        return payload
+
+    @model_validator(mode="after")
+    def _restore_missing_attachment_timestamp(self) -> Self:
+        modules: JsonValue = [{"type": module.type, "data": cast(JsonValue, module.data)} for module in self.modules]
+        for attachment in _table_file_attachments(modules):
+            if attachment.pop(_MISSING_TIMESTAMP_MARKER, None) is True:
+                del attachment["timestamp"]
+        return self
+
+
 _LIST_RECORDS = Operation(
     method="POST",
     path="/eln_api/items",
@@ -68,7 +119,7 @@ _READ_RECORD = Operation(
     method="GET",
     path="/eln_items/item_view",
     encoding=Encoding.QUERY,
-    response_model=wire_models.ItemViewResponse,
+    response_model=_ReadRecordResponse,
     success_codes=frozenset({0}),
     retry_on_access_expired=True,
 )

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/tests/test_records.py

@@ -303,6 +303,77 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
     assert "74034dae" not in repr(record.attachments[0])
 
 
+@pytest.mark.asyncio
+async def test_read_tolerates_provider_table_attachment_without_timestamp() -> None:
+    payload = _item_view_payload(uid="REC-EXAMPLE-001")
+    attachment = {
+        "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+        "filename": "evidence.pdf",
+        "size": 34,
+    }
+    payload["modules"] = [
+        {
+            "type": "table",
+            "name": "Data sheet",
+            "rows": ["row-1"],
+            "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        }
+    ]
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    notebook = NotebookRef(notebook_id=23, title="Shared Example", owner_userid=202, scope="shared")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-EXAMPLE-001"))
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
+        record = await client.records.read(source)
+
+    assert record.modules[0] == {
+        "name": "Data sheet",
+        "type": "table",
+        "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        "language": None,
+        "style": None,
+        "rows": ["row-1"],
+    }
+    assert [(item.filename, item.size) for item in record.attachments] == [("evidence.pdf", 34)]
+
+
+@pytest.mark.parametrize("invalid_change", ["filename", "hash", "size", "null_timestamp"])
+@pytest.mark.asyncio
+async def test_read_timestamp_compatibility_does_not_relax_other_attachment_requirements(invalid_change: str) -> None:
+    payload = _item_view_payload(uid="REC-EXAMPLE-001")
+    attachment: dict[str, object] = {
+        "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+        "filename": "evidence.pdf",
+        "size": 34,
+        "timestamp": 1_767_946_200_000,
+    }
+    if invalid_change == "null_timestamp":
+        attachment["timestamp"] = None
+    else:
+        del attachment[invalid_change]
+    payload["modules"] = [
+        {
+            "type": "table",
+            "name": "Data sheet",
+            "rows": ["row-1"],
+            "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        }
+    ]
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    notebook = NotebookRef(notebook_id=23, title="Shared Example", owner_userid=202, scope="shared")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-EXAMPLE-001"))
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
+        with pytest.raises(MatelabProtocolError, match="does not match the Integration Contract"):
+            _ = await client.records.read(source)
+
+
 @pytest.mark.asyncio
 async def test_read_rejects_historical_table_attachment_array_at_public_boundary() -> None:
     payload = _item_view_payload(uid="REC-EXAMPLE-001")

{matelab_python_sdk-0.1.0a22 → matelab_python_sdk-0.1.0a23}/uv.lock

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