matelab-python-sdk 0.1.0a10__tar.gz → 0.1.0a12__tar.gz

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a12}/AGENTS.md

@@ -69,8 +69,10 @@
 ## 测试与质量门槛
 
 - 测试以 public interface 为主；不得把 `_generated` 或 raw HTTP adapter 当作 Consumer interface。
-- 新增或修改 operation 至少覆盖 method/path/encoding、认证、成功映射、空结果、required nullable、
-  additive response fields、HTTP error、HTTP 200 business error、schema mismatch、刷新与重试边界。
+- 新增或修改 operation 至少覆盖 method/path/encoding、认证、成功映射，以及适用的空结果、required nullable
+  和 additive response fields。通用 HTTP、envelope、Provider error、认证及刷新语义由 transport 测试集中覆盖；
+  operation 测试只重复其特有配置或边界，例如特殊成功码、未认证请求、显式 retry、stream 或 mutation。
+- 删除或收紧 public interface 时同步删除过时测试；除非存在明确兼容承诺，不为已删除名称保留墓碑测试。
 - `docs/operation-coverage.yaml` 必须与 pinned OpenAPI exact match；implemented operation 必须有 public
   interface、wire adapter 和测试，generated model 本身不算实现。
 - 生成测试必须锁定 contract metadata/checksum、schema 覆盖、required/nullable、extra policy、

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a12}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.1.0a12 - 2026-08-07
+
+- Breaking: removes `MatelabAttachmentValidationError`; local attachment size and checksum mismatches now use the
+  existing `MatelabUsageError` without a separate reason/value interface.
+- Adopts immutable `matelab-spec v0.4.0` at commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7` and OpenAPI
+  SHA-256 `e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`. Fixed response models now
+  accept but ignore additive Provider fields; only the Contract's seven semantically open models preserve them.
+- Breaking: removes the unused `StagedUploadSession.new()` constructor and the caller-echoed
+  `StagedFileFragment.fragment_size` field. `uploads.stage()` now owns fresh-session creation while retaining explicit
+  restored sessions, automatic single-`bytes` checksums, and required complete checksums for resumed final fragments.
+- Breaking: removes untyped pass-through attributes from cloud-drive results, literature schema fields, and extracted
+  literature authors. Unknown response fields remain parse-compatible but are ignored unless the Contract defines an
+  open data shape. Template publication reasons now use only the Contract-declared Provider key.
+
+## 0.1.0a11 - 2026-08-05
+
+- Adds `AsyncIterable[bytes]` support to the three complete record-attachment upload interfaces without adding new
+  methods. Async content is spooled, size/checksum validated, rewound, and cleaned up without blocking the event loop;
+  `sha256` may now be omitted and computed by the SDK.
+- Adds structured `MatelabAttachmentValidationError` reasons and expected/actual values so integrations can distinguish
+  size and checksum failures without parsing exception text. Validation failures occur before Provider staging, while
+  source exceptions propagate unchanged.
+
 ## 0.1.0a10 - 2026-08-05
 
 - Keeps synchronous multipart file length probes and chunk reads off the event-loop thread while preserving streamed

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a10
+Version: 0.1.0a12
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -30,10 +30,10 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a10`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a12`. `[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.3.0` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.0` 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.
 
@@ -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.0a10-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a12-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -234,6 +234,20 @@ result = await client.records.import_dataset(
 )
 ```
 
+`content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. `size` is always required and must
+be exact. `sha256` is optional; when omitted, the SDK computes it while consuming the content. Async content is fully
+consumed into a `SpooledTemporaryFile`, size-checked, checksum-checked when a checksum was supplied, rewound, and only
+then sent to the Provider. An over-size stream stops at the first chunk that exceeds the declared size. Temporary-file
+write, seek, read, and close operations run outside the event-loop thread, including after the spool rolls to disk.
+
+Local size or checksum mismatches raise `MatelabUsageError` before any Provider request. An exception raised by the
+async source is propagated unchanged after the SDK closes its temporary file. The SDK does not impose an upload-size
+policy; callers remain responsible for limits such as an HTTP endpoint's maximum accepted body size.
+
+The same content interface is available on `records.upload_attachment()` and
+`records.upload_comment_attachment()`. `uploads.stage()` remains a separate resumable-fragment interface and does not
+accept async content because its per-fragment offset and completion semantics are different.
+
 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:
 
@@ -526,8 +540,6 @@ Provider authorization credentials: current Providers do not verify that associa
 Cross-domain staging keeps resumable state and completed-file identity separate:
 
 ```python
-import hashlib
-
 from matelab import StagedFile
 
 pdf_bytes = b"sanitized PDF bytes"
@@ -535,14 +547,14 @@ staged = await client.uploads.stage(
     pdf_bytes,
     filename="example.pdf",
     fragment_size=len(pdf_bytes),
-    complete_sha256=hashlib.sha256(pdf_bytes).hexdigest(),
 )
 assert isinstance(staged, StagedFile)
 ```
 
-For multiple fragments, pass `StagedFileFragment.session` into the next call. `next_offset` is explicitly a
-caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
-contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
+The SDK computes the complete SHA-256 for a single `bytes` fragment. For multiple fragments, pass
+`StagedFileFragment.session` into the next call and supply `complete_sha256` on the final call. `next_offset` is
+explicitly a caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final
+result contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
 later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
 Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup that is not independently
 verified (PVD-028).
@@ -696,6 +708,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.3.0`,
-commit `0b5612588708b4639a42c7983ee2f08c350994bf`, and OpenAPI SHA-256
-`ebf5d446e3a5866d773cf8cfffe1db28f27015635fbb621bc091673e865ef70e`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.4.0`,
+commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7`, and OpenAPI SHA-256
+`e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`.

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a12}/README.md

@@ -2,10 +2,10 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a10`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a12`. `[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.3.0` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.0` 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.
 
@@ -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.0a10-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a12-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -206,6 +206,20 @@ result = await client.records.import_dataset(
 )
 ```
 
+`content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. `size` is always required and must
+be exact. `sha256` is optional; when omitted, the SDK computes it while consuming the content. Async content is fully
+consumed into a `SpooledTemporaryFile`, size-checked, checksum-checked when a checksum was supplied, rewound, and only
+then sent to the Provider. An over-size stream stops at the first chunk that exceeds the declared size. Temporary-file
+write, seek, read, and close operations run outside the event-loop thread, including after the spool rolls to disk.
+
+Local size or checksum mismatches raise `MatelabUsageError` before any Provider request. An exception raised by the
+async source is propagated unchanged after the SDK closes its temporary file. The SDK does not impose an upload-size
+policy; callers remain responsible for limits such as an HTTP endpoint's maximum accepted body size.
+
+The same content interface is available on `records.upload_attachment()` and
+`records.upload_comment_attachment()`. `uploads.stage()` remains a separate resumable-fragment interface and does not
+accept async content because its per-fragment offset and completion semantics are different.
+
 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:
 
@@ -498,8 +512,6 @@ Provider authorization credentials: current Providers do not verify that associa
 Cross-domain staging keeps resumable state and completed-file identity separate:
 
 ```python
-import hashlib
-
 from matelab import StagedFile
 
 pdf_bytes = b"sanitized PDF bytes"
@@ -507,14 +519,14 @@ staged = await client.uploads.stage(
     pdf_bytes,
     filename="example.pdf",
     fragment_size=len(pdf_bytes),
-    complete_sha256=hashlib.sha256(pdf_bytes).hexdigest(),
 )
 assert isinstance(staged, StagedFile)
 ```
 
-For multiple fragments, pass `StagedFileFragment.session` into the next call. `next_offset` is explicitly a
-caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
-contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
+The SDK computes the complete SHA-256 for a single `bytes` fragment. For multiple fragments, pass
+`StagedFileFragment.session` into the next call and supply `complete_sha256` on the final call. `next_offset` is
+explicitly a caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final
+result contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
 later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
 Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup that is not independently
 verified (PVD-028).
@@ -668,6 +680,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.3.0`,
-commit `0b5612588708b4639a42c7983ee2f08c350994bf`, and OpenAPI SHA-256
-`ebf5d446e3a5866d773cf8cfffe1db28f27015635fbb621bc091673e865ef70e`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.4.0`,
+commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7`, and OpenAPI SHA-256
+`e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`.

{matelab_python_sdk-0.1.0a10 → matelab_python_sdk-0.1.0a12}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.3.0",
-    "commit": "0b5612588708b4639a42c7983ee2f08c350994bf"
+    "tag": "v0.4.0",
+    "commit": "7993a7bccc213f626b9cc8124423e2b2c9e48dd7"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "ebf5d446e3a5866d773cf8cfffe1db28f27015635fbb621bc091673e865ef70e"
+    "sha256": "e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e"
   }
 }