matelab-python-sdk 0.1.0a1__tar.gz

matelab_python_sdk-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Publish release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.14"]
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.32"
+      - name: Sync locked environment
+        run: uv sync --frozen --python "${{ matrix.python-version }}"
+      - name: Check generated wire models
+        if: matrix.python-version == '3.14'
+        run: uv run python scripts/generate_models.py --check
+      - name: Lint
+        if: matrix.python-version == '3.14'
+        run: uv run ruff check .
+      - name: Check formatting
+        if: matrix.python-version == '3.14'
+        run: uv run ruff format --check .
+      - name: Type check
+        if: matrix.python-version == '3.14'
+        run: uv run basedpyright
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: Build reproducible distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.32"
+      - name: Verify tag and configure timestamp
+        shell: bash
+        run: |
+          project_version="$(uv version --short)"
+          test "${GITHUB_REF_NAME}" = "v${project_version}"
+          echo "SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)" >> "${GITHUB_ENV}"
+      - name: Sync locked build environment
+        run: uv sync --frozen --python "3.14"
+      - name: Check generated wire models
+        run: uv run python scripts/generate_models.py --check
+      - name: Build twice
+        run: |
+          mkdir -p dist/release dist/reproducible
+          uv build --no-build-isolation --out-dir dist/release
+          uv build --no-build-isolation --out-dir dist/reproducible
+      - name: Verify reproducibility
+        run: |
+          cmp dist/release/*.whl dist/reproducible/*.whl
+          cmp dist/release/*.tar.gz dist/reproducible/*.tar.gz
+      - name: Audit distributions
+        run: |
+          uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
+          sha256sum dist/release/*.whl dist/release/*.tar.gz
+      - name: Verify installed-wheel consumer
+        run: |
+          uv venv --python "3.14" "${RUNNER_TEMP}/matelab-consumer"
+          uv pip install \
+            --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
+            dist/release/*.whl \
+            "basedpyright==1.39.9" \
+            "nodejs-wheel-binaries==22.20.0"
+          "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
+          "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \
+            --pythonpath "${RUNNER_TEMP}/matelab-consumer/bin/python" \
+            --project tests/typing/pyproject.toml
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: |
+            dist/release/*.whl
+            dist/release/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/matelab-python-sdk
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

matelab_python_sdk-0.1.0a1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.env.test
+.uv-cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.pyc
+.generated/
+dist/

matelab_python_sdk-0.1.0a1/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md
+
+本文档只保留维护 `matelab-python-sdk` 必须长期遵守的项目约束。当前能力和使用方式见
+`README.md`，实现路线与进度见 `docs/roadmap.md`，operation 状态以
+`docs/operation-coverage.yaml` 为机器权威。不要在本文记录阶段性完成状态、一次性验收数字或迁移历史。
+
+## 权威与范围
+
+- 本项目是 Matelab Integration Contract 的通用异步 Python Consumer，负责隐藏 HTTP 编码、认证刷新、
+  Matelab 业务错误、wire model 和 Provider 兼容细节。
+- `contracts/matelab-integration-v1.lock.json` 是 Contract pin 的唯一机器权威；HTTP method、path、编码、
+  字段、required、nullable、默认值、成功码和响应结构以它固定的 OpenAPI snapshot 为准。
+- `/home/tnzhu/projects/matelab-spec` 是 Wire Contract、兼容策略及 Provider 问题的权威。
+  `matelab-server` 是 Provider 实现，`matelab-mcp` 只是 Consumer 证据，均不能反向定义 SDK interface。
+- 开始修改前先执行 `git status`；现有改动均视为用户工作，不覆盖、不移动、不清理。
+- 默认只修改本仓库。未经用户明确授权，不修改相邻仓库，不迁移 MCP，不 commit、push、tag、发布，
+  也不对真实 Provider 执行 mutation。
+- Contract 无法安全表达某项能力时停止实现并报告缺口，不猜测协议，也不静默适配 Provider 漂移。
+
+## Public interface
+
+- `AsyncMatelab` 是稳定入口；能力按 `groups`、`users`、`notebooks`、`records`、`templates`、`uploads`、
+  `literature` 和 `cloud_drive` 等领域组织，不按 PHP endpoint 平铺浅方法。
+- public interface 只表达用户意图；controller、path、opcode、wire 字段和刷新细节必须留在内部。
+- `src/matelab/__init__.py` 的 `__all__` 定义公开边界。`src/matelab/_generated/` 永远是私有实现，
+  Consumer 不得导入或接收 generated model。
+- 公共类型使用含义明确、不可混用的资源身份；不得用模糊 `id` 混淆 userid、database id、UID、relation
+  id 或 staging id。
+- Provider 未返回的 identity、affected rows、排序、分页、原子性、CAS、幂等性或持久化结果不得推测。
+  legacy 限制应通过类型、结果和文档诚实表达。
+- MCP typed refs、capabilities、fingerprints、FastMCP context、Redis session 和 Agent 展示模型不得进入 SDK。
+- 项目支持 Python 3.11+；源码不使用 `from __future__ import annotations`，前向引用优先通过定义顺序解决。
+- 仅在存在真实第二种实现时增加新 seam，不为测试预设无用抽象。
+
+## Contract 与生成
+
+- 每个 operation 都必须核对 pinned OpenAPI 中的 request、response、security、examples 和成功码，并查看相关
+  PVD/PCG；只有 Contract 不足以说明真实 use case 时才只读参考 Consumer。
+- Contract Adoption 只能来自不可变 release tag；同一变更必须更新唯一 lock 的 tag、commit、snapshot
+  path 和 SHA-256，重新生成并复核差异。不得跟踪移动分支或为生成方便改写正式 snapshot。
+- request 和 response 都由生成的 wire model 校验；公共 adapter 负责 Python 名称与 PHP wire 字段之间的映射。
+- required nullable 表示为无默认值的 `T | None`；request 默认拒绝未知字段；response 必须兼容新增字段。
+- 不手工编辑 `src/matelab/_generated/`。generation projection 只可补偿生成器表达能力，并必须保留 inherited
+  required 及 `if/then`、`oneOf`、`anyOf`、`not` 等约束。
+- 生成变化必须能追溯到 Contract snapshot、生成器版本或受测试锁定的生成配置；`--check` 必须保持确定性、
+  非写入并能发现 stale output。
+
+## Transport、认证与安全
+
+- `base_url` 表示 Provider API 根。query、JSON、form-urlencoded、multipart 和 streaming 必须按各 operation
+  定义分别实现。
+- bearer 只用于要求认证的 operation；成功码按 operation 配置，不能全局接受 `{0, 10}`。
+- 每个 `AsyncMatelab` 实例最多持有一个进程内 Session，包含 access/refresh token、毫秒 expiration 和可选
+  identity；不同用户的 token pair 必须拒绝绑定，失败时不得替换现有 Session。
+- `client.session` 暴露实例内最新 Session。持久化、加密、撤销、`userid/session_id` 关联和跨进程锁属于
+  集成方；不同逻辑 Session 不得共享同一个 `AsyncMatelab`，但多个实例可以共享注入的 `httpx.AsyncClient`。
+- access 到期前按 skew 刷新；并发刷新使用单个异步锁；已认证且可安全重试的请求遇到 `code=5` 最多强制
+  刷新并重试一次。
+- mutation 默认不自动重试。multipart 或 stream 只有在确认可重放时才能重试；download stream 不自动重放，
+  必须支持显式关闭。
+- HTTP/transport、Provider business/authentication、Wire Contract/schema 和 client usage 错误必须稳定区分。
+- password、token、SSO code/key、临时附件凭证、原始文件内容和敏感 payload 不得进入日志、异常或提交内容。
+
+## 测试与质量门槛
+
+- 测试以 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、刷新与重试边界。
+- `docs/operation-coverage.yaml` 必须与 pinned OpenAPI exact match；implemented operation 必须有 public
+  interface、wire adapter 和测试，generated model 本身不算实现。
+- 生成测试必须锁定 contract metadata/checksum、schema 覆盖、required/nullable、extra policy、
+  determinism 和 stale detection。
+- Provider smoke 默认 skip 且不自动读取 `.env`。本地 `.env.test` 必须保持 Git ignore，且只可通过显式
+  `uv run --env-file .env.test` 在用户确认的目标和唯一 fixture 上 opt in；优先使用隔离实例，生产目标必须
+  获得本轮明确授权并只使用专用测试 fixture。mutation 或带写痕迹的读取必须显式确认、回读并尽力清理。
+
+Ruff、Basedpyright 和测试要求：
+
+- Ruff 负责格式、lint 和 import sorting，行宽 120，启用 `I` 规则；`src`、`tests`、`scripts` 及生成输出都
+  必须通过 `ruff check` 和 `ruff format --check`，不得以排除测试代码来消除诊断。
+- Basedpyright 使用默认 `recommended` 模式，不在 `pyproject.toml` 重复声明 `typeCheckingMode`；
+  检查 `src`、`tests`、`scripts`，仅排除 `_generated`，目标为 0 errors / 0 warnings。不得全局关闭规则；
+  必要 ignore 必须精确到 rule 并说明原因。
+- 改动时先运行相关 pytest；交付前运行完整测试。skip 必须有明确环境或 fixture 原因，不能把 skip 报告为通过。
+
+完整质量门槛：
+
+```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
+uv build --no-build-isolation
+```
+
+Codex 受限沙箱可能阻止缓存写入、Node wheel 安装或 Python 环境发现，导致 Basedpyright 出现
+`No python interpreter search path` 或大量虚假的 `reportMissingImports`。此时应使用同一条命令在沙箱外
+复核，不得添加 `venvPath`/`venv`、降低检查范围或改用未锁定的全局工具绕过。
+
+## 依赖、版本与发布
+
+- 公开包的 runtime dependency 必须声明经受支持 Python 版本实测的兼容下限，并排除未经验证的下一个
+  major；`uv.lock` 只固定本仓库的开发、测试和构建环境，不能作为下游依赖约束。
+- `hatchling` 作为 build backend 和 dev dependency 使用同一兼容范围，以支持锁定环境中的
+  `uv build --no-build-isolation`。wheel 显式打包 `src/matelab`，不得依赖与发行名不一致的自动发现。
+- `basedpyright==1.39.9` 与其安装所需的 `nodejs-wheel-binaries==22.20.0` 保持精确约束；其他开发工具由
+  `uv.lock` 固定，不向下游发布。
+- `[project].version` 是唯一 SDK 版本源；不得在 Python 模块中增加第二个 `__version__`。
+- SDK 使用 SemVer；`integration-v1` 是 Contract Line，不是 SDK 版本。
+- 公开发行采用 Apache-2.0；`LICENSE`、`NOTICE`、PEP 639 metadata 和构建产物必须保持一致。
+- Gitee `origin` 是内部主仓库；私有 GitHub mirror 只承载 PyPI Trusted Publishing。release workflow 只能由
+  与 `[project].version` 完全匹配的 `v*` tag 触发，第三方 Action 必须固定不可变 commit SHA。
+- release 必须从干净 revision、锁定环境和固定 `SOURCE_DATE_EPOCH` 构建，并记录 Contract tag、commit、
+  OpenAPI checksum 和制品 checksum。
+- release candidate 必须审计 wheel/sdist 内容与 METADATA、验证 wheel 安装后的公开导入及类型消费、
+  覆盖最低和最高受支持 Python 版本，并确认连续两次固定时间戳构建字节一致。wheel 必须包含 `py.typed`，
+  且安装后的 public interface 不得泄漏 `_generated`。
+- public interface 的删除、重命名、类型收紧或行为变化均按 breaking change 处理。

matelab_python_sdk-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 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.0a1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

matelab_python_sdk-0.1.0a1/NOTICE

@@ -0,0 +1,2 @@
+matelab-python-sdk
+Copyright 2026 中国科学院物理研究所凝聚态物质科学数据中心