p115sync 0.1.6

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 主包，就不需要再额外关心加密运行时依赖和顶级包冲突。

发布流程

项目内已经提供了可复用的 conda 发布环境和统一发布脚本，后续发包不要再临时手敲散命令。

推荐直接使用总入口脚本，它会自动创建或更新专用 conda 环境，然后在环境内完成构建、校验和上传。

1. 修改版本号：

• pyproject.toml
• src/p115sync/version.py

2. 先本地构建并校验产物：

bash scripts/release_pypi.sh

3. 上传到 PyPI：

export PYPI_TOKEN='pypi-***'
bash scripts/release_pypi.sh --upload

如果你想单独管理环境，不走总入口脚本，也可以继续使用底层命令：

1. 初始化或更新专用环境：

/opt/anaconda3/bin/conda env create -f environment.publish.yml
/opt/anaconda3/bin/conda env update -f environment.publish.yml --prune

2. 先本地构建并校验产物：

/opt/anaconda3/bin/conda run -n p115sync-publish bash scripts/publish_pypi.sh

3. 上传到 PyPI：

export PYPI_TOKEN='pypi-***'
/opt/anaconda3/bin/conda run -n p115sync-publish bash scripts/publish_pypi.sh --upload

脚本会自动：

• 校验 pyproject.toml 和 version.py 的版本号是否一致
• 清理旧的 build/、dist/ 和 src/p115sync.egg-info/
• 执行 python -m build
• 执行 python -m twine check dist/*
• 在显式传入 --upload 时执行 twine upload

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

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

版本状态

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