matelab-python-sdk 0.2.0a4__tar.gz → 0.2.0a5__tar.gz

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/CONTEXT.md

@@ -63,9 +63,14 @@ _Avoid_: Record locator, public record ref, deleted record ref
 
 **Record locator**:
 A record ref paired with the owned or shared notebook in which it was observed. It is the complete source identity
-used by record reads and record-scoped operations.
+used by owned/shared record reads and record-scoped operations.
 _Avoid_: Record ref, notebook ID
 
+**Public record ref**:
+A public association's row ID, paired source notebook and record IDs, and nullable association UID metadata.
+The source ID pair locates its current body; it does not grant notebook-wide access.
+_Avoid_: Record locator, public notebook ID, association ID as record ID
+
 **Record version ref**:
 A historical version ID bound to its record locator. It identifies observed historical content, not a separate active
 record.

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a4
+Version: 0.2.0a5
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.10.1",
-    "commit": "9941e2d623a1c2633adb459b823d78d4e62d3802"
+    "tag": "v2026.10.2",
+    "commit": "1183d6833d88a6904598357321ef2d30cf944339"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813"
+    "sha256": "4806fc2e4b4cb4cf94464be6f1b5f574f5a44745bf7cbc03d8644a13e57f8ec9"
   }
 }

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.10.1"
+  version: "2026.10.2"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -26,6 +26,7 @@ info:
       - controller/Eln.php
       - controller/Eln_api.php
       - controller/Eln_items.php
+      - controller/Eln_public.php
       - controller/Eln_template.php
       - controller/Eln_url.php
       - controller/Files.php
@@ -36,6 +37,7 @@ info:
       - model/FileQuoteModel.php
       - model/FilesModel.php
       - traits/ElnTrait.php
+      - traits/ElnPublicTrait.php
       - traits/RecommendTrait.php
       - service/ElnApiImport.php
       - service/ElnApiUpdate.php
@@ -53,7 +55,7 @@ info:
       - sql/recommend.sql
   x-provider-audit:
     currentCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
-    previousReleaseEvidenceCommit: acb0e12f2d62a8959ab9e9bddf38e34a67c19b48
+    previousReleaseEvidenceCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
     lastProviderVerifiedCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
@@ -62,36 +64,8 @@ info:
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
     incorporatedChanges:
-      - {operationId: readApplicationBootstrap, change: array-valued-query-token-rejected-as-missing-authentication}
-      - {operationId: updateRecordData, change: collaboration-source-restricted-to-same-notebook-record-web-peer}
-      - {operationId: readRecord, change: encrypted-modules-and-unresolved-user-fields-modeled}
-      - {operationId: listRecordComments, change: unresolved-author-descriptors-modeled}
-      - {operationId: listRecordRelations, change: unresolved-comment-author-descriptors-modeled}
-      - {operationId: updateRecordData, change: staged-files-folder-append-wired-into-request-and-base64-excluded}
-      - {operationId: importRecordDataset, change: unreachable-base64-file-input-excluded}
-      - {operationId: searchRecordData, change: fixed-result-field-aliases-reserved-and-extraction-path-constrained}
-      - {operationId: saveNotebookMetadata, change: decoded-list-display-requests-reject-null-uid-and-invalid-path}
-      - {operationId: updateRecordData, change: quote-extraction-path-constrained-and-collaboration-code-0-documented}
-      - {operationId: listNotebooks, change: stored-types-return-non-null-decoded-json}
-      - {operationId: extractLiteratureMetadata, change: nested-errors-and-opaque-array-results-modeled}
-      - {operationId: listCloudDriveFiles, change: unreachable-null-timestamp-success-removed}
-      - {operationId: downloadRecordAttachment, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadRecordCommentAttachment, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadLiteraturePdf, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadCloudDriveFile, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: listCurrentUserElnGroups, change: dangling-group-id-null-and-first-group-error-modeled}
-      - {operationId: downloadRecordCommentAttachment, change: zero-byte-attachment-download-supported}
-      - {operationId: listNotebookRecords, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: exportRecords, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: searchRecordData, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: listDeletedRecordPage, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: copyRecord, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: addRecordRelation, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: deleteRecordRelation, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: saveRecordComment, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: deleteRecordComment, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: downloadRecordAttachment, change: remote-data-server-download-excluded-pending-proxy-verification}
-      - {operationId: downloadRecordCommentAttachment, change: remote-data-server-download-excluded-pending-proxy-verification}
+      - {operationId: readRecord, change: public-only-body-access-and-source-record-identity-documented}
+      - {operationId: listPublicNotebookRecords, change: source-record-identifiers-distinguished-from-public-association-id}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -2054,6 +2028,17 @@ paths:
       operationId: listPublicNotebookRecords
       tags: [Records]
       summary: List records in a visible public notebook
