matelab-python-sdk 0.2.0a3__py3-none-any.whl → 0.2.0a5__py3-none-any.whl

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/_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/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.0a5.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: matelab-python-sdk
+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
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.13.1
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+# matelab-python-sdk
+
+Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add matelab-python-sdk
+```
+
+Or use `python -m pip install matelab-python-sdk`.
+
+## Quick start
+
+Replace the example credentials with your own:
+
+```python
+import asyncio
+
+from matelab import AsyncMatelab
+
+
+async def main() -> None:
+    async with AsyncMatelab() as client:
+        await client.authenticate("user@example.org", "password")
+        notebooks = await client.notebooks.list()
+        for notebook in notebooks.owned:
+            print(notebook.ref)
+
+
+asyncio.run(main())
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another API root as its first argument.
+
+## Documentation
+
+- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

{matelab_python_sdk-0.2.0a3.dist-info → matelab_python_sdk-0.2.0a5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-matelab/__init__.py,sha256=C3CXRwVFMfaeyb55jl-MsNJtyUURKfuvVNlb_0mLxwM,5055
+matelab/__init__.py,sha256=cJgzpDJiKJ9-XANRfRAjiRNoFVc3EovfxO-M2vu-HwU,5093
 matelab/_hashes.py,sha256=ImrLHx9wvcU6R-xGOrUCVDN_30sYA2UMn-NLwFrmFtU,163
 matelab/_transport.py,sha256=hdDxNsVnEYoZvhtkD4hQLzsVhlOTKsU4wvCdOpHVDuI,14863
 matelab/_wire_validation.py,sha256=Z_PpxwLS0S18kCC8ah6CmxUEjzvQ-iP8_XBOoQ46Wt4,4752
@@ -8,19 +8,19 @@ matelab/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 matelab/session.py,sha256=D8i9uyAt32-bADotS-Lrb7RpmWRNYNIkIpZUijTYvy4,899
 matelab/streaming.py,sha256=36epH2josWk87Ors_JY0YsjNmtiq3NZa2iB9djLmlnY,3792
 matelab/_generated/__init__.py,sha256=jmGbXLLe3JorsGU7OUdF8iKGewFMRqkCzgyFAw7C15w,79
-matelab/_generated/models.py,sha256=TzVbDt0NRx8R9i6GvRe5PVZpRKBgVDg5miKl6oNWKxc,168733
+matelab/_generated/models.py,sha256=U3SS83szvXoxBHfL8yMwYm5hKCZ52DOyhG_RuB8lmAA,169243
 matelab/domains/__init__.py,sha256=C34IWsGoCAwP7r6uYKJ79DJkToZyrZ4LWA87ufc1i0Q,65
 matelab/domains/_attachment_content.py,sha256=z26hwFpdgAk2x1w8EGe00XBLtJ3QFDX8BPS35Zc5SoE,1461
 matelab/domains/cloud_drive.py,sha256=EoqAYWvLVUfVOsic3g-TxsQEtAI3wTp5h0_vB79KpwY,10406
 matelab/domains/groups.py,sha256=H8-Da2WTm2Ui4m3Nr1bhMNMn7stbzbRa3EmpkTRmkBU,1300
 matelab/domains/literature.py,sha256=1KZPakc20ExorVV4gsBlcQJ9CspZY3KkdF77Z0WO5rk,27485
 matelab/domains/notebooks.py,sha256=_SvffaViECSEOkN5iwXtSv6El3fK2OYaR4RJvUCXfGk,13477
-matelab/domains/records.py,sha256=n-YfsBbGZOjj1j2keqjHyckHAJ6ZLfYB9J1bto__q9g,92322
+matelab/domains/records.py,sha256=AWWw1_Zb67t1pGfXIR9jhvmwgJZ2Ug9Bw-Hs3XcEpwg,93984
 matelab/domains/templates.py,sha256=AsnayIc72J9pPTgcFpo8IfaM2a2C-acL6k8sdRH3rt8,17386
 matelab/domains/uploads.py,sha256=J9YveZIHq03YQuWwRZwayP1-tz7cE0F17RIgWByLcvc,7368
 matelab/domains/users.py,sha256=ZhlLzC_AadwYqNqxQrqkUBgIUqL7MJ6FgMyxwq-az8s,1445
-matelab_python_sdk-0.2.0a3.dist-info/METADATA,sha256=wdiO0RLndPd6fjQHtHo7WfW63JYLQYtey1BiVvZ4yeo,1086
-matelab_python_sdk-0.2.0a3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-matelab_python_sdk-0.2.0a3.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-matelab_python_sdk-0.2.0a3.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
-matelab_python_sdk-0.2.0a3.dist-info/RECORD,,
+matelab_python_sdk-0.2.0a5.dist-info/METADATA,sha256=dcxCPmz1lx0uAD7ds1DgDHWF0zbltUv-Ox4GaIXwVos,2436
+matelab_python_sdk-0.2.0a5.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+matelab_python_sdk-0.2.0a5.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+matelab_python_sdk-0.2.0a5.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
+matelab_python_sdk-0.2.0a5.dist-info/RECORD,,

matelab_python_sdk-0.2.0a3.dist-info/METADATA

@@ -1,26 +0,0 @@
-Metadata-Version: 2.5
-Name: matelab-python-sdk
-Version: 0.2.0a3
-Summary: Reusable async Python client for the Matelab Integration Contract
-Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: httpx2<3,>=2.13.1
-Requires-Dist: jsonschema<5,>=4.26.0
-Requires-Dist: pydantic<3,>=2.13.5
-Requires-Dist: typing-extensions<5,>=4.16.0