wecom-doc-sdk 0.1.0__py3-none-any.whl

wecom_doc_sdk/__init__.py

@@ -0,0 +1,93 @@
+"""企业微信文档 SDK 入口。"""
+
+from .client import AccessTokenProvider, WeComClient
+from .exceptions import WeComAPIError, WeComRequestError
+from .models import (
+    AddField,
+    AddFieldGroupRequest,
+    AddFieldGroupResponse,
+    AddFieldsRequest,
+    AddFieldsResponse,
+    AddRecord,
+    AddRecordsRequest,
+    AddRecordsResponse,
+    AddSheetRequest,
+    AddSheetResponse,
+    AddViewRequest,
+    AddViewResponse,
+    CellValueKeyType,
+    FieldType,
+    GetFieldGroupsRequest,
+    GetFieldGroupsResponse,
+    GetFieldsRequest,
+    GetFieldsResponse,
+    GetRecordsRequest,
+    GetRecordsResponse,
+    GetSheetRequest,
+    GetSheetResponse,
+    GetViewsRequest,
+    GetViewsResponse,
+    Record,
+    UpdateField,
+    UpdateFieldGroupRequest,
+    UpdateFieldGroupResponse,
+    UpdateFieldsRequest,
+    UpdateFieldsResponse,
+    UpdateRecord,
+    UpdateRecordsRequest,
+    UpdateRecordsResponse,
+    UpdateSheetRequest,
+    UpdateSheetResponse,
+    UpdateViewRequest,
+    UpdateViewResponse,
+    ViewType,
+    WeComBaseModel,
+    WeComBaseResponse,
+)
+
+__all__ = [
+    "AccessTokenProvider",
+    "WeComClient",
+    "WeComAPIError",
+    "WeComRequestError",
+    "WeComBaseModel",
+    "WeComBaseResponse",
+    "FieldType",
+    "ViewType",
+    "CellValueKeyType",
+    "AddSheetRequest",
+    "AddSheetResponse",
+    "UpdateSheetRequest",
+    "UpdateSheetResponse",
+    "GetSheetRequest",
+    "GetSheetResponse",
+    "AddViewRequest",
+    "AddViewResponse",
+    "UpdateViewRequest",
+    "UpdateViewResponse",
+    "GetViewsRequest",
+    "GetViewsResponse",
+    "AddField",
+    "AddFieldsRequest",
+    "AddFieldsResponse",
+    "UpdateField",
+    "UpdateFieldsRequest",
+    "UpdateFieldsResponse",
+    "GetFieldsRequest",
+    "GetFieldsResponse",
+    "AddRecord",
+    "AddRecordsRequest",
+    "AddRecordsResponse",
+    "UpdateRecord",
+    "UpdateRecordsRequest",
+    "UpdateRecordsResponse",
+    "GetRecordsRequest",
+    "GetRecordsResponse",
+    "Record",
+    "AddFieldGroupRequest",
+    "AddFieldGroupResponse",
+    "UpdateFieldGroupRequest",
+    "UpdateFieldGroupResponse",
+    "GetFieldGroupsRequest",
+    "GetFieldGroupsResponse",
+]

wecom_doc_sdk/apis/__init__.py

@@ -0,0 +1,5 @@
+"""API 模块入口。"""
+
+from .smartsheet import SmartSheetAPI
+
+__all__ = ["SmartSheetAPI"]

wecom_doc_sdk/apis/smartsheet.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+from typing import Any, Type, TypeVar
+
+from pydantic import BaseModel
+
+from ..client import WeComClient
+from ..models.fields import (
+    AddFieldsRequest,
+    AddFieldsResponse,
+    DeleteFieldsRequest,
+    DeleteFieldsResponse,
+    GetFieldsRequest,
+    GetFieldsResponse,
+    UpdateFieldsRequest,
+    UpdateFieldsResponse,
+)
+from ..models.groups import (
+    AddFieldGroupRequest,
+    AddFieldGroupResponse,
+    DeleteFieldGroupsRequest,
+    DeleteFieldGroupsResponse,
+    GetFieldGroupsRequest,
+    GetFieldGroupsResponse,
+    UpdateFieldGroupRequest,
+    UpdateFieldGroupResponse,
+)
+from ..models.records import (
+    AddRecordsRequest,
+    AddRecordsResponse,
+    DeleteRecordsRequest,
+    DeleteRecordsResponse,
+    GetRecordsRequest,
+    GetRecordsResponse,
+    UpdateRecordsRequest,
+    UpdateRecordsResponse,
+)
+from ..models.sheets import (
+    AddSheetRequest,
+    AddSheetResponse,
+    DeleteSheetRequest,
+    DeleteSheetResponse,
+    GetSheetRequest,
+    GetSheetResponse,
+    UpdateSheetRequest,
+    UpdateSheetResponse,
+)
+from ..models.views import (
+    AddViewRequest,
+    AddViewResponse,
+    DeleteViewsRequest,
+    DeleteViewsResponse,
+    GetViewsRequest,
+    GetViewsResponse,
+    UpdateViewRequest,
+    UpdateViewResponse,
+)
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class SmartSheetAPI:
+    """管理智能表格内容相关接口封装。"""
+
+    def __init__(self, client: WeComClient) -> None:
+        self._client = client
+
+    @staticmethod
+    def _ensure_model(model_cls: Type[TModel], payload: Any) -> TModel:
+        if isinstance(payload, model_cls):
+            return payload
+        return model_cls.model_validate(payload)
+
+    # --- 子表 ---
+    def add_sheet(self, request: AddSheetRequest | dict[str, Any]) -> AddSheetResponse:
+        """在文档的指定位置新增一个智能表子表。
+
+        新建子表初始不包含视图、记录和字段，后续需再调用对应接口补充内容。
+        """
+        req = self._ensure_model(AddSheetRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/add_sheet",
+            json=self._client.dump_model(req),
+        )
+        return AddSheetResponse.model_validate(data)
+
+    def delete_sheet(
+        self, request: DeleteSheetRequest | dict[str, Any]
+    ) -> DeleteSheetResponse:
+        """删除在线表格中的指定子表。"""
+        req = self._ensure_model(DeleteSheetRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/delete_sheet",
+            json=self._client.dump_model(req),
+        )
+        return DeleteSheetResponse.model_validate(data)
+
+    def update_sheet(
+        self, request: UpdateSheetRequest | dict[str, Any]
+    ) -> UpdateSheetResponse:
+        """更新子表信息，当前主要用于修改子表标题。"""
+        req = self._ensure_model(UpdateSheetRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/update_sheet",
+            json=self._client.dump_model(req),
+        )
+        return UpdateSheetResponse.model_validate(data)
+
+    def get_sheet(self, request: GetSheetRequest | dict[str, Any]) -> GetSheetResponse:
+        """查询文档下的子表信息。"""
+        req = self._ensure_model(GetSheetRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/get_sheet",
+            json=self._client.dump_model(req),
+        )
+        return GetSheetResponse.model_validate(data)
+
+    # --- 视图 ---
+    def add_view(self, request: AddViewRequest | dict[str, Any]) -> AddViewResponse:
+        """在子表中新增视图。
+
+        单表最多允许 200 个视图；添加甘特图或日历视图时需传入对应属性。
+        """
+        req = self._ensure_model(AddViewRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/add_view",
+            json=self._client.dump_model(req),
+        )
+        return AddViewResponse.model_validate(data)
+
+    def delete_views(
+        self, request: DeleteViewsRequest | dict[str, Any]
+    ) -> DeleteViewsResponse:
+        """批量删除子表中的一个或多个视图。"""
+        req = self._ensure_model(DeleteViewsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/delete_views",
+            json=self._client.dump_model(req),
+        )
+        return DeleteViewsResponse.model_validate(data)
+
+    def update_view(
+        self, request: UpdateViewRequest | dict[str, Any]
+    ) -> UpdateViewResponse:
+        """更新视图标题或视图属性。
+
+        支持调整排序、过滤、分组、字段显示、冻结列和填色等配置。
+        """
+        req = self._ensure_model(UpdateViewRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/update_view",
+            json=self._client.dump_model(req),
+        )
+        return UpdateViewResponse.model_validate(data)
+
+    def get_views(self, request: GetViewsRequest | dict[str, Any]) -> GetViewsResponse:
+        """获取子表下全部视图信息。"""
+        req = self._ensure_model(GetViewsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/get_views",
+            json=self._client.dump_model(req),
+        )
+        return GetViewsResponse.model_validate(data)
+
+    # --- 字段 ---
+    def add_fields(
+        self, request: AddFieldsRequest | dict[str, Any]
+    ) -> AddFieldsResponse:
+        """在子表中新增一个或多个字段。
+
+        单表最多允许 150 个字段，字段类型与字段属性必须严格匹配。
+        """
+        req = self._ensure_model(AddFieldsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/add_fields",
+            json=self._client.dump_model(req),
+        )
+        return AddFieldsResponse.model_validate(data)
+
+    def delete_fields(
+        self, request: DeleteFieldsRequest | dict[str, Any]
+    ) -> DeleteFieldsResponse:
+        """批量删除子表中的字段。"""
+        req = self._ensure_model(DeleteFieldsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/delete_fields",
+            json=self._client.dump_model(req),
+        )
+        return DeleteFieldsResponse.model_validate(data)
+
+    def update_fields(
+        self, request: UpdateFieldsRequest | dict[str, Any]
+    ) -> UpdateFieldsResponse:
+        """更新字段标题或字段属性。
+
+        该接口不支持修改字段类型；更新时至少应提供待变更的标题或字段属性。
+        """
+        req = self._ensure_model(UpdateFieldsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/update_fields",
+            json=self._client.dump_model(req),
+        )
+        return UpdateFieldsResponse.model_validate(data)
+
+    def get_fields(
+        self, request: GetFieldsRequest | dict[str, Any]
+    ) -> GetFieldsResponse:
+        """查询子表字段信息。
+
+        支持按字段 ID、字段标题或分页方式获取，单次 `limit` 最大为 1000。
+        """
+        req = self._ensure_model(GetFieldsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/get_fields",
+            json=self._client.dump_model(req),
+        )
+        return GetFieldsResponse.model_validate(data)
+
+    # --- 记录 ---
+    def add_records(
+        self, request: AddRecordsRequest | dict[str, Any]
+    ) -> AddRecordsResponse:
+        """在子表中新增一行或多行记录。
+
+        单次添加建议控制在 500 行内，且不能写入创建时间、最后编辑时间、创建人、
+        最后编辑人字段。
+        """
+        req = self._ensure_model(AddRecordsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/add_records",
+            json=self._client.dump_model(req),
+        )
+        return AddRecordsResponse.model_validate(data)
+
+    def delete_records(
+        self, request: DeleteRecordsRequest | dict[str, Any]
+    ) -> DeleteRecordsResponse:
+        """批量删除子表中的记录，单次删除建议控制在 500 行内。"""
+        req = self._ensure_model(DeleteRecordsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/delete_records",
+            json=self._client.dump_model(req),
+        )
+        return DeleteRecordsResponse.model_validate(data)
+
+    def update_records(
+        self, request: UpdateRecordsRequest | dict[str, Any]
+    ) -> UpdateRecordsResponse:
+        """更新子表中的一行或多行记录。
+
+        单次更新建议控制在 500 行内，且不能更新创建时间、最后编辑时间、创建人、
+        最后编辑人字段。
+        """
+        req = self._ensure_model(UpdateRecordsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/update_records",
+            json=self._client.dump_model(req),
+        )
+        return UpdateRecordsResponse.model_validate(data)
+
+    def get_records(
+        self, request: GetRecordsRequest | dict[str, Any]
+    ) -> GetRecordsResponse:
+        """查询子表记录信息。
+
+        支持全量查询、按记录或字段筛选以及排序；`filter_spec` 与 `sort` 不能同时使用，
+        单次 `limit` 最大为 1000。
+        """
+        req = self._ensure_model(GetRecordsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/get_records",
+            json=self._client.dump_model(req),
+        )
+        return GetRecordsResponse.model_validate(data)
+
+    # --- 编组 ---
+    def add_field_group(
+        self, request: AddFieldGroupRequest | dict[str, Any]
+    ) -> AddFieldGroupResponse:
+        """在子表中新增编组。
+
+        单表最多允许 150 个编组，每个编组最多 150 个字段，且字段只能同时属于一个编组。
+        """
+        req = self._ensure_model(AddFieldGroupRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/add_field_group",
+            json=self._client.dump_model(req),
+        )
+        return AddFieldGroupResponse.model_validate(data)
+
+    def update_field_group(
+        self, request: UpdateFieldGroupRequest | dict[str, Any]
+    ) -> UpdateFieldGroupResponse:
+        """更新已有编组的名称或字段成员。
+
+        编组名称不能与已有编组重复，字段仍只能同时属于一个编组。
+        """
+        req = self._ensure_model(UpdateFieldGroupRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/update_field_group",
+            json=self._client.dump_model(req),
+        )
+        return UpdateFieldGroupResponse.model_validate(data)
+
+    def delete_field_groups(
+        self, request: DeleteFieldGroupsRequest | dict[str, Any]
+    ) -> DeleteFieldGroupsResponse:
+        """批量删除子表中的一个或多个编组。"""
+        req = self._ensure_model(DeleteFieldGroupsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/delete_field_groups",
+            json=self._client.dump_model(req),
+        )
+        return DeleteFieldGroupsResponse.model_validate(data)
+
+    def get_field_groups(
+        self, request: GetFieldGroupsRequest | dict[str, Any]
+    ) -> GetFieldGroupsResponse:
+        """获取子表下已有的编组信息。"""
+        req = self._ensure_model(GetFieldGroupsRequest, request)
+        data = self._client.request_json(
+            "POST",
+            "/cgi-bin/wedoc/smartsheet/get_field_groups",
+            json=self._client.dump_model(req),
+        )
+        return GetFieldGroupsResponse.model_validate(data)