+      description: |
+        Authentication is required even for a globally visible public directory.
+        `eln` is the public directory's name. Visibility comes from a global
+        directory (`eln_public.userid=0`) or the caller's directory membership;
+        owning or sharing the source notebook is not required.
+        To read an item's current body, call `readRecord` with query
+        `eln=items[n].eln_id&id=items[n].item_id&version=0`. The directory's own
+        id and each returned association `id` are different identities and must
+        not be substituted. `uid` is nullable association metadata, not a body
+        selector. An association can survive a missing source notebook or record;
+        listing it does not guarantee that its body can still be read.
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -2092,6 +2077,8 @@ paths:
                       - {id: 52, item_id: 9002, eln_id: 12, uid: null, title: null, comm: null, locked: false, eln_name: null, userid: null, username: null, email: null, owner: false}
                 error:
                   value: {code: 2, msg: Public notebook not found, errcode: 2, errmsg: Public notebook not found}
+                authenticationError:
+                  value: {code: 1, msg: Authentication required, errcode: 1, errmsg: Authentication required}
   /eln_items/items:
     get:
       operationId: listNotebookRecordPage
@@ -2676,19 +2663,37 @@ paths:
         operation uses query parameters. Reading records writes an audit-log entry;
         that incidental access logging does not turn the resource read into a
         mutation operation.
+        Public-record bodies use this same operation and `ItemViewResponse`.
+        After `listPublicNotebookRecords`, pass that item's `eln_id` as `eln` and
+        `item_id` as `id`; keep them paired and use `version=0` for current content.
+        Do not substitute the public directory id, the public association's `id`,
+        or its nullable `uid`.
+        Authentication is still required. For a caller with no source-notebook
+        owner/share grant, an exact `(eln_id, item_id)` association in a global
+        public directory or one they belong to grants record-level read access.
+        This does not grant ownership or access to other records in that notebook.
+        Global public access is read-only; a member directory can separately
+        grant editing through the association's `editable` setting.
+        `modules` contains the canonical body or the existing encrypted descriptor;
+        this endpoint does not decrypt it. The required `uid` field can be null
+        for historical content and is not needed to construct the body request.
+        Missing/invalid authentication returns business code 1; denied access or
+        an invalid current-record identity returns code 2, both over HTTP 200.
+        Historical reads must use a version from this record's own `modify_log`;
+        the Provider does not enforce historical-version ownership (PVD-005).
       security:
         - bearerAuth: []
       parameters:
         - name: eln
           in: query
           required: true
-          description: Notebook database identifier.
+          description: Source notebook database identifier; use PublicRecordItem.eln_id for a public record, not the public directory id.
           schema: {type: integer, minimum: 1}
           example: 12
         - name: id
           in: query
           required: true
-          description: Record database identifier.
+          description: Source record database identifier; use PublicRecordItem.item_id for a public record, not its association id or UID.
           schema: {type: integer, minimum: 1}
           example: 9001
         - name: version
@@ -2766,6 +2771,38 @@ paths:
                     template_show: ""
                     template_text: Calibration Template
                     template_intro: ""
