cpan123 0.1.0__tar.gz

cpan123-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.ruff_cache
+.pytest_cache
+.vscode
+*.rar
+*.zip
+drop
+图吧工具箱2409安装程序.exe
+t.py

cpan123-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

cpan123-0.1.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: mkdocs.yml
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt
+        

cpan123-0.1.0/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 20250517
+
+- 初次提交, 可能存在bug. 使用中慢慢发现bug.
+

cpan123-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: cpan123
+Version: 0.1.0
+Summary: 123云盘的python接口文档(非官方)
+Project-URL: Homepage, https://github.com/zoushucai/cpan123
+Project-URL: Documentation, https://cpan123.readthedocs.org
+Project-URL: Repository, https://github.com/zoushucai/cpan123.git
+Project-URL: Issues, https://github.com/zoushucai/cpan123/issues
+Project-URL: Changelog, https://github.com/zoushucai/cpan123/blob/main/CHANGELOG.md
+Author-email: zoushucai <zoushucai@users.noreply.github.com>
+Requires-Python: >=3.10
+Requires-Dist: json5>=0.10.0
+Requires-Dist: jsonpath>=0.6.0
+Requires-Dist: py3-wget>=1.0.0
+Requires-Dist: pydantic>=2.1.0
+Requires-Dist: requests>=2.10.0
+Requires-Dist: tenacity>=8.0.0
+Description-Content-Type: text/markdown
+
+
+## cpan123
+
+这是一个非官方的123云盘开放平台调用库，可以轻松的在Python中调用123云盘开放平台而不需要多次编写重复的代码
+
+文档: [cpan123.readthedocs.io](https://cpan123.readthedocs.io/)
+

cpan123-0.1.0/README.md

@@ -0,0 +1,7 @@
+
+## cpan123
+
+这是一个非官方的123云盘开放平台调用库，可以轻松的在Python中调用123云盘开放平台而不需要多次编写重复的代码
+
+文档: [cpan123.readthedocs.io](https://cpan123.readthedocs.io/)
+

cpan123-0.1.0/docs/auth.md

@@ -0,0 +1,8 @@
+
+## Auth 类
+
+::: cpan123.utils.api.Auth
+    options:
+      members:
+      - set_access_token
+      - refresh_access_token

cpan123-0.1.0/docs/checkdata.md

@@ -0,0 +1,9 @@
+
+## 数据检查
+
+::: cpan123.utils.checkdata
+    options:
+      members:
+      - DataResponse
+      - BaseResponse
+      - JsonInput

cpan123-0.1.0/docs/directlink.md

@@ -0,0 +1,5 @@
+
+## 直链
+
+
+::: cpan123.directlink

cpan123-0.1.0/docs/file.md

@@ -0,0 +1,3 @@
+## 文件类
+
+::: cpan123.file

cpan123-0.1.0/docs/images/cuttlefish.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 440 512"><!--!Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.--><path d="M344 305.5c-17.5 31.6-57.4 54.5-96 54.5-56.6 0-104-47.4-104-104s47.4-104 104-104c38.6 0 78.5 22.9 96 54.5 13.7-50.9 41.7-93.3 87-117.8C385.7 39.1 320.5 8 248 8 111 8 0 119 0 256s111 248 248 248c72.5 0 137.7-31.1 183-80.7-45.3-24.5-73.3-66.9-87-117.8z"/></svg>

cpan123-0.1.0/docs/index.md

@@ -0,0 +1,120 @@
+
+## cpan123
+
+这是一个非官方的123云盘开放平台调用库，可以轻松的在Python中调用123云盘开放平台而不需要多次编写重复的代码
+
+
+- 已有的python库
+
+    - [pan123](https://pypi.org/project/pan123/)
+
+    - [123pan](https://github.com/wojiaoyishang/123pan)
+
+优势:
+
+- 主要对返回的结果做了类型检查, 防止网络异常等不知道什么情况下导致的错误
+
+- 上传文件采用多线程.
+
+- 下载文件采用第三方库, `pip install py3-wget`
+
+吐槽:
+
+- 123云盘有些时候抽风, 对于同一段代码, 有时候能成功, 有时候不能成功, 可能是网络问题, 也可能是123云盘的问题.
+- 同一个文件在网盘上有多份, 有可能居然找不到? 不知道什么怎么回事.(感觉是123云盘抽风)
+
+
+### 安装
+```bash
+pip install cpan123
+```
+
+### 授权
+
+
+!!! note 
+    建议使用环境变量, token和client_id 二选一即可.
+
+    - PAN123TOKEN: 授权 token
+    - PAN123TOKEN_EXPIREDAT: 授权 token 过期时间
+    - PAN123CLIENTID: 客户端 ID
+    - PAN123CLIENTSECRET: 客户端密钥
+
+
+```python
+# 方式1: 使用环境变量中的授权信息
+from cpan123 import Pan123openAPI
+pan123 = Pan123openAPI() 
+
+# 方式2: 使用授权信息
+from cpan123 import Pan123openAPI, Auth
+auth = Auth(clientID="your_client_id", clientSecret="your_client_secret")
+print(auth.access_token) # 打印 access_token
+
+# 或者
+auth = Auth(access_token="your_access_token")
+print(auth.access_token) # 打印 access_token
+
+# 然后传入 Pan123openAPI中
+pan123 = Pan123openAPI(auth=auth)
+
+```
+
+### 使用
+
+```python
+from cpan123 import Pan123openAPI
+from pathlib import Path
+
+pan123 = Pan123openAPI()
+
+# # 下载单个文件
+fname = "xxxx.pt"
+pan123.download(fname)
+
+# # 下载多个文件
+# filenames = ["xxxx1.pt", "xxx2.pt"]
+# pan123.download(filenames)
+# 上传文件
+fname = "xxxxx.zip"
+pan123.upload(fname, fname, 0, overwrite=True)
+print("上传完成")
+
+# 上传文件到oss(图床)
+imgfile = "xxxx.png"
+res = pan123.upload_oss(imgfile, Path(imgfile).name)
+print(res)
+```
+
+- 推荐上传与下载的文件都在根目录下, 且是文件
+
+- 如果一个文件在云端过多, 可能会出一定的bug, 我遇到过, 当同一个文件在云端回收站和根目录下都有时, 下载时会过滤, 结果发现找不到非回收站的文件. 猜测和缓存之类的有关
+
+
+
+### 个人主要用的三个功能已封装.
+
+- [x] 上传文件
+- [x] 下载文件
+- [x] 上传图片到oss
+
+建议单个文件下载与上传, 暂不支持文件夹的上传与下载.
+
+### 已实现的接口
+
+- [x] 文件管理
+- [x] 分享管理
+- [x] 离线下载
+- [x] 用户管理
+- [x] 直链
+- [x] 图床
+- [ ] 视频转码
+    - 容量需要单独购买, 目前不支持对接
+
+
+
+## 参考: 
+
+- [123云盘开放平台](https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/ppsuasz6rpioqbyt)
+
+

cpan123-0.1.0/docs/interface.md

@@ -0,0 +1,118 @@
+
+## 接口
+
+所有的接口采用json文件存储, 一个文件对应一个类接口, 全部存储在 `src/cpan123/apijson` 中
+```bash
+
+src/cpan123/apijson
+├── directlink.json
+├── file.json
+├── offline.json
+├── oss.json
+├── share.json
+└── user.json
+```
+
+## 举例
+- 官方的接口 : [获取文件列表](https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced/zrip9b0ye81zimv4)
+
+- 对应的json文件接口的实现, 引入了一些额外的字段:
+	- `schema_` : 是对接口返回值的描述, 用于验证返回值的正确性, 验证返回的data字段是否符合这个描述, 
+	- `response_schema` : 是对接口返回值的描述, 用于验证返回值的正确性(与上面的区别,在于这个是简单的验证,只要返回的字段中存在指定的key, 就可以了)
+	- `comment` : 是对接口的描述,无意义
+
+- 只能包含以下字段: `method`, `url`, `data`, `params`, `schema_`, `comment`, `response_schema`
+
+
+- 下面是获取文件列表的接口的json文件, 其中`list_v2`是接口的名称, `method`是请求方式, `url`是请求的url, `params`是请求参数, `schema_`是返回值的描述, `comment`是对接口的描述
+
+- 采用json5的方式读入, 因此可以写注释.
+
+- 其中 `params` 和`data` 的格式是一样的, 他们对应下面都是一个dict(没有可以为null或不写), 其值我们不关心,但是其key后续会被用到,应该和python的接口保持一致
+
+
+```json
+{
+  ....
+
+	"list_v2": {
+		"method": "get",
+		"url": "/api/v2/file/list",
+		"params": {
+			"parentFileId": "number: required",
+			"limit": "number: required",
+			"searchData": "string: optional",
+			"searchMode": "number: optional",
+			"lastFileId": "number: optional"
+		},
+		"schema_": {
+			"type": "object",
+			"properties": {
+				"lastFileId": { "type": "number" },
+				"fileList": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"fileId": { "type": "number" },
+							"filename": { "type": "string" },
+							"type": { "type": "number", "enum": [0, 1] },
+							"etag": { "type": "string" },
+							"size": { "type": "number" },
+							"status": { "type": "number" },
+							"parentFileId": { "type": "number" },
+							"category": { "type": "number" }, //"enum": [0, 1, 2, 3] 实际情况可以出现5,而文档写的是0-4, 因此不要
+							"trashed": { "type": "number", "enum": [0, 1] }
+						},
+						"required": ["fileId", "filename", "type", "size", "etag", "status", "parentFileId", "category", "trashed"]
+					}
+				}
+			},
+			"required": ["lastFileId", "fileList"]
+		}
+	},
+  ....
+}
+```
+
+只需要在python中引入即可
+
+```python
+# 引入必要的类
+
+class File(BaseApiClient):
+    def __init__(self, auth: Optional[Auth] = None) -> None:
+        super().__init__(filepath="file", auth=auth) # 这里的filepath对应上面的json文件名,不需要后缀
+
+		...
+		...
+		
+
+    @auto_args_call_api("list_v2")
+    def list_v2(
+        self,
+        parentFileId: int,
+        limit: int = Field(default=100, gt=0, le=100),
+        searchData: Optional[str] = None,
+        searchMode: Optional[int] = 0,
+        lastFileId: Optional[int] = None,
+        skip: bool = False,
+    ) -> DataResponse:  # type: ignore
+        """获取文件列表(V2版本, v1弃用)
+
+        Args:
+            parentFileId (int): 文件夹ID,根目录传 0
+            limit (int): 每页文件数量,最大不超过100
+            searchData (str, optional):搜索关键字将无视文件夹ID参数. 将会进行全局查找
+            searchMode (int, optional): 搜索模式,0:模糊搜索,1:精确搜索,默认为0
+            lastFileId (int, optional): 翻页查询时需要填写
+            skip (bool): 是否跳过响应数据的模式校验
+        """
+        # 这里的函数体根本不会执行, 因为被装饰器给劫持了, 返回的结果是装饰器的返回值,所以对参数进行校验无效
+        # 如果要对参数进行校验,需要 Field 等参数校验方法
+        # 默认已开启函数参数校验
+        # 总结: 所以完全不用写函数体
+
+		...
+		...
+```

cpan123-0.1.0/docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+	tex: {
+		inlineMath: [["\\(", "\\)"]],
+		displayMath: [["\\[", "\\]"]],
+		processEscapes: true,
+		processEnvironments: true,
+	},
+	options: {
+		ignoreHtmlClass: ".*|",
+		processHtmlClass: "arithmatex",
+	},
+};
+
+document$.subscribe(() => {
+	MathJax.startup.output.clearCache();
+	MathJax.typesetClear();
+	MathJax.texReset();
+	MathJax.typesetPromise();
+});

cpan123-0.1.0/docs/offline.md

@@ -0,0 +1,5 @@
+
+## 离线下载
+
+::: cpan123.offline
+

cpan123-0.1.0/docs/oss.md

@@ -0,0 +1,4 @@
+
+## 图床
+
+::: cpan123.oss

cpan123-0.1.0/docs/pan.md

@@ -0,0 +1,3 @@
+# Pan123openAPI 主接口
+
+::: cpan123.pan

cpan123-0.1.0/docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs==1.6.1
+mkdocs-autorefs==1.4.1
+mkdocs-get-deps==0.2.0
+mkdocs-material==9.6.12
+mkdocs-material-extensions==1.3.1
+mkdocstrings==0.29.1
+mkdocstrings-python==1.16.10
+black==25.1.0

cpan123-0.1.0/docs/share.md

@@ -0,0 +1,4 @@
+
+## Share 类
+
+::: cpan123.share

cpan123-0.1.0/docs/user.md

@@ -0,0 +1,3 @@
+## 用户信息
+
+::: cpan123.user

cpan123-0.1.0/mkdocs.yml

@@ -0,0 +1,147 @@
+#[Info]
+site_name: 123云盘的python接口文档 
+site_description: 123云盘的python接口文档(非官方)
+site_author: zsc 
+
+nav:
+  - 介绍: index.md
+  - 主接口: pan.md
+  - Auth类: auth.md
+  - File类: file.md
+  - Share类: share.md
+  - Offline 类: offline.md
+  - User类: user.md
+  - DirectLink 类: directlink.md
+  - Oss 类: oss.md
+  - 更多: 
+      - 数据验证: checkdata.md
+      - 接口的编写: interface.md
+  
+edit_uri: edit/main/docs # 编辑按钮跳转的链接
+repo_url: https://github.com/zoushucai/cpan123 # 右上角点击跳转的链接
+repo_name: cpan123 # 右上角的名字
+copyright: Copyright &copy 2025 by zsc; # 左下角的版权声明
+extra:
+  social:
+    - icon: fontawesome/brands/github     
+      link: https://github.com/zoushucai
+      name: GitHub ##网页右下角的图标链接
+theme:
+  name: material
+  language: zh
+  icon:
+    repo: fontawesome/brands/github #右上角图标
+    logo: fontawesome/brands/cuttlefish #左上角图标
+  favicon: images/cuttlefish.svg 
+  palette:
+  - media: "(prefers-color-scheme)"
+    toggle:
+      icon: material/brightness-auto
+      name: Switch to light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    primary: teal
+    accent: purple
+    toggle:
+      icon: material/weather-sunny
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    primary: black
+    accent: lime
+    toggle:
+      icon: material/weather-night
+      name: Switch to system preference
+  features:
+    - announce.dismiss #呈现可标记为由用户读取的临时公告,可以包含一个用于取消当前公告的按钮
+    - navigation.instant # 现在页面不会跳转,而是类似单页应用,搜索和各种跳转都是在当前页面完成,对美观有很大帮助
+    - header.autohide  #自动隐藏顶部标题(在观看文章的时候会自动隐藏,滑动鼠标的时候会自动显示)
+    - navigation.tracking #地址栏中的 URL 将自动更新为在目录中突出显示的活动锚点
+    - navigation.tabs #顶级部分将呈现在上面视口标题下方的菜单层中,但在移动设备上保持原样
+    - navigation.tabs.sticky  #启用粘性选项卡后,导航选项卡将锁定在标题下方,并在向下滚动时始终保持可见
+    - navigation.sections #启用部分后,顶级部分在边栏中呈现为1220px以上视口的组,但在移动设备上保持原样
+    - navigation.top # 返回顶部的按钮 在上滑时出现
+    - navigation.footer #页脚将呈现在边栏中,但在移动设备上保持原样.,# 页脚提示下一章
+    - search.suggest # 搜索输入一些字母时推荐补全整个单词
+    - search.highlight # 搜索出的文章关键词加入高亮
+    - search.share #搜索分享按钮
+    - navigation.expand # 打开Tab时左侧目录全部展开
+    - navigation.indexes #启用节索引页后,可以将文档直接附加到节
+    - content.tabs.link
+    - content.tooltips
+    - content.code.copy #代码复制
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate 
+
+plugins:
+  - search #搜索配置
+  - autorefs #自动引用
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: ["src"] # 需要解析的路径
+          options:
+            # filters:  #付费功能
+            #   - "!^_[^_]"
+            members_order: source
+            heading_level: 3  # 解析的函数的标题级别
+            show_root_full_path: true  #显示根对象标题的完整 Python 路径,默认为true
+            # show_root_members_full_path: true  #显示根成员的完整 Python 路径.  默认为false
+            # show_object_full_path: true  #递归显示每个成员的完整路径, （默认为false）
+            parameter_headings: false #显示参数标题（默认为false）
+            show_root_toc_entry: true  #显示根对象的目录项(默认为true)
+            # summary: true
+            show_symbol_type_heading: true  #显示符号类型标题（默认为false,建议开启）
+            show_symbol_type_toc: true  #显示符号类型目录项（默认为false,建议开启）
+            show_labels: true   #显示标签（默认为true）
+            docstring_style: google #google风格的文档字符串
+            show_signature: true  #显示方法和函数签名. 
+            separate_signature: true #是否将整个签名放在标题下方的代码块中.  
+            show_signature_annotations: true   #在方法和函数签名中显示类型注释. 
+            # signature_crossrefs: true
+            show_source: true #显示源代码链接(默认为true)
+
+##### 看官网： https://squidfunk.github.io/mkdocs-material/setup/extensions/ #####
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+
+markdown_extensions:
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true  # 固定标题位置为当前位置
+  # Python Markdown Extensions,需要额外加载本地js文件
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic:
+      mode: view  #显示文档中添加、删除或更新的部分
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      linenums: true # 显示行号
+      # auto_title: true # 显示编程语言名称
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true  #切换复选框的渲染样式
+  - pymdownx.tilde  
+
+

cpan123-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "cpan123"
+version = "0.1.0"
+description = "123云盘的python接口文档(非官方)"
+readme = "README.md"
+authors = [
+    { name = "zoushucai", email = "zoushucai@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "json5>=0.10.0",
+    "jsonpath>=0.6.0",
+    "py3-wget>=1.0.0",
+    "pydantic>=2.1.0",
+    "requests>=2.10.0",
+    "tenacity>=8.0.0",
+]
+
+[project.scripts]
+cpan123 = "cpan123:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+
+
+[tool.ruff.lint]
+extend-select = ["I", "B"]
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "jsonschema>=4.23.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-autorefs>=1.4.1",
+    "mkdocs-get-deps>=0.2.0",
+    "mkdocs-material>=9.6.14",
+    "mkdocs-material-extensions>=1.3.1",
+    "mkdocstrings>=0.29.1",
+    "mkdocstrings-python>=1.16.10",
+    "pytest>=8.3.5",
+    "ruff>=0.11.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/zoushucai/cpan123"
+Documentation = "https://cpan123.readthedocs.org"
+Repository = "https://github.com/zoushucai/cpan123.git"
+Issues = "https://github.com/zoushucai/cpan123/issues"
+Changelog = "https://github.com/zoushucai/cpan123/blob/main/CHANGELOG.md"

cpan123-0.1.0/src/cpan123/__init__.py

@@ -0,0 +1,3 @@
+from .pan import Auth, Pan123openAPI
+
+__all__ = ["Pan123openAPI", "Auth"]