wecom_doc_sdk/client.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+from pydantic import BaseModel
+
+from .exceptions import WeComAPIError, WeComRequestError
+
+
+class AccessTokenResponse(BaseModel):
+    """`/cgi-bin/gettoken` 接口响应。
+
+    企业微信会返回凭证本身及其秒级有效期。SDK 会基于该结构做本地缓存，
+    并在凭证过期前提前刷新，避免业务请求在边界时刻拿到失效 token。
+    """
+
+    errcode: int = 0
+    errmsg: str = ""
+    access_token: Optional[str] = None
+    expires_in: Optional[int] = None
+
+
+class AccessTokenProvider:
+    """access_token 获取与缓存。
+
+    说明：
+    - 内部会做简单缓存与提前刷新（默认提前 120 秒）。
+    - 仅用于企业微信自建应用的 corpid/secret 换取 token 场景。
+    - 企业微信官方文档要求开发者在服务端缓存 token，并在失效时重新获取。
+    """
+
+    def __init__(
+        self,
+        corp_id: str,
+        corp_secret: str,
+        *,
+        base_url: str = "https://qyapi.weixin.qq.com",
+        timeout: float = 10.0,
+        refresh_buffer: int = 120,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._corp_id = corp_id
+        self._corp_secret = corp_secret
+        self._refresh_buffer = refresh_buffer
+        self._lock = threading.Lock()
+        self._token: Optional[str] = None
+        self._expire_at: float = 0.0
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(base_url=base_url, timeout=timeout)
+
+    def close(self) -> None:
+        """关闭内部持有的 HTTP 客户端。
+
+        当调用方复用了外部传入的 `httpx.Client` 时，由调用方自己负责关闭。
+        """
+
+        if self._owns_client:
+            self._client.close()
+
+    def get(self) -> str:
+        """获取当前可用的 access_token。
+
+        优先返回缓存中的 token；如果缓存不存在或即将过期，则在锁保护下刷新。
+        这样可以避免多线程环境下重复请求 `/cgi-bin/gettoken`。
+        """
+
+        if self._token and time.time() < self._expire_at - self._refresh_buffer:
+            return self._token
+        # 多线程场景下仅允许一个线程刷新
+        with self._lock:
+            if self._token and time.time() < self._expire_at - self._refresh_buffer:
+                return self._token
+            self._refresh_token()
+            if not self._token:
+                raise WeComRequestError("获取 access_token 失败：返回为空")
+            return self._token
+
+    def _refresh_token(self) -> None:
+        """调用企业微信 `gettoken` 接口刷新缓存中的 access_token。"""
+
+        try:
+            resp = self._client.get(
+                "/cgi-bin/gettoken",
+                params={"corpid": self._corp_id, "corpsecret": self._corp_secret},
+            )
+        except httpx.HTTPError as exc:
+            raise WeComRequestError(
+                "获取 access_token 失败：网络异常", cause=exc
+            ) from exc
+
+        if resp.status_code >= 400:
+            raise WeComRequestError(
+                "获取 access_token 失败：HTTP 状态异常", response=resp
+            )
+
+        try:
+            payload = resp.json()
+        except ValueError as exc:
+            raise WeComRequestError(
+                "获取 access_token 失败：响应不是 JSON", response=resp, cause=exc
+            ) from exc
+
+        data = AccessTokenResponse.model_validate(payload)
+        # 企业微信官方文档明确要求以 errcode 判断是否成功，errmsg 仅用于辅助排障。
+        if data.errcode != 0:
+            raise WeComAPIError(data.errcode, data.errmsg, payload)
+
+        self._token = data.access_token
+        expires_in = int(data.expires_in or 0)
+        # 记录过期时间（秒级）；后续读取时会结合 refresh_buffer 提前刷新。
+        self._expire_at = time.time() + expires_in
+
+
+class WeComClient:
+    """企业微信文档 SDK 客户端（同步版）。
+
+    负责统一管理底层 HTTP 连接、access_token 获取逻辑，以及各业务 API 模块。
+    当前默认挂载智能表格内容相关接口：`smartsheet`。
+    """
+
+    def __init__(
+        self,
+        corp_id: str,
+        corp_secret: str,
+        *,
+        base_url: str = "https://qyapi.weixin.qq.com",
+        timeout: float = 10.0,
+    ) -> None:
+        self._http = httpx.Client(base_url=base_url, timeout=timeout)
+        # 复用 httpx.Client 以减少连接开销，并与 token 获取共用一套超时配置。
+        self._token_provider = AccessTokenProvider(
+            corp_id,
+            corp_secret,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=self._http,
+        )
+        # 延迟导入避免循环依赖
+        from .apis.smartsheet import SmartSheetAPI
+
+        self.smartsheet = SmartSheetAPI(self)
+
+    def close(self) -> None:
+        """关闭底层 HTTP 连接。"""
+
+        self._http.close()
+
+    def __enter__(self) -> "WeComClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # noqa: D401 - 遵循上下文管理协议
+        self.close()
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """统一发送企业微信 JSON 请求。
+
+        该方法会自动注入 `access_token`，并统一处理三类错误：
+        - 网络层或 HTTP 状态异常；
+        - 响应体不是合法 JSON；
+        - 企业微信返回 `errcode != 0` 的业务错误。
+        """
+
+        token = self._token_provider.get()
+        request_params = dict(params or {})
+        # 企业微信大多数服务端接口都要求将 access_token 放在查询参数中。
+        request_params["access_token"] = token
+
+        try:
+            response = self._http.request(
+                method, path, params=request_params, json=json
+            )
+        except httpx.HTTPError as exc:
+            raise WeComRequestError("请求企业微信接口失败", cause=exc) from exc
+
+        if response.status_code >= 400:
+            raise WeComRequestError(
+                "请求企业微信接口失败：HTTP 状态异常", response=response
+            )
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise WeComRequestError(
+                "响应解析失败：不是 JSON", response=response, cause=exc
+            ) from exc
+
+        # 根据企业微信全局错误码文档，必须优先使用 errcode 判断业务是否成功。
+        if isinstance(payload, dict) and payload.get("errcode", 0) != 0:
+            raise WeComAPIError(
+                int(payload.get("errcode", -1)), str(payload.get("errmsg", "")), payload
+            )
+
+        return payload
+
+    @staticmethod
+    def dump_model(model: BaseModel) -> Dict[str, Any]:
+        """统一序列化 Pydantic 模型。
+
+        默认使用字段别名并忽略空值，避免把未填写的可选字段透传给企业微信接口。
+        """
+
+        return model.model_dump(by_alias=True, exclude_none=True)

wecom_doc_sdk/exceptions.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+
+class WeComAPIError(RuntimeError):
+    """企业微信接口返回业务错误时抛出。
+
+    这类异常表示请求已成功到达企业微信，但接口返回了非零 `errcode`。
+    排查时应优先依据 `errcode`，`errmsg` 只作为辅助说明。
+    """
+
+    def __init__(
+        self, errcode: int, errmsg: str, raw: Optional[dict[str, Any]] = None
+    ) -> None:
+        self.errcode = errcode
+        self.errmsg = errmsg
+        # 保留企业微信原始 JSON，便于调用方在日志中定位字段级问题。
+        self.raw = raw or {}
+        super().__init__(f"WeCom API error: {errcode} - {errmsg}")
+
+
+class WeComRequestError(RuntimeError):
+    """网络请求、HTTP 状态或响应解析失败时抛出。
+
+    这类异常通常发生在企业微信真正返回业务结果之前，适合用来区分：
+    - 网络连接异常；
+    - HTTP 状态码异常；
+    - 返回体不是预期 JSON。
+    """
+
+    def __init__(
+        self,
+        message: str,
+        response: Optional[httpx.Response] = None,
+        cause: Optional[BaseException] = None,
+    ) -> None:
+        # 原始响应可帮助排查状态码、响应头或非 JSON 返回体。
+        self.response = response
+        # 透传底层异常，方便日志或调用方保留完整调用栈。
+        self.cause = cause
+        super().__init__(message)