wecom-doc-sdk 0.1.0__tar.gz

wecom_doc_sdk-0.1.0/.gitattributes

@@ -0,0 +1,20 @@
+.agents/** linguist-generated=true
+
+# 统一使用 LF 行尾符（与 Mac/Linux 一致）
+* text=auto eol=lf
+
+# 确保这些文件类型始终使用 LF
+*.ts text eol=lf
+*.tsx text eol=lf
+*.js text eol=lf
+*.jsx text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.mdx text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.css text eol=lf
+*.scss text eol=lf
+*.html text eol=lf
+*.sh text eol=lf

wecom_doc_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/wecom-doc-sdk
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish distributions to PyPI
+        run: uv publish --trusted-publishing always

wecom_doc_sdk-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+docs
+tmp

wecom_doc_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

wecom_doc_sdk-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}\\.venv\\Scripts\\python.exe"
+}

wecom_doc_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,54 @@
+# Agent Guide
+
+本文件用于统一协作式代码生成/修改的约定，帮助快速上手本仓库。
+
+## 项目概览
+
+- 项目：企业微信文档 SDK（Python）
+- 目标：封装企业微信文档相关 API（当前聚焦“管理智能表格内容”）
+- 技术栈：`httpx` + `pydantic` + 完整类型标注
+- 发布包名：`wecom-doc-sdk`
+- Python 导入名：`wecom_doc_sdk`
+
+## 目录与结构
+
+- `src/`：SDK 源码（使用 `src` 布局）
+- `references/`：版本化维护的官方文档入口与参考索引
+- `docs/`：企业微信接口文档参考
+- `tests/`：pytest 测试（如不存在，新增时遵循该目录）
+
+建议包结构（新增代码优先遵循）：  
+`src/wecom_doc_sdk/`  
+`src/wecom_doc_sdk/client.py`（HTTP 客户端封装）  
+`src/wecom_doc_sdk/models/`（Pydantic 模型）  
+`src/wecom_doc_sdk/apis/`（接口封装）
+
+## 开发规范要点
+
+- 中文注释：关键逻辑、边界条件与业务语义必须有中文说明
+- 类型标注：函数/方法需完整类型标注，公开接口必须明确输入输出
+- HTTP：使用 `httpx.Client/AsyncClient` 复用连接；统一超时与错误处理
+- Pydantic：v2 写法；序列化用 `model_dump()`，校验用 `model_validate()`
+- Pydantic 命名冲突：若模块内需要保留业务别名 `Field`，统一将 Pydantic 的 `Field` 导入为 `PydanticField`
+- 错误处理：统一沿用 `WeComAPIError` / `WeComRequestError`，并以 `errcode == 0` 作为业务成功判断标准
+- 扩展性：新增接口按模块拆分，避免把逻辑堆在单文件
+
+详细规范见 `CONTRIBUTING.md`。
+
+## 常用命令
+
+- 安装依赖（开发）：`uv sync --dev`
+- IDE/ty 解释器：优先使用仓库内 `.venv`，VS Code 建议绑定 `${workspaceFolder}\\.venv\\Scripts\\python.exe`
+- 代码风格：`uv run ruff check .`
+- 代码格式：`uv run black --check .`
+- 类型检查：`uv run ty check`
+- 测试：`uv run pytest`
+- 本地构建：`uv build`
+- 分发包检查：`uvx twine check dist/*`
+
+## 变更约定
+
+- 尽量小步提交，改动保持聚焦
+- 不随意重排/重写与本次任务无关的代码
+- 修改公共接口需同步补充类型与文档
+- 涉及发布相关改动时，同步检查 `pyproject.toml`、README 安装命令、导入示例与公共导出是否一致

wecom_doc_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# 贡献指南（开发规范）
+
+本文档用于统一企业微信文档 SDK 的基础开发规范，便于后续扩展与协作。
+
+## 开发环境
+
+- Python 版本：3.10（与项目 `pyproject.toml` 对齐）
+- 建议使用 `uv` 或虚拟环境（`venv`/`conda`）隔离依赖
+- 依赖安装（开发环境）：`uv sync --dev`
+- 发布包名为 `wecom-doc-sdk`，Python 导入名为 `wecom_doc_sdk`
+- 如使用 VS Code/ty，解释器应绑定到仓库内 `.venv`，建议使用 `${workspaceFolder}\\.venv\\Scripts\\python.exe`
+
+## 目录结构与职责边界
+
+- `src/`：SDK 源码，所有业务代码放在此处
+- `references/`：版本化维护的官方文档入口与参考索引
+- `docs/`：企业微信文档与接口说明，仅作参考
+- `tests/`：单元测试目录（如不存在，新增时保持该结构）
+- 建议包结构示例：`src/wecom_doc_sdk/`、`src/wecom_doc_sdk/client.py`、`src/wecom_doc_sdk/models/`、`src/wecom_doc_sdk/apis/`
+- 扩展约束：新增接口优先在 `apis/` 下增量扩展，避免接口逻辑堆在单一文件中
+
+## 代码风格
+
+- 命名：类用 `PascalCase`，函数/变量用 `snake_case`，常量用 `UPPER_SNAKE_CASE`
+- 导入顺序：标准库 > 第三方库 > 本地模块，使用 `ruff` 自动整理
+- 中文注释：关键逻辑、边界条件与业务语义需配中文注释
+- Docstring：公开 API（对外可调用的函数/类）必须写简短 docstring
+
+## 类型规范
+
+- 所有函数与方法需要完整类型标注
+- 公开接口必须明确输入与返回类型
+- 优先使用 `typing` 中的显式类型（如 `Sequence`、`Mapping`）
+
+## Pydantic 规范（v2）
+
+- 模型统一继承 `pydantic.BaseModel`
+- 字段别名、默认值、描述使用 `Field`
+- 序列化/反序列化：输出用 `model_dump()`，输入用 `model_validate()`
+- 如果模块内需要保留业务别名 `Field`，则统一使用 `from pydantic import Field as PydanticField`，避免与业务模型命名冲突
+
+## HTTP 规范（httpx）
+
+- 使用 `httpx.Client`/`httpx.AsyncClient` 复用连接，避免频繁创建
+- 统一超时策略（例如：连接/读取超时都设定）
+- 统一请求封装入口，避免在接口层直接拼接请求细节
+- 需要时添加重试策略（可后续扩展，不在本次强制实现）
+
+## 错误处理
+
+- 统一使用 `WeComAPIError` 表示企业微信返回的业务错误，使用 `WeComRequestError` 表示网络、HTTP 状态或响应解析错误
+- 业务成功始终以 `errcode == 0` 判断，不依赖 `errmsg` 文案做逻辑判断
+- 对外暴露的错误信息应尽量保留：错误码、错误信息、原始响应、底层异常原因（如有）
+- SDK 层不吞异常，必要时包装后抛出
+
+## 测试规范
+
+- 使用 `pytest`，测试文件以 `test_*.py` 命名
+- 测试目录统一放在 `tests/`
+- 新增接口应配套至少 1 个核心路径测试
+
+## Git 流程与提交规范
+
+- 分支命名：`feature/*` 新功能，`fix/*` 缺陷修复，`docs/*` 文档更新
+- 提交信息格式：`type: summary`，示例：`feat: add smart table client`，类型可用 `feat`/`fix`/`docs`/`refactor`/`test`/`chore`
+- 版本发布：遵循 SemVer（`MAJOR.MINOR.PATCH`），打 tag 时与版本号一致
+
+## 发布前检查
+
+- 确认 `pyproject.toml` 中的 `project.name`、`version`、`description` 与 README 描述一致
+- 确认 README 中安装命令使用 `wecom-doc-sdk`，导入示例使用 `wecom_doc_sdk`
+- 确认公共导出与 README 示例保持一致
+- 发布前至少执行一次完整质量检查：`uv run ruff check .`、`uv run black --check .`、`uv run ty check`、`uv run pytest`
+- 发布前至少执行一次本地打包与元数据检查：`uv build`、`uvx twine check dist/*`
+
+## 发布命令（uv）
+
+- 本地构建：`uv build`
+- 分发包检查：`uvx twine check dist/*`
+- 发布到 TestPyPI：`uv publish --index testpypi`
+- 发布到 PyPI：`uv publish`
+- 仓库已提供 GitHub Actions Trusted Publishing 工作流；发布 GitHub Release 后会触发 `.github/workflows/publish.yml` 自动上传到 PyPI
+
+## 质量检查
+
+- 代码风格：`uv run ruff check .`
+- 代码格式：`uv run black --check .`
+- 类型检查：`uv run ty check`
+- 测试：`uv run pytest`

wecom_doc_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: wecom-doc-sdk
+Version: 0.1.0
+Summary: 企业微信文档 SDK
+Project-URL: Homepage, https://github.com/zzwtsy/wecom-doc-sdk
+Project-URL: Repository, https://github.com/zzwtsy/wecom-doc-sdk
+Author-email: zzwtsy <zzwtsy@yumdeb.top>
+Keywords: docs,sdk,smartsheet,wechat-work,wecom
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Typing :: Typed
+Requires-Python: ~=3.10.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# 企业微信文档 SDK
+
+`wecom-doc-sdk` 是一个面向企业微信文档相关服务端 API 的 Python SDK，当前聚焦“文档 -> 管理智能表格内容”能力，并为后续扩展更多文档接口保留了清晰的客户端与模型结构。
+
+## 特性
+
+- 基于 `httpx.Client` 的同步客户端，复用连接并统一处理超时
+- 内置 `access_token` 获取、缓存和提前刷新逻辑
+- 使用 `pydantic v2` 建模请求与响应，便于校验和序列化
+- 完整类型标注，适合编辑器补全与静态检查
+- 对企业微信业务错误与请求错误做了统一异常封装
+- 代码和公开模型带中文注释，尽量降低接入与维护成本
+
+## 当前支持
+
+当前已封装企业微信“管理智能表格内容”中的以下能力：
+
+- 子表：添加、删除、更新、查询
+- 视图：添加、删除、更新、查询
+- 字段：添加、删除、更新、查询
+- 记录：添加、删除、更新、查询
+- 编组：添加、更新、删除、查询
+
+对应入口为 `WeComClient.smartsheet`。
+
+## 安装
+
+要求 Python `3.10+`。
+
+使用 `pip`：
+
+```bash
+pip install wecom-doc-sdk
+```
+
+使用 `uv`：
+
+```bash
+uv add wecom-doc-sdk
+```
+
+如果是本地开发安装：
+
+```bash
+uv sync --dev
+```
+
+## 快速开始
+
+### 创建客户端
+
+```python
+from wecom_doc_sdk import WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    sheets = client.smartsheet.get_sheet({"docid": "DOCID"})
+    print(sheets.ok, sheets.sheet_list)
+```
+
+### 使用 Pydantic 模型查询字段
+
+```python
+from wecom_doc_sdk import GetFieldsRequest, WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    response = client.smartsheet.get_fields(
+        GetFieldsRequest(
+            docid="DOCID",
+            sheet_id="SHEET_ID",
+            limit=100,
+        )
+    )
+
+    if response.fields:
+        for field in response.fields:
+            print(field.field_id, field.field_title, field.field_type)
+```
+
+### 直接使用 `dict` 新增记录
+
+SDK 的公开 API 同时接受 Pydantic 模型或 `dict`。
+
+```python
+from wecom_doc_sdk import WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    response = client.smartsheet.add_records(
+        {
+            "docid": "DOCID",
+            "sheet_id": "SHEET_ID",
+            "records": [
+                {
+                    "values": {
+                        "标题": [{"type": "text", "text": "第一条任务"}],
+                        "进度": 50,
+                    }
+                }
+            ],
+        }
+    )
+
+    print(response.ok, response.records)
+```
+
+## 错误处理
+
+SDK 将错误分成两类：
+
+- `WeComAPIError`：企业微信接口已返回响应，但 `errcode != 0`
+- `WeComRequestError`：网络异常、HTTP 状态异常或响应解析失败
+
+推荐按下面的方式处理：
+
+```python
+from wecom_doc_sdk import WeComAPIError, WeComRequestError, WeComClient
+
+try:
+    with WeComClient(
+        corp_id="YOUR_CORP_ID",
+        corp_secret="YOUR_CORP_SECRET",
+    ) as client:
+        client.smartsheet.get_sheet({"docid": "DOCID"})
+except WeComAPIError as exc:
+    print("业务错误", exc.errcode, exc.errmsg)
+    print("原始响应", exc.raw)
+except WeComRequestError as exc:
+    print("请求失败", exc)
+    print("底层原因", exc.cause)
+```
+
+## 设计约定
+
+- `access_token` 仅在服务端获取和缓存，不应返回给前端
+- 业务成功与否始终以 `errcode` 判断，不应依赖 `errmsg` 文案
+- 所有请求统一通过 `WeComClient.request_json()` 注入 `access_token`
+- 所有模型统一通过 `model_dump(by_alias=True, exclude_none=True)` 序列化
+- 当前客户端为同步版；如后续需要，可在现有结构上扩展异步能力
+
+## 常用导出
+
+根包 `wecom_doc_sdk` 已导出常用客户端、异常和请求/响应模型，例如：
+
+- `WeComClient`
+- `AccessTokenProvider`
+- `WeComAPIError`
+- `WeComRequestError`
+- `AddSheetRequest`
+- `GetFieldsRequest`
+- `AddRecordsRequest`
+- `UpdateViewRequest`
+
+更多模型可从 `wecom_doc_sdk.models` 导入。
+
+## 项目结构
+
+```text
+references/          # 官方文档入口与实现参考索引
+src/wecom_doc_sdk/
+├── apis/           # 接口封装
+├── models/         # Pydantic 模型与枚举
+├── client.py       # 客户端、鉴权与统一请求入口
+└── exceptions.py   # 异常定义
+```
+
+维护时可参考 `references/wecom-docs.md` 中整理的官方文档入口与当前实现对应条目。
+
+## 开发
+
+安装开发依赖：
+
+```bash
+uv sync --dev
+```
+
+常用检查命令：
+
+```bash
+uv run ruff check .
+uv run black --check .
+uv run ty check
+uv run pytest
+```
+
+## 发布
+
+本地构建与检查：
+
+```bash
+uv build
+uvx twine check dist/*
+```
+
+发布到 TestPyPI：
+
+```bash
+uv publish --index testpypi
+```
+
+发布到 PyPI：
+
+```bash
+uv publish
+```
+
+项目约定与贡献规范见 `CONTRIBUTING.md`。
+
+## 适用范围
+
+这个库当前聚焦企业微信文档能力，尤其是智能表格内容管理，但项目结构已经按“可扩展库”来组织。后续可以在保持现有客户端与模型风格一致的前提下，继续扩展更多企业微信文档相关 API 模块。

wecom_doc_sdk-0.1.0/README.md

@@ -0,0 +1,218 @@
+# 企业微信文档 SDK
+
+`wecom-doc-sdk` 是一个面向企业微信文档相关服务端 API 的 Python SDK，当前聚焦“文档 -> 管理智能表格内容”能力，并为后续扩展更多文档接口保留了清晰的客户端与模型结构。
+
+## 特性
+
+- 基于 `httpx.Client` 的同步客户端，复用连接并统一处理超时
+- 内置 `access_token` 获取、缓存和提前刷新逻辑
+- 使用 `pydantic v2` 建模请求与响应，便于校验和序列化
+- 完整类型标注，适合编辑器补全与静态检查
+- 对企业微信业务错误与请求错误做了统一异常封装
+- 代码和公开模型带中文注释，尽量降低接入与维护成本
+
+## 当前支持
+
+当前已封装企业微信“管理智能表格内容”中的以下能力：
+
+- 子表：添加、删除、更新、查询
+- 视图：添加、删除、更新、查询
+- 字段：添加、删除、更新、查询
+- 记录：添加、删除、更新、查询
+- 编组：添加、更新、删除、查询
+
+对应入口为 `WeComClient.smartsheet`。
+
+## 安装
+
+要求 Python `3.10+`。
+
+使用 `pip`：
+
+```bash
+pip install wecom-doc-sdk
+```
+
+使用 `uv`：
+
+```bash
+uv add wecom-doc-sdk
+```
+
+如果是本地开发安装：
+
+```bash
+uv sync --dev
+```
+
+## 快速开始
+
+### 创建客户端
+
+```python
+from wecom_doc_sdk import WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    sheets = client.smartsheet.get_sheet({"docid": "DOCID"})
+    print(sheets.ok, sheets.sheet_list)
+```
+
+### 使用 Pydantic 模型查询字段
+
+```python
+from wecom_doc_sdk import GetFieldsRequest, WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    response = client.smartsheet.get_fields(
+        GetFieldsRequest(
+            docid="DOCID",
+            sheet_id="SHEET_ID",
+            limit=100,
+        )
+    )
+
+    if response.fields:
+        for field in response.fields:
+            print(field.field_id, field.field_title, field.field_type)
+```
+
+### 直接使用 `dict` 新增记录
+
+SDK 的公开 API 同时接受 Pydantic 模型或 `dict`。
+
+```python
+from wecom_doc_sdk import WeComClient
+
+with WeComClient(
+    corp_id="YOUR_CORP_ID",
+    corp_secret="YOUR_CORP_SECRET",
+) as client:
+    response = client.smartsheet.add_records(
+        {
+            "docid": "DOCID",
+            "sheet_id": "SHEET_ID",
+            "records": [
+                {
+                    "values": {
+                        "标题": [{"type": "text", "text": "第一条任务"}],
+                        "进度": 50,
+                    }
+                }
+            ],
+        }
+    )
+
+    print(response.ok, response.records)
+```
+
+## 错误处理
+
+SDK 将错误分成两类：
+
+- `WeComAPIError`：企业微信接口已返回响应，但 `errcode != 0`
+- `WeComRequestError`：网络异常、HTTP 状态异常或响应解析失败
+
+推荐按下面的方式处理：
+
+```python
+from wecom_doc_sdk import WeComAPIError, WeComRequestError, WeComClient
+
+try:
+    with WeComClient(
+        corp_id="YOUR_CORP_ID",
+        corp_secret="YOUR_CORP_SECRET",
+    ) as client:
+        client.smartsheet.get_sheet({"docid": "DOCID"})
+except WeComAPIError as exc:
+    print("业务错误", exc.errcode, exc.errmsg)
+    print("原始响应", exc.raw)
+except WeComRequestError as exc:
+    print("请求失败", exc)
+    print("底层原因", exc.cause)
+```
+
+## 设计约定
+
+- `access_token` 仅在服务端获取和缓存，不应返回给前端
+- 业务成功与否始终以 `errcode` 判断，不应依赖 `errmsg` 文案
+- 所有请求统一通过 `WeComClient.request_json()` 注入 `access_token`
+- 所有模型统一通过 `model_dump(by_alias=True, exclude_none=True)` 序列化
+- 当前客户端为同步版；如后续需要，可在现有结构上扩展异步能力
+
+## 常用导出
+
+根包 `wecom_doc_sdk` 已导出常用客户端、异常和请求/响应模型，例如：
+
+- `WeComClient`
+- `AccessTokenProvider`
+- `WeComAPIError`
+- `WeComRequestError`
+- `AddSheetRequest`
+- `GetFieldsRequest`
+- `AddRecordsRequest`
+- `UpdateViewRequest`
+
+更多模型可从 `wecom_doc_sdk.models` 导入。
+
+## 项目结构
+
+```text
+references/          # 官方文档入口与实现参考索引
+src/wecom_doc_sdk/
+├── apis/           # 接口封装
+├── models/         # Pydantic 模型与枚举
+├── client.py       # 客户端、鉴权与统一请求入口
+└── exceptions.py   # 异常定义
+```
+
+维护时可参考 `references/wecom-docs.md` 中整理的官方文档入口与当前实现对应条目。
+
+## 开发
+
+安装开发依赖：
+
+```bash
+uv sync --dev
+```
+
+常用检查命令：
+
+```bash
+uv run ruff check .
+uv run black --check .
+uv run ty check
+uv run pytest
+```
+
+## 发布
+
+本地构建与检查：
+
+```bash
+uv build
+uvx twine check dist/*
+```
+
+发布到 TestPyPI：
+
+```bash
+uv publish --index testpypi
+```
+
+发布到 PyPI：
+
+```bash
+uv publish
+```
+
+项目约定与贡献规范见 `CONTRIBUTING.md`。
+
+## 适用范围
+
+这个库当前聚焦企业微信文档能力，尤其是智能表格内容管理，但项目结构已经按“可扩展库”来组织。后续可以在保持现有客户端与模型风格一致的前提下，继续扩展更多企业微信文档相关 API 模块。