+                public:
+                  summary: Current body for a public-only reader without source-notebook sharing
+                  value:
+                    code: 0
+                    msg: ""
+                    errcode: 0
+                    errmsg: ""
+                    title: Calibration Run
+                    keywords: [calibration]
+                    modules:
+                      - {type: richtext, name: Notes, uid: module-example, data: Sanitized content}
+                    template_id: 8
+                    datetime_modify: 1767946200000
+                    username: Example User
+                    modify_log: []
+                    uid: REC-EXAMPLE-001
+                    current_version: 0
+                    item_id: 9001
+                    datetime_locked: 0
+                    locked: false
+                    signs: []
+                    signed: false
+                    owner: false
+                    eln_text: Example Notebook
+                    eln_server: localhost
+                    eln_id: 12
+                    editable: false
+                    keyword_eln: [calibration]
+                    pdf_enable: true
+                    template_show: ""
+                    template_text: Calibration Template
+                    template_intro: ""
                 nullable:
                   summary: Historical record with nullable UID, user, template, and keywords
                   value:
@@ -2902,6 +2939,11 @@ paths:
                     msg: No operation permission
                     errcode: 2
                     errmsg: No operation permission
+                authenticationError:
+                  value: {code: 1, msg: Authentication required, errcode: 1, errmsg: Authentication required}
+                identityError:
+                  summary: Source notebook and record identifiers do not identify the same current record
+                  value: {code: 2, msg: Illegal operation, errcode: 2, errmsg: Illegal operation}
   /eln_url/eln:
     get:
       operationId: downloadRecordAttachment
@@ -5677,7 +5719,10 @@ components:
       type: object
       required: [eln]
       properties:
-        eln: {type: string, minLength: 1}
+        eln:
+          type: string
+          minLength: 1
+          description: Public directory name, not the source notebook name or numeric id.
       additionalProperties: false
     CreateRecordRequest:
       type: object
@@ -6214,10 +6259,21 @@ components:
       type: object
       required: [id, item_id, eln_id, uid, title, comm, locked, eln_name, userid, username, email, owner]
       properties:
-        id: {type: integer, minimum: 1}
-        item_id: {type: integer, minimum: 1}
-        eln_id: {type: integer, minimum: 1}
-        uid: {type: [string, "null"]}
+        id:
+          type: integer
+          minimum: 1
+          description: Public association row identifier; not the record id accepted by readRecord.
+        item_id:
+          type: integer
+          minimum: 1
+          description: Source record identifier; pass as readRecord query id together with this row's eln_id.
+        eln_id:
+          type: integer
+          minimum: 1
+          description: Source notebook identifier; pass as readRecord query eln, not the public directory id.
+        uid:
+          type: [string, "null"]
+          description: Nullable UID copied into the association; not required for the numeric readRecord selector.
         title: {type: [string, "null"]}
         comm: {type: [string, "null"]}
         locked: {type: boolean}

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/docs/api.md

@@ -5,13 +5,13 @@ See the [README](../README.md) for installation and quick start and [CONTEXT.md]
 
 ## Contract
 
