matelab-python-sdk 0.2.0a1__tar.gz → 0.2.0a3__tar.gz

matelab_python_sdk-0.2.0a3/.env.example

@@ -0,0 +1,7 @@
+# SDK Provider smoke targets the confirmed isolated test service.
+# Configure this repository's .env.test independently of matelab-spec.
+# Authentication and external-token refresh persist Provider token state.
+# Keep these names aligned with matelab-spec Provider Verification.
+MATELAB_PROVIDER_BASE_URL=
+MATELAB_PROVIDER_USERNAME=
+MATELAB_PROVIDER_PASSWORD=

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
           uv pip install \
             --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
             dist/release/*.whl \
-            "basedpyright==1.39.9" \
+            "basedpyright<2,>=1.40.1" \
             "nodejs-wheel-binaries==22.20.0"
           "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
           "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \
@@ -116,4 +116,4 @@ jobs:
           name: python-package-distributions
           path: dist
       - name: Publish distributions
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/AGENTS.md

@@ -5,11 +5,12 @@
 ## 维护顺序
 
 1. **定界**：先读 `git status` 和适用权威；完成标准是任务范围、用户现有改动和所需外部权限均已识别。
-2. **查证**：沿 public intent → wire operation → Provider evidence 核对；完成标准是每个受影响 operation 的
-   request、response、security、examples、成功码及 PVD/PCG 均有结论，Contract 缺口已明确报告。
-3. **收敛**：只修改任务必需的层；完成标准是 public、adapter、generated、tests、coverage 和 docs 的影响均已
-   记账，未加入 Provider 推测、Consumer 私有概念或无真实第二实现的 seam。
-4. **验证**：先跑聚焦测试，再跑适用的完整门槛；完成标准是必需命令全部退出为零，skip 单独说明。
+2. **查证**：涉及 SDK 行为或 Contract 时，沿 public intent → wire operation → Provider evidence 核对受影响
+   operation 的 request、response、security、examples、成功码及 PVD/PCG，明确报告 Contract 缺口。文档、排版和
+   工具配置修改只核对相关权威。
+3. **收敛**：只修改任务必需的层，检查 public、adapter、generated、tests、coverage 和 docs 中受影响的内容。
+4. **验证**：按变更类型选择 [delivery gate](docs/agent-workflows.md#delivery-gate)，先运行相关检查；代码变更先跑
+   聚焦测试，再跑完整门槛。完成标准是必需命令全部退出为零，skip 和 deselected 分别说明。
 5. **交付**：复核最终 diff、状态和验证证据；完成标准是结果、限制和未执行项都可由用户独立核对。
 
 ## 分支指针
@@ -20,11 +21,13 @@
   [`docs/agent-architecture.md#transport-session-and-errors`](docs/agent-architecture.md#transport-session-and-errors)。
 - **Contract adoption**：同步 spec tag、snapshot、lock 或生成模型时执行
   [`docs/agent-workflows.md#contract-adoption`](docs/agent-workflows.md#contract-adoption)。
-- **Delivery gate**：代码、Contract、依赖或构建元数据变化后执行
+- **Configuration and dependencies**：修改 `pyproject.toml`、依赖范围、lock 或对应 CI 配置时读
+  [`docs/agent-workflows.md#configuration-and-dependencies`](docs/agent-workflows.md#configuration-and-dependencies)。
+- **Delivery gate**：交付前按变更类型执行
   [`docs/agent-workflows.md#delivery-gate`](docs/agent-workflows.md#delivery-gate)。
 - **Provider validation**：任何实时 Provider smoke、读取或 mutation 前执行
   [`docs/agent-workflows.md#provider-validation`](docs/agent-workflows.md#provider-validation)。
-- **Release**：版本、制品、commit、tag、push 或 publish 任务执行
+- **Release**：准备版本或发布制品时执行；普通 commit/push 只应用其中的授权与 diff 审查要求
   [`docs/agent-workflows.md#release`](docs/agent-workflows.md#release)。
 
 ## 权威
@@ -48,5 +51,7 @@
   仓库只作只读证据来源。
 - `/home/tnzhu/projects/matelab-spec` 定义 Wire Contract、兼容策略及 Provider 问题；`matelab-server` 是 Provider
   实现，`matelab-mcp` 只提供 Consumer evidence，均不能反向定义 SDK interface。
-- commit、push、tag、publish、生产访问和真实 Provider mutation 需要本轮明确授权；授权只覆盖用户指定的目标与
-  副作用。
+- SDK 与 spec 可以使用同一个 Docker 测试服务，各自维护环境配置和测试职责；修改 SDK 不授权修改邻接仓库或
+  运行 spec 测试。
+- commit、push、tag、publish、生产访问和真实 Provider mutation 需要用户对目标及副作用的明确授权。沿用会话中
+  已有的有效授权；只在目标、副作用超出授权或必要信息缺失时再询问。

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.2.0a3 - 2026-10-02
+
+- Updates the pinned PyPI publishing action to v1.14.2, whose Twine 7 supports the Core Metadata 2.5 emitted by
+  Hatchling 1.32.4. Publishes the changes recorded under `0.2.0a2`; that candidate passed SDK and artifact checks but
+  was not uploaded to PyPI because the previous publisher rejected its metadata version.
+
+## 0.2.0a2 - 2026-10-02
+
+- Raises runtime and build dependency lower bounds to validated stable releases and uses compatible
+  development tool ranges, retaining `nodejs-wheel-binaries==22.20.0` as the sole system-specific exact pin. Refreshes
+  the lock against PyPI and aligns the installed-wheel CI checker with the declared Basedpyright range.
+- Release artifact auditing compares dependency metadata with `pyproject.toml`, and release tests verify version
+  constraints and CI consistency without freezing dependency update values.
+- Sets the distribution author to CMPDC, Institute of Physics, Chinese Academy of Sciences.
+- Documents that SDK smoke can use the same isolated test service as spec while each repository keeps its own test
+  configuration; limits the SDK environment template to its smoke connection settings. Clarifies maintenance
+  validation by change type, keeps the default gate offline, and records the project and Basedpyright field order.
+- Fixes rich-text and comment attachment markers whose names share a prefix, preserving exact attachment bindings
+  regardless of mapping order.
+- Keeps download rejection errors within the public SDK error boundary when response cleanup fails.
+- Consolidates duplicate attachment tests and removes documentation, formatting, and current operation-count
+  assertions. Strengthens SDK stream lifecycle and upload metadata validation coverage with controlled offline fixtures.
+
 ## 0.2.0a1 - 2026-10-02
 
 - Establishes the `0.x` versioning rule: incompatible public changes advance the SDK minor version; alpha/beta/RC

matelab_python_sdk-0.2.0a3/PKG-INFO

@@ -0,0 +1,26 @@
+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

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/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.2.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.2.0a3`. `[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 v2026.10.1` Contract Release. The sole pin,
@@ -38,7 +38,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.2.0a1-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.2.0a3-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -57,7 +57,7 @@ forwarding is outside its verified callable scope (PVD-049).
 ## Versioning
 
 SDK versions express compatibility of the public Python interface and behavior. Python prerelease spelling follows
-PEP 440: `0.2.0a1` is the first alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
+PEP 440: `0.2.0a3` is the third alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
 the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
 changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
 
@@ -872,16 +872,20 @@ aliases, and unrelated fields do not enter exceptions.
 ## Development
 
 ```bash
-uv sync
-uv run python scripts/generate_models.py
+uv sync --frozen
 uv run python scripts/generate_models.py --check
 uv run ruff check .
 uv run ruff format --check .
 uv run basedpyright
-uv run pytest
-uv build
+uv run pytest -m 'not provider'
+uv build --no-build-isolation
 ```
 
+This gate checks the SDK with offline fixtures and excludes the real Provider smoke. Run focused tests first when
+changing code; documentation and configuration-only edits use the relevant checks described in
+[the maintenance workflows](docs/agent-workflows.md#delivery-gate). Contract or generator changes regenerate the
+private models with `uv run python scripts/generate_models.py` before running the gate.
+
 The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
 creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
 generates private component, operation-response, and parameter models. Generator emission uses its built-in formatter;
@@ -890,23 +894,19 @@ projection flattens pure
 object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
 2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and
 deterministic generation without writing the checked-in models. `WireModel` applies that metadata with the standard
-`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current
-lock resolves
-`datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`,
-`pydantic>=2.13.4,<3`, and `typing-extensions>=4.14.1,<5`; the build backend requires
-`hatchling>=1.27,<2`. These lower bounds are verified
-against the complete test suite on the supported Python boundary versions rather than inferred from
-`uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
-Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
-`nodejs-wheel-binaries==22.20.0`.
+`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter.
+
+`pyproject.toml` declares runtime, build, and development compatibility ranges; `uv.lock` fixes the exact environment
+for development and release builds. Runtime and build lower bounds are verified against the complete test suite on
+the supported Python boundary versions. The sole exact development requirement is `nodejs-wheel-binaries`, retained
+for system compatibility. The `0.x` generator and Ruff ranges allow patch updates within their current minor versions.
 
 ## Opt-in Provider consumer smoke
 
 `tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
 scenario covers credential authentication, persistence of the complete returned Session, restoration through a new
-`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. It is not Provider Verification
-and is skipped by default.
+`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. The development gate excludes it;
+a direct pytest run skips it if any of its three connection variables are missing.
 
 Raw Provider conformance remains the responsibility of `matelab-spec`, which sends direct HTTP requests and validates
 the unmodified responses. The SDK does not repeat its route-by-route, cross-account, sharing, or attachment-isolation
@@ -918,31 +918,27 @@ Provider smoke is restricted to the confirmed isolated test service. Authenticat
 token state. This side effect is inherent to the tested Provider operations; it cannot be disabled by a test setting.
 Explicitly loading `.env.test` and selecting the `provider` marker is the opt-in for this flow.
 
-Copy `.env.example` to the git-ignored local `.env.test`, then fill in the shared Provider connection settings:
+SDK smoke can use the same isolated `matelab-test` service as `matelab-spec`. Each repository keeps its own test
+configuration: the SDK uses `.env.test`, and spec keeps its existing `.env`.
+
+Copy this repository's `.env.example` to the git-ignored local `.env.test`, then fill in the SDK connection settings:
 
 - `MATELAB_PROVIDER_BASE_URL`
 - `MATELAB_PROVIDER_USERNAME`
 - `MATELAB_PROVIDER_PASSWORD`
 
-These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
-`.env` into this repository's `.env.test`. Refreshing the restored Session must preserve its authenticated identity.
-With the environment prepared:
+These names intentionally match `matelab-spec` Provider Verification. Refreshing the restored Session must preserve
+its authenticated identity. With the SDK environment prepared, run the public-interface smoke:
 
 ```bash
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-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.
+This command runs only the SDK public-interface smoke; Provider Verification is maintained in
+`matelab-spec` with its own configuration and run instructions.
+SDK tests do not load `.env.test` implicitly; without Provider environment variables, the real smoke remains skipped.
+Offline SDK tests continue to use `MockTransport`. Do not use the smoke flow against production, and never commit
+Provider credentials.
 
 ## Reproducible release build
 

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/docs/agent-architecture.md

@@ -12,7 +12,8 @@
   identity、affected rows、排序、分页、原子性、CAS、幂等性和持久化结果。
 - MCP typed refs、capabilities、fingerprints、FastMCP/Redis context 与 Agent 展示模型留在 Consumer。只有真实
   第二种实现才能引入 seam。
-- 支持 Python 3.11+；源码不使用 `from __future__ import annotations`，前向引用优先靠定义顺序解决。
+- 源码语法遵循 `pyproject.toml` 中 `requires-python` 的最低版本；不使用 `from __future__ import annotations`，
+  前向引用优先靠定义顺序解决。
 
 ## Transport, Session, and errors
 

matelab_python_sdk-0.2.0a3/docs/agent-workflows.md

@@ -0,0 +1,129 @@
+# Agent Maintenance Workflows
+
+本文件只在对应分支触发时加载。机器值始终从仓库读取；这里记录顺序、授权边界和完成标准。
+
+## Contract adoption
+
+1. 读取当前工作区、Contract lock 和远端 release refs。只选择新的 annotated tag；移动分支和改写后的旧
+   snapshot 不能成为 SDK pin。记录 tag object、peeled commit、OpenAPI path 与 SHA-256。完成标准：四者固定且
+   互相一致。
+2. 比较当前 snapshot 与 release commit。逐项核对 operation request、response、security、examples、成功码、
+   Provider evidence 及 PVD/PCG。完成标准：每个 schema/operation 差异都分类为 generated-only、adapter、public
+   interface、test、coverage 或 docs 影响。
+3. request/response 均由生成 wire model 校验，adapter 只映射 public Python 名称与 wire 字段。required nullable
+   使用无默认值的 `T | None`；request 拒绝未知字段，response 接受新增字段。若专用 schema、顶层 request 或
+   Provider evidence 相互矛盾，保留当前安全边界并报告缺口。
+4. 从 release commit 复制 OpenAPI snapshot；同一变更更新 lock 的 tag、commit、snapshot path 和 SHA-256，运行
+   生成脚本并审查完整 generated diff。`_generated` 只由生成脚本修改；projection 只补偿生成器表达能力并保留
+   inherited required、`if/then`、`oneOf`、`anyOf` 和 `not`。完成标准：snapshot hash 与 lock 相等，生成差异
+   全部可由 OpenAPI 差异解释，`--check` 确定、非写入且能发现 stale output。
+5. 同步 runtime、测试、operation coverage、README、CHANGELOG、`pyproject.toml` 与 `uv.lock` 中受影响的当前态。
+   完成标准：每个 Contract 差异都有实现或明确 containment，历史 changelog 未被改写。
+6. 执行 [delivery gate](#delivery-gate)。
+
+## Configuration and dependencies
+
+配置值以 `pyproject.toml` 为准，`uv.lock` 固定本仓库的解析环境，不反向定义发布依赖范围。
+
+- `[project]` 字段依次为 `name`、`version`、`description`、`requires-python`、`keywords`、`authors`、
+  `dependencies`，其他字段放在其后。
+- `[tool.basedpyright]` 字段依次为 `pythonVersion`、`typeCheckingMode`、`include`、`exclude`、
+  `reportUnannotatedClassAttribute`、`reportIncompatibleUnannotatedOverride`，其他设置放在其后。沿用 SDK 的目标
+  Python 版本与检查路径，不照搬其他项目的值。
+- runtime、build 和 dev 依赖声明兼容范围；`nodejs-wheel-binaries` 保留系统兼容性所需的精确固定。更新范围时
+  同步 lock 和安装后消费检查使用的 CI requirement。下限须有实际验证；上限排除未经验证的下一 major，
+  generator 和 Ruff 的 `0.x` 范围排除下一 minor。
+- 构建后端范围和 wheel package 显式配置；metadata 与制品检查从这些声明推导预期值。
+
+完成标准：配置可解析、范围与 lock 一致、受影响 CI 使用同一约束；字段重排不改变配置含义。
+
+## Delivery gate
+
+按本次变更选择验证范围：
+
+- 纯文档修改检查相关事实、本地路径和 Markdown 引用；示例或接口说明变化要对照当前 public interface。
+- 字段重排或显式写出既有默认值，检查语法与有效配置一致性。工具配置的有效设置变化运行对应工具。
+- SDK 代码、测试行为、Contract、依赖范围或影响制品的构建元数据变化，先跑聚焦测试，再完成下列完整门槛。
+- 发布准备在完整门槛之后继续执行 [release](#release) 的制品检查。
+
+已有验证仍对应当前变更且无新失败或疑点时可以复用。文档整理不触发重复的完整测试、构建或实时 Provider 调用。
+
+### SDK test scope
+
+SDK 测试覆盖 public interface 到 wire adapter 的映射、认证与 Session、错误与重试、stream/上传生命周期及
+分发制品。Provider 的逐路由原始 HTTP conformance 由 `matelab-spec` 负责，不在 SDK 重复实现或附带重跑。
+
+新增或修改 operation 覆盖 method/path/encoding、认证、成功映射及适用的空结果、
+required nullable 和 additive response fields；operation coverage 与 pinned OpenAPI exact match，implemented
+operation 同时具备 public interface、wire adapter 和测试。删除或收紧 public interface 时同步移除过时测试，
+不保留无承诺的墓碑 alias。生成测试覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
+stale detection。
+
+优先使用 pinned sanitized examples 或小型受控 fixture 验证稳定行为。operation 数量从 pinned Contract 推导，
+不固定当前数量；当前服务地址和依赖版本值不作为回归断言，除非它们本身就是明确的稳定契约。
+配置值变化只验证语法、约束及相关行为，不另加冻结新值或重复实现逻辑的测试。
+
+Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检查范围；Basedpyright 目标为 0 errors / 0 warnings。
+
+### Full gate
+
+在上面的完整门槛条件成立时运行：
+
+```bash
+uv sync --frozen
+uv run python scripts/generate_models.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest -m 'not provider'
+uv build --no-build-isolation
+```
+
+`not provider` 显式排除实时 smoke，但保留离线 smoke 配置测试。确需实时验证时单独执行
+[Provider validation](#provider-validation)，不通过加载凭证扩展完整门槛的副作用。
+
+检查因权限失败或无进展时，先查看输出和自己启动的进程，区分普通失败与文件、socket、网络或子进程限制。
+有沙箱阻塞证据后停止自己启动的停滞测试，通过工具审批机制申请最小范围重试；保留配置，不改权限、凭证或测试
+行为来绕过限制。超时本身不是沙箱拒绝的证据；无法升级或被拒绝时报告阻塞。
+
+完成标准：必需检查退出为零；skip 按测试名称和原因报告，不能计为通过；deselected 说明筛选范围；最终
+`git diff --check` 无错误。本次新增修改限于任务范围，原有工作区改动按归属保留。
+
+## Provider validation
+
+1. 默认使用 pinned examples、`MockTransport` 和 SDK adapter tests。SDK 不自动读取 `.env` 或 `.env.test`；
+   smoke 从进程环境读取三个连接变量，缺少任一变量就 skip。默认门槛显式排除 `provider`；只有任务确需实时
+   验证且会话授权覆盖目标及副作用时才启用。
+2. 执行前确认目标是隔离服务、`.env.test` 处于 Git ignore、命令显式加载该文件，并列出 authentication、refresh、
+   mutation 或带写痕迹读取的副作用。生产目标或 mutation 必须有对应的明确授权；已有授权不因多轮对话失效。
+3. SDK public smoke 使用 README 的 `Opt-in Provider consumer smoke` 命令；route-by-route conformance 由
+   `matelab-spec` Provider Verification 负责。可以共用 Docker 中的隔离服务，但 SDK `.env.test` 与 spec 的环境
+   配置分别维护，不跨仓库传入 SDK 配置，也不因运行 SDK smoke 附带运行 spec 测试。两者的结果分开报告。
+4. mutation 场景在写前记录 fixture，在写后回读，并尽力清理。完成标准：目标、Provider commit、命令、通过数、
+   skip/failure 和清理结果均可追溯；凭证及敏感 payload 未进入输出或提交。
+
+## Release
+
+版本规划和本地构建可以在请求范围内完成；commit、push、tag、publish 只执行会话已明确授权的步骤。普通
+commit/push 审查并提交或推送已授权的 diff，不自动改版本、建 tag 或发布。发布准备完成后若缺少发布授权，
+交付版本、diff、验证证据和制品结果，授权是执行外部动作前的最后一步。
+
+以下步骤适用于实际发布；只准备版本或制品时止于所需步骤：
+
+1. 读取 `[project].version`，确认待发布版本未发布、changelog 已追加且 Contract pin 完整。SDK 采用 SemVer 的
+   兼容规则，Python 版本拼写遵循 PEP 440；公开接口
+   删除、重命名、类型收紧或不兼容行为变化按 breaking change 处理。`0.x` 阶段 breaking change 递增 minor；
+   `1.0.0` 起兼容修复递增 patch、兼容新增递增 minor、breaking change 递增 major。同一候选版本的预发布使用
+   `aN`、`bN`、`rcN` 并在阶段内递增序号；改变目标版本后重新从 1 开始。spec 的年月版本与 SDK 独立，通过
+   Contract lock 关联，不按 spec 版本号机械递增 SDK。完成标准：版本、文档和 tag 名 `v{version}` 一致。
+2. 在完整 delivery gate 通过且 commit 已授权后创建单一 release commit。完成标准：commit 仅包含已审查、
+   已授权的 diff；隔离无关用户改动，不把清理用户工作区作为发布前提。
+3. 以 release commit 的 committer timestamp 设置 `SOURCE_DATE_EPOCH`，从锁定环境构建两次并逐字节比较 wheel
+   与 sdist；运行 `scripts/check_release.py`，再从 wheel 验证公开导入和类型消费。完成标准：制品可复现，
+   Apache-2.0 `LICENSE`/`NOTICE`、PEP 639 METADATA、`py.typed` 与公开边界审计通过，`_generated` 未公开，
+   checksum 已记录。未提交的本地构建标明对应工作区状态，不作为正式发布制品。
+4. 创建指向 release commit 的 annotated `v{version}` tag。先推送 `origin` 的 main/tag，再推送 GitHub mirror 的
+   main/tag；只有与项目版本完全匹配的 tag 触发 Trusted Publishing workflow，第三方 Action 固定 immutable
+   commit SHA。
+5. 跟踪 CI 的 Python 边界测试、生成检查、可复现构建、安装后消费和 PyPI publish。完成标准：两个远端 main/tag
+   都指向 release commit，workflow success，PyPI 对应版本可读取；原有无关工作区改动保留。

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/pyproject.toml

@@ -1,17 +1,24 @@
 [build-system]
-requires = ["hatchling>=1.27,<2"]
+requires = ["hatchling>=1.32.4,<2"]
 build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a1"
+version = "0.2.0a3"
 description = "Reusable async Python client for the Matelab Integration Contract"
-readme = "README.md"
 requires-python = ">=3.11"
+keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]
+authors = [
+    { name = "CMPDC, Institute of Physics, Chinese Academy of Sciences" },
+]
+dependencies = [
+    "httpx2>=2.13.1,<3",
+    "jsonschema>=4.26.0,<5",
+    "pydantic>=2.13.5,<3",
+    "typing-extensions>=4.16.0,<5",
+]
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
-authors = [{ name = "朱天念", email = "zhutiannian@gmail.com" }]
-keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Framework :: AsyncIO",
@@ -26,28 +33,19 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
-dependencies = [
-    "httpx2>=2.9.1,<3",
-    "jsonschema>=4.26,<5",
-    "pydantic>=2.13.4,<3",
-    "typing-extensions>=4.14.1,<5",
-]
 
 [dependency-groups]
 dev = [
-    "basedpyright==1.39.9",
+    "basedpyright>=1.40.1,<2",
     "nodejs-wheel-binaries==22.20.0",
-    "datamodel-code-generator",
-    "hatchling>=1.27,<2",
-    "pytest",
-    "pytest-asyncio",
-    "pyyaml",
-    "ruff",
+    "datamodel-code-generator>=0.83.0,<0.84",
+    "hatchling>=1.32.4,<2",
+    "pytest>=9.1.1,<10",
+    "pytest-asyncio>=1.4.0,<2",
+    "pyyaml>=6.0.3,<7",
+    "ruff>=0.16.10,<0.17",
 ]
 
-[tool.uv]
-index-url = "https://repo.huaweicloud.com/repository/pypi/simple"
-
 [tool.ruff]
 line-length = 120
 lint.extend-select = ["I"]
@@ -55,9 +53,10 @@ lint.isort.split-on-trailing-comma = false
 format.skip-magic-trailing-comma = true
 
 [tool.basedpyright]
+pythonVersion = "3.11"
+typeCheckingMode = "recommended"
 include = ["src", "tests", "scripts"]
 exclude = ["src/matelab/_generated"]
-pythonVersion = "3.11"
 reportUnannotatedClassAttribute = "none"
 reportIncompatibleUnannotatedOverride = "error"
 

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/scripts/check_release.py

@@ -11,20 +11,17 @@ from pathlib import Path, PurePosixPath
 from typing import cast
 from zipfile import ZipFile
 
+from packaging.requirements import Requirement
+
 _ROOT = Path(__file__).resolve().parents[1]
 _PROJECT = cast(dict[str, object], tomllib.loads((_ROOT / "pyproject.toml").read_text())["project"])
 _PROJECT_NAME = cast(str, _PROJECT["name"])
 _VERSION = cast(str, _PROJECT["version"])
 _DIST_INFO = f"{_PROJECT_NAME.replace('-', '_')}-{_VERSION}.dist-info"
-_EXPECTED_REQUIRES_DIST = {
-    "httpx2<3,>=2.9.1",
-    "jsonschema<5,>=4.26",
-    "pydantic<3,>=2.13.4",
-    "typing-extensions<5,>=4.14.1",
-}
+_EXPECTED_REQUIRES_DIST = {str(Requirement(value)) for value in cast(list[str], _PROJECT["dependencies"])}
 _EXPECTED_LICENSE_FILES = set(cast(list[str], _PROJECT["license-files"]))
 _AUTHOR = cast(list[dict[str, str]], _PROJECT["authors"])[0]
-_EXPECTED_AUTHOR_EMAIL = f"{_AUTHOR['name']} <{_AUTHOR['email']}>"
+_EXPECTED_AUTHOR = _AUTHOR["name"]
 _ALLOWED_ENV_EXAMPLE = ".env.example"
 _FORBIDDEN_PARTS = {
     ".env",
@@ -98,8 +95,8 @@ def _check_metadata(artifact: Path, metadata_bytes: bytes) -> None:
         raise ValueError(f"{artifact.name} contains unexpected License-Expression metadata")
     if set(metadata.get_all("License-File", [])) != _EXPECTED_LICENSE_FILES:
         raise ValueError(f"{artifact.name} contains unexpected License-File metadata")
-    if metadata["Author-email"] != _EXPECTED_AUTHOR_EMAIL:
-        raise ValueError(f"{artifact.name} contains unexpected Author-email metadata")
+    if metadata["Author"] != _EXPECTED_AUTHOR or metadata["Author-email"] is not None:
+        raise ValueError(f"{artifact.name} contains unexpected author metadata")
 
 
 def _audit_wheel(path: Path) -> None:

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/src/matelab/_generated/models.py

@@ -2,7 +2,7 @@
 #
 # @generated by datamodel-codegen:
 #   filename:  openapi.yaml
-#   version:   0.71.0
+#   version:   0.83.0
 
 from enum import Enum, StrEnum
 from typing import Annotated, Any, Literal

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/src/matelab/_transport.py

@@ -80,7 +80,7 @@ def _provider_error(code: int) -> MatelabAuthenticationError | MatelabProviderEr
 
 
 def _header(response: Response, name: str) -> str:
-    return cast(str, response.headers.get(name, ""))
+    return response.headers.get(name, "")
 
 
 def _parse_content_length(response: Response) -> int | None:
@@ -293,7 +293,8 @@ class SessionTransport:
                 raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
 
             if response.status_code not in {200, 206}:
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabTransportError(
                     f"Matelab returned HTTP {response.status_code}.", status_code=response.status_code
                 )
@@ -321,7 +322,8 @@ class SessionTransport:
                     continue
                 raise _provider_error(code)
             if operation.media_types is not None and media_type not in operation.media_types:
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabProtocolError("Matelab returned an unexpected download media type.")
 
             content_length = _parse_content_length(response)
@@ -331,6 +333,7 @@ class SessionTransport:
                 or not _CONTENT_RANGE_PATTERN.fullmatch(_header(response, "Content-Range"))
                 or not _header(response, "Content-Disposition")
             ):
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabProtocolError("Matelab returned invalid partial-download metadata.")
             return DownloadStream(response, content_length=content_length)

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/src/matelab/domains/records.py

@@ -976,10 +976,9 @@ def _encode_record_rich_text(update: RecordRichTextUpdate) -> str:
     markers = set(_ATTACHMENT_MARKER_PATTERN.findall(update.html))
     if markers != set(update.attachments):
         raise MatelabUsageError("Rich-text attachment names must exactly match matelab-attachment:<name> markers.")
-    encoded = update.html
-    for name, attachment in update.attachments.items():
-        encoded = encoded.replace(f"matelab-attachment:{name}", _encode_record_attachment_reference(attachment))
-    return encoded
+    return _ATTACHMENT_MARKER_PATTERN.sub(
+        lambda match: _encode_record_attachment_reference(update.attachments[match.group(1)]), update.html
+    )
 
 
 def _validate_upload_filename(filename: str) -> None:
@@ -1001,15 +1000,15 @@ def _bind_comment_attachments(
 
     first = next(iter(selected_attachments.values()))
     binding_uid = first._binding_uid  # pyright: ignore[reportPrivateUsage]
-    for name, attachment in selected_attachments.items():
+    for attachment in selected_attachments.values():
         attachment_binding_uid = attachment._binding_uid  # pyright: ignore[reportPrivateUsage]
         if attachment.source != source or attachment_binding_uid != binding_uid:
             raise MatelabUsageError("Comment attachments must belong to the same record and upload batch.")
-        body = body.replace(
-            f"matelab-attachment:{name}",
-            attachment._temporary_url,  # pyright: ignore[reportPrivateUsage]
-        )
-    return body, binding_uid
+    bound_body = _ATTACHMENT_MARKER_PATTERN.sub(
+        lambda match: selected_attachments[match.group(1)]._temporary_url,  # pyright: ignore[reportPrivateUsage]
+        body,
+    )
+    return bound_body, binding_uid
 
 
 def _notebook_selector(notebook: NotebookRef) -> str | dict[str, JsonValue]:

{matelab_python_sdk-0.2.0a1 → matelab_python_sdk-0.2.0a3}/tests/test_async_attachment_upload.py

@@ -44,24 +44,6 @@ def _upload_response(
     )
 
 
-@pytest.mark.asyncio
-async def test_upload_attachment_computes_missing_async_checksum(
-    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
-) -> None:
-    async def content():
-        yield _CONTENT
-
-    async def handler(request: Request) -> Response:
-        assert _SHA256.encode() in request.content
-        return _upload_response(provider_envelope, request)
-
-    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)
-        staged = await client.records.upload_attachment(_NOTEBOOK, filename="alpha.txt", content=content())
-
-    assert staged.binding.uid.startswith("upl-")
-
-
 @pytest.mark.asyncio
 async def test_record_attachment_upload_uses_shared_async_content_handling(
     provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
@@ -80,6 +62,7 @@ async def test_record_attachment_upload_uses_shared_async_content_handling(
 
     assert staged.filename == "alpha.txt"
     assert staged.sha256 == _SHA256
+    assert staged.binding.uid.startswith("upl-")
 
 
 @pytest.mark.asyncio