p115sync 0.1.5

Sync-first Python client for 115 cloud drive, extracted and simplified for direct project usage.

p115sync

p115sync 是一个面向项目直接集成的 115 网盘同步版 Python 库。

这个包的目标不是复刻上游 p115 / p115client 的全部平台能力，而是沉淀一套更适合业务项目直接 pip install 的同步接口：

• 只保留同步调用
• 只保留已经验证稳定、适合业务项目直接复用的 115 能力
• 直接提供围绕同步主链路沉淀出来的常用文件与登录能力

当前范围

首个版本包含：

• P115Client
• P115FileSystem
• P115PathBuilder
• P115Helper
• P115UploadHelper
• QRLogin

已覆盖的主链路包括：

• Cookies 登录态访问
• 扫码登录换取 Cookies
• 文件 / 目录查询、创建、删除、移动、重命名
• 子树遍历、路径构建、同步树构建
• 分享链接信息读取、递归枚举、选择性转存、下载直链提取
• pickcode 下载直链提取
• 秒传初始化与 SHA1 预处理辅助

安装

发布到 PyPI 后：

pip install p115sync

默认安装会一并带上同步主链路实际依赖的运行时组件，包括：

• requests
• pycryptodome
• lz4

这样 P115UploadHelper、分享直链、下载直链等会走加密响应解码的能力，在 pip install p115sync 后就可以直接使用，不需要再额外补装依赖。

如果现有项目里已经写了下面这些命令，它们仍然可以继续使用，但现在只是兼容别名：

pip install "p115sync[upload]"
pip install "p115sync[crypto]"

p115cipher 兼容层仍然以内置 vendoring 形式收进 p115sync 包内，避免再引入 额外顶级包名冲突。

本地开发：

pip install -e ".[dev]"

快速开始

from p115sync import P115Client, P115FileSystem, P115Helper

client = P115Client("UID=...; CID=...; SEID=...;")
fs = P115FileSystem(client)
helper = P115Helper(client, fs=fs)

info = client.user_my_info()
root_exists = fs.exists("/")
download_url = helper.get_share_download_url(
    "https://115.com/s/xxxx?password=1234",
    file_id="123456789",
)

递归读取分享内容：

files = helper.get_all_share_files("https://115.com/s/xxxx?password=1234")
for item in files:
    print(item["path"], item["file_size"])

按 pickcode 获取文件直链：

download = fs.get_download_info("/Movies/demo.mkv", user_agent="VLC/3.0.20")
download_url = download["url"]
download_headers = download["headers"]

设计原则

1. 优先兼容现有业务迁移

为了降低从现有 115 客户端封装迁移过来的成本，这个库尽量延续熟悉的能力边界与调用风格，例如 P115Client、P115FileSystem 这类同步主接口。

2. 明确砍掉通用平台负担

这个包不会内置：

• async_ 双栈
• CLI 子命令
• 多请求后端工厂
• 运行时自动安装依赖

3. 把业务上反复用到的“好方法”直接沉到库里

除了基础 API 包装，本库还包含：

• 路径映射构建
• 目录 / 文件递归遍历
• 批量重命名 / 批量移动
• 分享链接接收与直链提取
• 分享树递归枚举与选择性转存
• pickcode 直链提取
• 秒传前的 SHA1 计算与范围读取辅助

另外，加密兼容层按内部 vendoring 方式收口在 p115sync 自己的命名空间下。 项目侧只需要安装 p115sync 主包，就不需要再额外关心加密运行时依赖和顶级包冲突。

发布前建议

第一次发到 PyPI 前，建议至少确认：

• project.authors
• 仓库地址 / 文档地址
• 最终许可证文本
• 是否要把更多 115 接口公开为稳定 API

当前 pyproject.toml 和 LICENSE 已经满足最基础的发包条件。

版本状态

当前为 0.1.5 发布版本，重点是继续稳定同步主链路，并修正原始上传在大文件场景下的内存占用问题。后续会在保持纯同步定位的前提下逐步补齐更多稳定接口。