-The SDK is pinned to the immutable `matelab-spec v2026.10.1` Contract Release. The sole pin,
+The SDK is pinned to the immutable `matelab-spec v2026.10.2` Contract Release. The sole pin,
 [contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
-`9941e2d623a1c2633adb459b823d78d4e62d3802`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
-`ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`.
+`1183d6833d88a6904598357321ef2d30cf944339`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `4806fc2e4b4cb4cf94464be6f1b5f574f5a44745bf7cbc03d8644a13e57f8ec9`. The annotated tag object is
+`4ea93c32637a8bcbea51cf6c6fb2da4c316a7134`.
 
-The Contract uses Provider source evidence from `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`; v2026.10.1 validation ran
+The Contract uses Provider source evidence from `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`; v2026.10.2 validation ran
 against an isolated test instance and does not establish production behavior. The Front Consumer evidence
 `0c985f5b6da8e8ef4627ca7065cea85e408ae981` informs cross-Consumer capability review but does not define the SDK interface.
 
@@ -65,7 +65,7 @@ callable Contract and raises `MatelabProtocolError` rather than assigning an err
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v2026.10.1 Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 record opaque array/object
+The pinned Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 record opaque array/object
 containers and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -556,6 +556,25 @@ Search and relation order remain unspecified, and no continuation token is inven
 directly. Remote data-server forwarding code `10` is rejected because only local data-server results are covered.
 `DeletedRecordPage` does not repeat its input notebook.
 
+Read a public entry's current body directly from its ref:
+
+```python
+notebooks = await client.notebooks.list()
+entries = await client.records.list_public(notebooks.public[0].ref)
+if entries:
+    record = await client.records.read_public(entries[0].ref)
+    modules = record.modules
+```
+
+`read_public()` returns `PublicRecord`, with the input `PublicRecordRef` as `source` and the same canonical `modules`
+and content metadata as a private read. It uses the paired source notebook and record IDs; the public association ID
+and its nullable, potentially stale UID do not select or validate the body. Authentication is required, and the Provider
+checks current access through a global directory or directory membership and writes a read audit entry (PVD-035).
+This grants no notebook-wide
+access. A listed association may outlive its source, and revoked access or a missing record raises a Provider error.
+Encrypted content remains in `encrypted_modules`, with empty plaintext `modules`. Public reads expose current content;
+historical-version and downloadable-attachment refs remain available through owned/shared record reads.
+
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v2026.10.1
+  release: v2026.10.2
   operation_count: 71
 
 operations:
@@ -429,7 +429,7 @@ operations:
     domain: records
     state: implemented
     stability: stable
-    public_interface: AsyncMatelab.records.read
+    public_interface: AsyncMatelab.records.read / AsyncMatelab.records.read_public
     known_issues: [PCG-005, PCG-012, PVD-035, PVD-005, PVD-044]
 
   - operation_id: downloadRecordAttachment

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a4"
+version = "0.2.0a5"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.11"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/src/matelab/__init__.py

@@ -41,6 +41,7 @@ from matelab.domains.records import (
     DeletedRecordSummary,
     EncryptedRecordModules,
     ExportedRecord,
+    PublicRecord,
     PublicRecordRef,
     PublicRecordSummary,
     Record,
@@ -145,6 +146,7 @@ __all__ = [
     "NotebookShareRef",
     "NotebookShares",
     "NotebookSummary",
+    "PublicRecord",
     "PublicRecordRef",
     "PublicRecordSummary",
     "PublicationAuthorCandidate",

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/src/matelab/_generated/models.py

@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "2026.10.1"
+OPENAPI_INFO_VERSION = "2026.10.2"
 
 
 class ResponseEnvelope(WireModel):
@@ -1433,6 +1433,9 @@ class DeleteNotebookShareRequest(WireModel):
 class PublicRecordListRequest(WireModel):
     model_config = ConfigDict(extra="forbid")
     eln: Annotated[str, Field(min_length=1)]
+    """
+    Public directory name, not the source notebook name or numeric id.
+    """
 
 
 class CreateRecordRequest(WireModel):
@@ -2047,9 +2050,21 @@ class DeleteRecordsRequest(WireModel):
 
 class PublicRecordItem(WireModel):
     id: Annotated[StrictInt, Field(ge=1)]
+    """
+    Public association row identifier; not the record id accepted by readRecord.
+    """
     item_id: Annotated[StrictInt, Field(ge=1)]
+    """
+    Source record identifier; pass as readRecord query id together with this row's eln_id.
+    """
     eln_id: Annotated[StrictInt, Field(ge=1)]
+    """
+    Source notebook identifier; pass as readRecord query eln, not the public directory id.
+    """
     uid: Annotated[str | None, Field(...)]
+    """
+    Nullable UID copied into the association; not required for the numeric readRecord selector.
+    """
     title: Annotated[str | None, Field(...)]
     comm: Annotated[str | None, Field(...)]
     locked: StrictBool

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/src/matelab/domains/records.py

@@ -320,6 +320,8 @@ class RecordSearchMatch:
 
 @dataclass(frozen=True, slots=True)
 class PublicRecordRef:
+    """Public association metadata with the paired source IDs used for body reads."""
+
     public_entry_id: int
     source_notebook_id: int
     source_record_id: int
@@ -587,6 +589,20 @@ class EncryptedRecordModules:
     extra: Mapping[str, JsonValue] = field(default_factory=dict[str, JsonValue], repr=False)
 
 
+@dataclass(frozen=True, slots=True)
+class PublicRecord:
+    """Current content read through a public record association."""
+
+    source: PublicRecordRef
+    title: str | None
+    keywords: tuple[str, ...] | None
+    modules: tuple[dict[str, JsonValue], ...]
+    template_id: int | None
+    modified_at_ms: int
+    author_name: str | None
+    encrypted_modules: EncryptedRecordModules | None = None
+
+
 @dataclass(frozen=True, slots=True)
 class Record:
     """Current or historical record content with safe attachment references."""
@@ -732,6 +748,18 @@ def _contains_native_attachment_reference(value: JsonValue) -> bool:
     return False
 
 
+def _record_modules(
+    response: wire_models.ItemViewResponse,
+) -> tuple[tuple[dict[str, JsonValue], ...], EncryptedRecordModules | None]:
+    if isinstance(response.modules, wire_models.EncryptedRecordModules):
+        return (), EncryptedRecordModules(
+            ciphertext=response.modules.data,
+            algorithm=response.modules.encrypt,
+            extra=MappingProxyType(cast(dict[str, JsonValue], response.modules.model_extra or {})),
+        )
+    return tuple(item.model_dump(mode="json") for item in response.modules), None
+
+
 def _record_attachment_refs(
     modules: Sequence[Mapping[str, JsonValue]], *, source: RecordLocator, version: RecordVersionRef | None
 ) -> tuple[RecordAttachmentRef, ...]:
@@ -1708,6 +1736,28 @@ class Records:
         )
         return await self._transport.stream(_DOWNLOAD_COMMENT_ATTACHMENT, payload=request, byte_range=byte_range)
 
+    async def read_public(self, source: PublicRecordRef) -> PublicRecord:
+        """Read current content using a public entry's source notebook and record IDs."""
+        request = validate_request(
+            wire_models.ReadRecordParametersQuery,
+            {"eln": source.source_notebook_id, "id": source.source_record_id, "version": 0},
+            "Public record source identity does not satisfy the Integration Contract.",
+        )
+        response = await self._transport.request(_READ_RECORD, payload=request)
+        modules, encrypted_modules = _record_modules(response)
+        return PublicRecord(
+            source=source,
+            title=response.title,
+            keywords=tuple(response.keywords) if response.keywords is not None else None,
+            modules=modules,
+            template_id=response.template_id,
+            modified_at_ms=response.datetime_modify,
+            author_name=response.username.root
+            if response.username is not None and isinstance(response.username.root, str)
+            else None,
+            encrypted_modules=encrypted_modules,
+        )
+
     async def read(self, source: RecordLocator | RecordVersionRef) -> Record:
         if isinstance(source, RecordVersionRef):
             version = source
@@ -1719,16 +1769,7 @@ class Records:
             record_source, version_id=version.version_id if version is not None else None
         )
 
-        encrypted_modules = None
-        if isinstance(response.modules, wire_models.EncryptedRecordModules):
-            encrypted_modules = EncryptedRecordModules(
-                ciphertext=response.modules.data,
-                algorithm=response.modules.encrypt,
-                extra=MappingProxyType(cast(dict[str, JsonValue], response.modules.model_extra or {})),
-            )
-            modules: tuple[dict[str, JsonValue], ...] = ()
-        else:
-            modules = tuple(item.model_dump(mode="json") for item in response.modules)
+        modules, encrypted_modules = _record_modules(response)
         return Record(
             source=record_source,
             version=version,

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/tests/test_records.py

@@ -7,9 +7,13 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 from matelab import (
     AsyncMatelab,
     Identity,
+    MatelabAuthenticationError,
+    MatelabError,
     MatelabProtocolError,
+    MatelabProviderError,
     MatelabUsageError,
     NotebookRef,
+    PublicRecordRef,
     RecordLocator,
     RecordRef,
     RecordValueUpdate,
@@ -127,6 +131,107 @@ async def test_list_records_omits_owned_defaults_and_accepts_empty_example() ->
     assert records.trash_count == 0
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("association_uid", [None, "outdated-association-uid"])
+async def test_read_public_record_uses_source_ids_and_maps_current_body(
+    association_uid: str | None,
+    contract_response_example: Callable[[str, str], dict[str, object]],
+    provider_session: Session,
+) -> None:
+    payload = contract_response_example("readRecord", "public")
+    payload["future_response_field"] = True
+    calls: list[Request] = []
+
+    async def handler(request: Request) -> Response:
+        calls.append(request)
+        assert request.method == "GET"
+        assert request.url.path == "/api/eln_items/item_view"
+        assert dict(request.url.params) == {"eln": "12", "id": "9001", "version": "0"}
+        assert request.headers["Authorization"] == "Bearer access"
+        assert request.content == b""
+        return Response(200, json=payload)
+
+    source = PublicRecordRef(
+        public_entry_id=51, source_notebook_id=12, source_record_id=9001, record_uid=association_uid
+    )
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        record = await client.records.read_public(source)
+
+    assert len(calls) == 1
+    assert record.source == source
+    assert record.title == "Calibration Run"
+    assert record.keywords == ("calibration",)
+    assert record.modules == (
+        {
+            "type": "richtext",
+            "name": "Notes",
+            "uid": "module-example",
+            "data": "Sanitized content",
+            "language": None,
+            "style": None,
+        },
+    )
+    assert record.template_id == 8
+    assert record.modified_at_ms == payload["datetime_modify"]
+    assert record.author_name == "Example User"
+    assert record.encrypted_modules is None
+
+
+@pytest.mark.asyncio
+async def test_read_public_record_preserves_encryption_and_nullable_metadata(
+    contract_response_example: Callable[[str, str], dict[str, object]], provider_session: Session
+) -> None:
+    payload = contract_response_example("readRecord", "public")
+    payload.update(
+        title=None,
+        keywords=None,
+        template_id=None,
+        username=None,
+        modules={"data": "opaque-ciphertext", "encrypt": "CBC", "future_field": {"version": 1}},
+    )
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    source = PublicRecordRef(public_entry_id=51, source_notebook_id=12, source_record_id=9001, record_uid=None)
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        record = await client.records.read_public(source)
+
+    assert record.title is None
+    assert record.keywords is None
+    assert record.template_id is None
+    assert record.author_name is None
+    assert record.modules == ()
+    descriptor = record.encrypted_modules
+    assert descriptor is not None
+    assert descriptor.ciphertext == "opaque-ciphertext"
+    assert descriptor.algorithm == "CBC"
+    assert descriptor.extra == {"future_field": {"version": 1}}
+    assert "opaque-ciphertext" not in repr(record)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("example", "error_type"), [("error", MatelabProviderError), ("authenticationError", MatelabAuthenticationError)]
+)
+async def test_read_public_record_raises_provider_errors(
+    example: str,
+    error_type: type[MatelabError],
+    contract_response_example: Callable[[str, str], dict[str, object]],
+    provider_session: Session,
+) -> None:
+    async def handler(_: Request) -> Response:
+        return Response(200, json=contract_response_example("readRecord", example))
+
+    source = PublicRecordRef(public_entry_id=51, source_notebook_id=12, source_record_id=9001, record_uid=None)
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(error_type):
+            _ = await client.records.read_public(source)
+
+
 @pytest.mark.asyncio
 async def test_read_current_record_maps_pinned_contract_success_example(
     contract_response_example: Callable[[str, str], dict[str, object]],

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/tests/typing/consumer.py

@@ -11,6 +11,8 @@ from matelab import (
     NotebookCollection,
     NotebookRef,
     PublicationMetadataCandidate,
+    PublicRecord,
+    PublicRecordSummary,
     Record,
     RecordAttachmentRef,
     RecordAttachmentReplacement,
@@ -94,6 +96,12 @@ async def consume_record(client: AsyncMatelab, source: RecordLocator) -> Record:
     return record
 
 
+async def consume_public_record(client: AsyncMatelab, notebook: NotebookRef) -> PublicRecord | None:
+    entries: tuple[PublicRecordSummary, ...] = await client.records.list_public(notebook)
+    record: PublicRecord | None = await client.records.read_public(entries[0].ref) if entries else None
+    return record
+
+
 async def consume_record_attachment_intents(
     client: AsyncMatelab,
     source: RecordLocator,

{matelab_python_sdk-0.2.0a4 → matelab_python_sdk-0.2.0a5}/uv.lock

@@ -362,7 +362,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.2.0a4"
+version = "0.2.0a5"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },