fundrive-alidrive 完整使用文档一、包基础说明1. 包定位与核心功能fundrive-alidrive是封装阿里云盘OpenAPI的第三方Python开源SDK全称Fundrive-Alidrive专为阿里云盘个人/团队盘操作设计封装鉴权、文件增删改查、离线下载、分享、目录遍历、批量上传下载、回收站、相册等全套能力屏蔽阿里云盘原生API复杂签名、分页、token刷新逻辑。核心特性自动维护access_token过期自动刷新refresh_token无需手动处理鉴权统一封装文件、文件夹、分享、离线任务、回收站、相册接口支持分片大文件上传、断点续传、流式下载适配GB级大文件内置分页封装无需手动处理分页参数同步/异步双API支持普通脚本与FastAPI/爬虫异步场景支持个人盘共享盘团队空间双存储区切换内置文件过滤、搜索、批量操作封装。2. 前置依赖Python ≥3.8依赖库requests、aiohttp、python-dotenv、tqdm、cryptography自动随包安装前置准备阿里云盘开发者应用前往阿里云盘开放平台创建应用获取client_id、client_secret获取授权refresh_token永久刷新凭证。二、安装方式方式1pip稳定版推荐pipinstallfundrive-alidrive方式2源码最新开发版gitclone https://github.com/fundrive/fundrive-alidrive.gitcdfundrive-alidrive pipinstall.方式3虚拟环境隔离避免依赖冲突python-mvenv alidrive_env# Windowsalidrive_env\Scripts\activate# Mac/Linuxsourcealidrive_env/bin/activate pipinstallfundrive-alidrive三、核心类、语法与全量参数说明3.1 主入口类AlidriveClient同步客户端绝大多数脚本使用fromfundrive_alidriveimportAlidriveClient# 初始化语法clientAlidriveClient(client_id:str,client_secret:str,refresh_token:str,# 可选参数storage_type:strpersonal,# personal个人盘 / shared共享盘timeout:int30,# 请求超时秒数proxy:strNone,# http代理 http://127.0.0.1:7890auto_refresh:boolTrue,# 自动刷新tokencache_token:boolTrue,# 缓存token到本地文件cache_path:str./token_cache.json)3.2 异步客户端AsyncAlidriveClient高并发爬虫、web服务使用语法与同步完全对齐方法加awaitfromfundrive_alidriveimportAsyncAlidriveClientimportasyncioasyncdefmain():clientAsyncAlidriveClient(...)file_listawaitclient.list_files(parent_file_idroot)3.3 核心通用参数所有文件接口通用参数名类型说明默认值parent_file_idstr父目录ID根目录固定root必填namestr文件/文件夹名称创建接口必填file_idstr文件唯一ID操作已有文件必填-drive_idstr盘ID切换共享盘自动填充自动获取limitint分页单次返回条数50markerstr分页游标遍历全部文件自动封装Nonetypestr筛选类型file文件/folder文件夹Nonequerystr文件搜索关键词None3.4 核心方法分类1鉴权相关client.refresh_access_token()手动刷新tokenclient.get_user_info()获取当前登录用户昵称、头像、存储空间2目录/文件基础操作list_files(parent_file_id, limit, type, query)列出目录文件create_folder(parent_file_id, name)新建文件夹get_file_detail(file_id)获取文件元信息大小、创建时间、md5、缩略图rename_file(file_id, new_name)重命名文件/文件夹move_file(file_id, target_parent_id)移动文件到其他目录copy_file(file_id, target_parent_id)复制文件delete_file(file_id, permanentlyFalse)移回收站/永久删除3上传下载upload_file(parent_file_id, local_path, progressTrue)本地文件上传自动分片download_file(file_id, save_local_path, progressTrue)文件流式下载到本地resume_upload(parent_file_id, local_path, upload_task_id)断点续传4离线下载add_offline_task(parent_file_id, url, save_nameNone)添加http/磁力离线下载list_offline_tasks()查询离线任务列表、进度、状态5分享链接create_share(file_id, expire_sec86400, password)创建分享支持密码、有效期cancel_share(share_id)取消分享get_share_info(share_id)获取分享链接信息6回收站list_recycle_bin()列出回收站文件restore_file(file_id)从回收站恢复文件empty_recycle_bin()清空回收站四、8个完整可运行实战案例案例1初始化客户端 获取用户存储空间信息fromfundrive_alidriveimportAlidriveClient# 配置凭证CLIENT_ID你的client_idCLIENT_SECRET你的client_secretREFRESH_TOKEN你的refresh_token# 初始化客户端clientAlidriveClient(client_idCLIENT_ID,client_secretCLIENT_SECRET,refresh_tokenREFRESH_TOKEN,cache_tokenTrue)# 获取用户信息userclient.get_user_info()print(用户名,user[nick_name])print(总空间,round(user[drive_total_size]/1024**3,2),GB)print(已使用,round(user[drive_used_size]/1024**3,2),GB)案例2根目录遍历筛选所有文件夹/文件fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)# 遍历根目录全部内容自动处理分页all_files[]markerNonewhileTrue:resclient.list_files(parent_file_idroot,limit100,markermarker)all_files.extend(res[items])markerres.get(next_marker)ifnotmarker:break# 分离文件夹和文件folders[iforiinall_filesifi[type]folder]files[iforiinall_filesifi[type]file]print(f根目录文件夹数量{len(folders)}文件数量{len(files)})forfinfolders:print(文件夹,f[name],ID:,f[file_id])案例3新建文件夹 本地文件分片上传fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)# 1. 在根目录新建电影文件夹folderclient.create_folder(parent_file_idroot,name本地上传电影)folder_idfolder[file_id]print(新建文件夹ID,folder_id)# 2. 上传本地视频文件自动分片支持10GB大文件upload_resclient.upload_file(parent_file_idfolder_id,local_pathrD:\movie\test.mp4,progressTrue# 显示进度条)print(上传完成云端文件ID,upload_res[file_id])案例4云端文件下载到本地带进度条fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)# 云端文件IDcloud_file_idxxxxxx# 本地保存路径save_pathr./download_movie.mp4# 流式下载占用低内存client.download_file(file_idcloud_file_id,save_local_pathsave_path,progressTrue)print(文件下载完成)案例5磁力链接离线下载到指定目录fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)# 目标文件夹IDtarget_folder_idxxxx# 磁力链接magnet_urlmagnet:?xturn:btih:xxxxxxx# 添加离线任务taskclient.add_offline_task(parent_file_idtarget_folder_id,urlmagnet_url,save_name离线电影.mp4)task_idtask[task_id]print(离线任务创建成功任务ID,task_id)# 查询所有离线任务状态tasksclient.list_offline_tasks()fortintasks[items]:print(f任务{t[task_id]}状态{t[status]}进度{t[progress]}%)案例6文件移动复制批量删除到回收站fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)source_file_id文件IDtarget_folder_id目标文件夹ID# 1. 移动文件client.move_file(file_idsource_file_id,target_parent_idtarget_folder_id)# 2. 复制文件copy_resclient.copy_file(file_idsource_file_id,target_parent_idroot)print(复制后的文件ID,copy_res[file_id])# 3. 删除文件移入回收站permanentlyTrue永久删除不可恢复client.delete_file(file_idcopy_res[file_id],permanentlyFalse)案例7创建加密分享链接读取分享信息fromfundrive_alidriveimportAlidriveClient clientAlidriveClient(id,secret,refresh_token)file_id需要分享的文件ID# 创建7天有效期、4位提取码分享shareclient.create_share(file_idfile_id,expire_sec7*24*3600,password1234)print(分享链接,share[share_url])print(提取码,share[password])print(过期时间戳,share[expire_time])# 读取分享详情share_infoclient.get_share_info(share[share_id])# 取消分享# client.cancel_share(share[share_id])案例8异步批量遍历所有目录高并发场景importasynciofromfundrive_alidriveimportAsyncAlidriveClientasyncdefscan_all_folder():clientAsyncAlidriveClient(client_idxxx,client_secretxxx,refresh_tokenxxx)markerNoneall_items[]whileTrue:resawaitclient.list_files(parent_file_idroot,markermarker,limit50)all_items.extend(res[items])markerres.get(next_marker)ifnotmarker:breakprint(根目录总文件数,len(all_items))awaitclient.close()# 关闭aiohttp会话if__name____main__:asyncio.run(scan_all_folder())五、常见错误、报错原因与解决方案1. AuthenticationError 鉴权失败报错信息refresh token invalid / token expired原因refresh_token过期、手动在阿里云盘网页端退出登录client_id/client_secret填写错误开放平台应用权限未勾选「文件读写」。解决重新获取最新refresh_token核对开发者应用凭证开放平台后台开启文件读写权限。2. UploadChunkError 分片上传失败报错分片上传请求429/500断点续传中断原因网络波动、代理不稳定本地文件被其他程序占用播放器/杀毒扫描单文件超过阿里云盘单文件上限个人盘最大40GB。解决配置稳定代理或关闭代理重试关闭占用本地文件的软件拆分超大文件分卷压缩后上传使用resume_upload断点续传接口恢复任务。3. FileNotFoundError 文件不存在报错file_id not found原因文件已删除、移入回收站混淆个人盘与共享盘file_id跨盘操作file_id复制遗漏字符。解决调用list_recycle_bin恢复文件初始化client时切换storage_typeshared访问共享盘文件重新遍历目录获取正确file_id。4. ApiRateLimitError 429请求限流报错请求频繁触发阿里云盘限流原因短时间大量循环遍历、批量上传下载超出开放平台QPS限制。解决循环内添加time.sleep(0.5~1)异步场景使用信号量限制并发开放平台申请提升应用QPS配额。5. OfflineTaskFailedError 离线任务失败原因磁力链接失效、资源被阿里云盘风控屏蔽、链接文件违规。解决更换资源链接规避版权影视资源。6. ShareCreateError 创建分享失败原因文件违规无法分享、免费用户每日分享次数超限。解决更换文件次日再创建分享。7. ModuleNotFoundError: No module named fundrive_alidrive原因安装失败、虚拟环境未激活、包名拼写错误。解决重新执行pip install fundrive-alidrive确认环境一致。8. ProxyError 代理连接失败报错requests.exceptions.ProxyError原因代理地址错误、代理未开启、不支持socks代理仅支持http/https。解决修正proxy参数或删除proxyNone关闭代理。六、使用注意事项1. 鉴权安全规范禁止硬编码refresh_token、client_id到公开代码GitHub/脚本分享建议使用.env文件python-dotenv读取refresh_token泄露会导致他人完全操控你的网盘泄露后立刻在阿里云盘网页端登出所有设备作废token开启cache_tokenTrue缓存access_token减少频繁刷新token请求。2. 文件操作风险delete_file(permanentlyTrue)永久删除文件无法找回生产环境默认不开启批量删除前先打印文件列表确认避免误删共享盘与个人盘file_id不互通切换盘必须重新初始化客户端。3. 上传下载性能大于100MB文件自动分片无需手动处理下载默认流式读写不会一次性加载完整文件到内存适合超大文件批量上传大量文件时增加延时防止429限流。4. 离线下载限制免费用户离线下载存在每日额度、任务并发数限制版权影视、违规资源会被直接拦截任务直接失败磁力链接仅支持BT协议不支持ed2k。5. 异步客户端使用规范异步客户端使用完毕必须调用await client.close()释放网络会话不要混用同步client与异步client在同一个协程高并发场景设置信号量限制同时上传/下载数量。6. 合规限制禁止使用该SDK批量爬取、转存他人付费/版权资源禁止用于网盘自动引流、批量生成分享链接营销遵守阿里云盘开放平台开发者协议违规会封禁应用与网盘账号。7. 存储与分页list_files默认分页50条遍历全目录必须循环读取next_marker否则只能获取前50个文件存储空间单位为字节转换GB需除以1024³。8. 兼容性Python3.7及以下不支持最低3.8Windows上传路径使用原始字符串rD:\xxx避免转义符报错Linux/Mac路径直接填写绝对路径/home/user/file.mp4。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。
