Metadata-Version: 2.4
Name: wps365
Version: 0.5.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Summary: WPS365 全域业务 API Python 绑定（云盘、智能文档、待办、组织、知识库、日历、邮件、消息、会议、审批、表格等）
Author: AbyssRei
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# wps365 — WPS365 全域业务 API Python 绑定

WPS365 云文档工具（[wps365-rs](https://codeberg.org/AbyssRei/wps365-rs)）的 Python 绑定：基于 [PyO3](https://github.com/PyO3/pyo3) 将核心库编译为 CPython 扩展模块，提供云盘文件与智能文档修改/导出、待办、组织架构、知识库、日历日程、邮箱、消息、会议、审批、传统/智能/多维表格等全域能力的同步 Python API。

CLI 与桌面 GUI 用法见仓库根 README，本页仅覆盖 Python 绑定。

## 安装（源码构建）

```bash
# 仓库根目录：uv 管理的 venv + maturin
uv venv .venv --python 3.13
uv pip install --python .venv maturin

# 构建并安装到 venv（editable，改 Rust 代码后重复执行即可）
cd crates/wps365-python
VIRTUAL_ENV=<仓库根>/.venv ../../.venv/Scripts/maturin develop

# 或只出分发物
uv build --wheel
```

## 快速上手

```python
from wps365 import Client, Wps365Error

client = Client()                     # 凭据解析：构造参数 > 环境变量 > 配置文件
# client = Client(sid="V02S...")      # 也可直接传入 wps_sid

for item in client.search("季度报告"):
    print(item["name"], item["link_url"])

result = client.upload(r"D:\报告.xlsx", folder="项目文档", share=True)
info = client.download(result["file_id"], dest="./下载")
text = client.read(result["file_id"])["markdown"]    # 在线文档抽取正文
```

`Client` 平铺全部 230 个方法（认证 / 云盘 / 文件 / 智能文档 / 待办 / 组织 / 知识库 / 日历 / 邮箱 / 消息 / 会议 / 审批 / 表格三件套 / 搜索 / 收藏 / 回收站 / 评论 / 标签），完整签名见随包分发的 `wps365.pyi`（IDE 自动补全开箱可用）。所有方法为同步阻塞调用，执行期间释放 GIL；返回值为 openapi 原始响应序列化而来的 dict / list / str。

## 凭据

优先级（首个非空者生效）：构造参数 `sid` > 环境变量 `WPS_SID` > `wps_sid` > `COOKIE`（解析其中 wps_sid 字段）> 配置文件 `auth_state.wps_sid`。

获取 wps_sid：浏览器登录 kdocs.cn → F12 → Application → Cookies → 复制 wps_sid 值。

## 错误处理

全部错误以 `Wps365Error`（`Exception` 子类）抛出，消息格式为「`[机器错误码] 描述`」，错误码与 CLI 一致（`AUTH_EXPIRED_NO_SID` / `INVALID_PARAM` / `API_ERROR` / `IO_ERROR` 等），可按前缀分支处理。

## 静态检查

- **mypy / Pyright（Pylance）**：开箱即用，读取随包分发的 `wps365.pyi`。
- **Pylint**：默认不导入 C 扩展，会对 `wps365.Client` 等成员误报 `no-member`（E1101），需在使用方项目放行：

```toml
# 使用方项目的 pyproject.toml（或同目录 .pylintrc）
[tool.pylint.main]
extension-pkg-allow-list = ["wps365"]
```

## 测试

```bash
cd crates/wps365-python
../../.venv/Scripts/python.exe -m pytest tests/ -v                        # 离线冒烟
WPS365_PYTHON_LIVE=1 ../../.venv/Scripts/python.exe -m pytest tests/ -v   # 含真实 API 用例
```

## License

MIT

