matelab-python-sdk 0.1.0a3__tar.gz → 0.1.0a5__tar.gz

matelab_python_sdk-0.1.0a5/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.1.0a5 - 2026-07-29
+
+- Adopts immutable `matelab-spec v0.1.2` at commit `6dd674ac001ae61197495ace5eba489d585cb825` and OpenAPI
+  SHA-256 `7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.
+- Adds notebook-scoped staged finalizers for a null table file cell, an attachment-bearing appended table row,
+  files-module root append, and table/files occurrence replacement, with exact provenance, one-shot transport, and
+  canonical readback checks.
+- Adds typed intents for an empty file table column and complete form file-field/table file-column deletion.
+- Allows `records.update(..., module_deletions=...)` to delete a canonical module even when the current record read
+  observes attachments in it, verifies absence on persisted readback, and does not claim attachment-quote or byte
+  cleanup beyond the pinned Contract.
+- Rejects cross-scope staged attachment handles before the record read, preserving the public static types while
+  avoiding the Provider's read-audit side effect for invalid runtime input.
+- Keeps notebook-staged rich-text binding and attachment-bearing multi-record import explicitly unsupported because
+  v0.1.2 Provider Verification does not provide safe one-shot semantics for either.
+
+## 0.1.0a4 - 2026-07-28
+
+- Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing
+  domain values instead of request-shaped wrapper dataclasses.
+- Centralizes safe request-model validation, strengthens generated Contract constraints, and preserves structured field
+  diagnostics without exposing credentials, tokens, or sensitive payload values.
+- Tightens Session replacement, refresh races, multipart retry safety, streaming cleanup, and exact HTTP success
+  handling while retaining stable transport, authentication, Provider, protocol, usage, and verification errors.
+- Collects all business capabilities under `matelab.domains`, keeps client/session/error/transport primitives at the
+  package root, and hardens generation and release-artifact audits.
+
+## 0.1.0a3 - 2026-07-28
+
+- Replaces HTTPX with HTTPX2 2.9.1 and raises the Pydantic compatibility floor to 2.13.4. Injected clients must now
+  be `httpx2.AsyncClient` instances; HTTPX and HTTPX2 objects are not interchangeable. Default TLS verification now
+  uses the operating system trust store.
+- Shrinks the alpha public surface from 184 to 150 symbols by returning existing domain values, tuples, booleans, or
+  `None` from simple mutations instead of defining endpoint-shaped result dataclasses. Contract invariants remain
+  documented operation semantics rather than repeated constant fields.
+- Reorganizes the record and literature implementations into domain packages and keeps generated wire imports behind
+  one private namespace without changing the generated-model boundary.
+- Aligns the opt-in SDK Provider smoke with the isolated test service's shared `MATELAB_PROVIDER_*` environment
+  variables and adds a safe `.env.example`.
+
+## 0.1.0a2 - 2026-07-27
+
+- Adopts the immutable `matelab-spec v0.1.1` release.
+- Adds notebook-scoped, uploader-bound record attachment staging before a target record exists.
+- Finalizes staged attachments through a single-record import or one new form-file-field update without exposing
+  Provider-native attachment syntax or private transport details.
+- Enforces exact notebook/user provenance and one finalization attempt per staged handle in one SDK client.
+
+## 0.1.0a1 - 2026-07-27
+
+First public alpha candidate of the asynchronous Matelab Integration Contract SDK.
+
+- Binds the immutable `matelab-spec v0.1.0` release.
+- Exposes all 71 pinned Contract operations through public domain interfaces: 15 are stable and 56 remain
+  experimental.
+- Provides instance-owned immutable Sessions, bounded token refresh, typed public models, streaming downloads,
+  and generated private wire validation.
+- Ships as a typed package for Python 3.11 through 3.14.
+- Uses the Apache License 2.0 with PEP 639 package metadata.

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a3
+Version: 0.1.0a5
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -28,10 +28,10 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a3`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a5`. `[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.1.1` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.2` Contract Release. The sole release pin is
 `contracts/matelab-integration-v1.lock.json`, which records
 the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
 
@@ -57,7 +57,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.0a3-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a5-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -82,6 +82,24 @@ async with AsyncMatelab() as client:
 `AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
 explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.
 
+### Error handling
+
+Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
+
+| Error | Meaning and normal response |
+|---|---|
+| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
+| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
+| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. |
+| `MatelabVerificationError` | A mutation was acknowledged but its readback failed; the mutation may already have persisted. |
+
+`code`, `status_code`, and the sanitized `payload` are diagnostics. The `payload` shape may contain private wire
+field names and is not a stable Consumer interface; application control flow should use the exception class and
+documented scalar attributes. Never automatically retry a mutation solely because it raised a transport or
+verification error.
+
 ### Session ownership
 
 Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
@@ -176,7 +194,7 @@ notebook selector used for upload:
 ```python
 import hashlib
 
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 content = b"measurement data"
 staged = await client.records.stage_attachment(
@@ -188,7 +206,8 @@ staged = await client.records.stage_attachment(
 )
 result = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=(
         RecordImportItem(
             record_uid="REC-IMPORT-001",
@@ -199,38 +218,163 @@ result = await client.records.import_dataset(
 )
 ```
 
-The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
-module:
+The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
+existing form module:
 
 ```python
-from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+from matelab import RecordFormAttachmentFieldAddition
 
 # Alternative to the import above; do not run both with the same staged handle.
 result = await client.records.update(
     source,
-    RecordPatch(
-        attachment_changes=(
-            RecordFormAttachmentFieldAddition(
-                module="Attachments",
-                name="Measurement",
-                attachment=staged,
-            ),
-        )
+    attachment_changes=(
+        RecordFormAttachmentFieldAddition(
+            module="Attachments",
+            name="Measurement",
+            attachment=staged,
+        ),
     ),
 )
 ```
 
-Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
-operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
-attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
-and a second finalization attempt through the same client. A Session imported without identity must first call
-`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
-guarantee, so callers must discard the handle as soon as a finalization request starts.
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update operation;
+do not reuse it after transport starts, even when the Provider outcome is unknown. A locally rejected target or
+argument does not spend the handle. The SDK rejects raw Provider attachment references, cross-user or cross-notebook
+handles, unsafe combinations, duplicate use in one request, and a second finalization attempt through the same
+client. A Session imported without identity must first call `await client.resolve_identity()`.
+
+The Provider supplies no staging status, abort, TTL, atomicity, idempotency, or retry guarantee. Integrations that
+persist handles must durably claim their own `uploaded -> finalizing/indeterminate` transition before calling a
+finalizer.
+
+### Attachment-bearing record update boundary
+
+The v0.1.2 Contract adds dedicated, verified notebook-staged update shapes. They remain public intent objects; callers
+never construct Provider paths or attachment strings:
+
+```python
+from matelab import (
+    RecordFilesAttachmentRootAppend,
+    RecordTableFileCellSet,
+    RecordTableRowAttachmentAppend,
+)
+
+# Each example is a separate finalizer; never run several with the same handle.
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableFileCellSet(
+            table="Measurements",
+            column="Evidence",
+            row=0,
+            attachment=staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableRowAttachmentAppend(
+            table="Measurements",
+            file_column="Evidence",
+            values={"Label": "Sample C"},
+            attachment=another_staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordFilesAttachmentRootAppend(
+            module="Files",
+            caption="Evidence",
+            attachment=third_staged,
+        ),
+    ),
+)
+```
+
+`RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
+`null`. The row-append intent addresses the new row by the row count from the SDK's immediate read and supports one
+staged file column. Files append is root-only and requires a string caption.
+
+Replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
+`RecordAttachmentRef`:
+
+```python
+from matelab import RecordFilesAttachmentReplacement
+
+record = await client.records.read(notebook=source.notebook, record=source.record)
+existing = next(
+    attachment
+    for attachment in record.attachments
+    if attachment.location is not None and attachment.location.kind == "files_module"
+)
+await client.records.update(
+    source,
+    attachment_changes=(RecordFilesAttachmentReplacement(existing=existing, replacement=staged, caption=None),),
+)
+```
+
+For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
+the required empty string). Canonical readback must preserve the Provider `uid` and folder. Table replacement requires
+exactly one current attachment in the selected cell and uses `RecordTableFileAttachmentReplacement`. Both replacement
+forms require the new hash to differ.
+
+Row/index-based finalizers 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. `expected_content_sha256` is only a client-side prewrite
+check, not Provider compare-and-swap.
+
+File-bearing structure changes do not consume staging:
+
+```python
+from matelab import (
+    RecordFormFileFieldDeletion,
+    RecordTableFileColumnAddition,
+    RecordTableFileColumnDeletion,
+)
+
+await client.records.update(
+    source,
+    file_structure_changes=(
+        RecordTableFileColumnAddition(table="Measurements", name="Additional evidence"),
+        RecordFormFileFieldDeletion(form="Attachments", name="Obsolete evidence"),
+        RecordTableFileColumnDeletion(table="Measurements", name="Old evidence"),
+    ),
+)
+```
+
+The SDK emits the v0.1.2 dedicated operations: a new file column omits wire `data` and must read back as `null` for
+every existing row; whole form-field/table-column deletion uses a strict two-segment target. It does not expose a
+three-segment delete as table-cell clearing.
+
+Deleting a complete canonical module is also supported even when the current read observes attachments in it:
+
+```python
+result = await client.records.update(
+    source,
+    module_deletions=("Raw files",),
+    expected_content_sha256=record.content_sha256,
+)
+```
+
+This requests only a canonical record-content mutation. Readback proves the module is absent; it does not prove
+attachment-quote cleanup or byte deletion. Collaboration-pending has no readback and is not reported as persisted.
+
+Notebook-staged rich-text binding remains unsupported. Provider Verification shows that `#file{name}` is stored as
+plain text and that a hash-based URI can fall back to an existing quote, so neither is a one-shot staged finalizer.
+Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
+multi-record import is also forbidden; callers must split it into single-record finalizers.
+
+See `docs/attachment-write-contract-gaps.md` in the source repository for the exact support matrix, integration
+lifecycle requirements, and minimum Contract changes needed to expose the remaining operations.
 
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.2` operations to ordered work packages, defines the machine-readable coverage that
 must be added, records Provider-risk gates, and specifies the final completion checks.
 
 The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
@@ -295,11 +439,9 @@ Provider returns members for an unstable first group and user search is unpaged,
 Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:
 
 ```python
-from matelab import NotebookMetadata, NotebookSharePermissionGrant
-
-await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(title="Example Notebook")
 shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
+updated = await client.notebooks.update_share(shares[0].ref, write=True, create=True)
 ```
 
 Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
@@ -314,7 +456,7 @@ relation identities:
 ```python
 templates = await client.templates.list()
 market = await client.templates.search_market("calibration", page=1, page_size=20)
-content = await client.templates.read(templates.owned[0].ref)
+modules = await client.templates.read(templates.owned[0].ref)
 ```
 
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
@@ -334,12 +476,10 @@ limitations are documented operation semantics rather than constant fields on ev
 Extended record reads stay behind the same `records` interface:
 
 ```python
-from matelab import RecordFieldExtraction, RecordLocator
+from matelab import RecordLocator
 
 exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
-matches = await client.records.search(
-    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
-)
+matches = await client.records.search(notebooks=[notebook], extractions={"notes": ("Notes",)})
 page = await client.records.page(notebook)
 deleted = await client.records.recycle_bin(notebook)
 relations = await client.records.relations(notebook=notebook, record=record)
@@ -354,12 +494,13 @@ remain unspecified, and no continuation token is invented.
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
 imported = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
 )
 ```
@@ -397,7 +538,7 @@ Attachment bytes are streamed and must be consumed or closed explicitly:
 from matelab import ByteRange
 
 comments = await client.records.comments(notebook=notebook, record=record)
-attachment = comments.comments[0].attachments[0]
+attachment = comments[0].attachments[0]
 async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
     async for chunk in download:
         consume(chunk)
@@ -436,7 +577,7 @@ Staging mutations are never automatically retried.
 Literature identities distinguish the personal library, shared libraries and pending incoming copies:
 
 ```python
-from matelab import DoiMetadataSource, LiteratureMetadata
+from matelab import LiteratureMetadata
 
 libraries = await client.literature.libraries()
 page = await client.literature.list(libraries.personal.ref)
@@ -444,7 +585,7 @@ detail = await client.literature.read(page.items[0].ref)
 schema = await client.literature.creation_schema()
 
 if schema.metadata_extraction_available:
-    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
+    candidates = await client.literature.extract_metadata(doi="10.0000/example")
 
 await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
 ```
@@ -467,10 +608,8 @@ stable `ByteRange` subset.
 The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
 
 ```python
-from matelab import CloudFolderMetadata
-
 listing = await client.cloud_drive.list()
-folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
+folder_result = await client.cloud_drive.create_folder(name="Example data")
 matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
 
 if len(matches) == 1:
@@ -479,13 +618,13 @@ if len(matches) == 1:
     )
 ```
 
-`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
+`CloudDriveListing` contains a typed file page, complete folder snapshot, quota usage and personal-root permissions rather
 than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
 are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
 no stable ID tie-breaker (PCG-003, PVD-013).
 
 Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
-complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
+complete folder snapshot. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
 exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
 another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
 temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).
@@ -568,8 +707,17 @@ agree. With the environment prepared:
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
-production, and never commit its credentials.
+This command runs only the SDK public-interface smoke; it is not the 71-operation Provider Verification. To reuse the
+same `.env.test` for the complete Contract suite, also populate the optional share user, secondary account, record
+staging opt-in, and Chat SSO settings documented in `.env.example`, then run from sibling checkouts:
+
+```bash
+cd ../matelab-spec
+uv run --env-file ../matelab-python-sdk/.env.test pytest
+```
+
+The files are never loaded implicitly, so normal test runs remain safely skipped. Do not use either flow against
+production, and never commit Provider credentials.
 
 ## Reproducible release build
 
@@ -587,6 +735,6 @@ uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
 ```
 
 Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.1`,
-commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
-`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.2`,
+commit `6dd674ac001ae61197495ace5eba489d585cb825`, and OpenAPI SHA-256
+`7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.