wps365 — WPS365 云文档 Python 绑定

WPS365 云文档工具（wps365-upload-rs）的 Python 绑定：基于 PyO3 将核心库编译为 CPython 扩展模块，提供云盘文件上传/下载/浏览/分享、智能文档创建、收藏、回收站、评论、标签等能力的同步 Python API。

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

安装（源码构建）

# 仓库根目录：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

快速上手

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 平铺全部 47 个方法（认证 / 云盘 / 文件 / 智能文档 / 搜索 / 收藏 / 回收站 / 评论 / 标签），完整签名见随包分发的 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），需在使用方项目放行：

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

测试

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