bdds 0.1.0__tar.gz

bdds-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bdds contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bdds-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: bdds
+Version: 0.1.0
+Summary: Baidu Disk SDK - 百度网盘 Python SDK
+Author: hochenggang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hochenggang
+Project-URL: Repository, https://github.com/hochenggang/bdds
+Project-URL: Bug Tracker, https://github.com/hochenggang/bdds/issues
+Keywords: baidu,pan,netdisk,sdk,baidupan,baidu-disk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# bdds
+
+Baidu Disk SDK - 简单、有效、报错清晰的百度网盘 Python SDK。
+
+基于 [百度网盘开放平台 API](https://pan.baidu.com/union/doc/) 封装，核心依赖仅 `requests`。
+
+## 安装
+
+```bash
+pip install bdds
+```
+
+## 快速开始
+
+### 1. 获取应用凭证
+
+在 [百度网盘开放平台](https://pan.baidu.com/union/doc/) 创建应用，获取 `client_id`、`client_secret` 和 `app_name`。
+
+### 2. 初始化客户端
+
+```python
+from pathlib import Path
+from bdds import BaiduPanClient
+
+client = BaiduPanClient(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+    app_name="your_app_name",
+)
+```
+
+### 3. 授权登录
+
+```python
+# 首次使用需要授权
+if not client.access_token:
+    print(f"请在浏览器打开: {client.auth_url}")
+    code = input("请输入授权码: ")
+    client.fetch_token(code)
+```
+
+Token 会自动保存到 `~/.baidupan/` 目录，下次启动无需重新授权。
+
+### 4. 使用 API
+
+```python
+# 查询空间配额
+quota = client.get_quota()
+print(f"已用: {quota.used / 1024**3:.1f} GB / 总计: {quota.total / 1024**3:.1f} GB")
+
+# 上传文件 - 支持 Path / bytes / Generator
+result = client.upload(Path("local_file.txt"))
+result = client.upload(Path("data.bin"), file_to=Path("/backup/data.bin"))
+result = client.upload(b"hello world", file_to=Path("/hello.txt"))
+
+# 获取文件元信息
+metas = client.get_file_metas([result.fs_id])
+dlink = metas[0].dlink
+
+# 下载文件 - file_to=None 返回流式迭代器，file_to=Path 写入文件
+path = client.download(dlink, file_to=Path("downloaded.txt"))
+
+# 流式下载（适合大文件或自定义处理）
+for chunk in client.download(dlink):
+    process(chunk)
+
+# 列出文件
+items = client.get_file_list("/apps/your_app_name/")
+for item in items:
+    print(f"{'[DIR]' if item.is_dir else '     '} {item.filename} ({item.size} bytes)")
+
+# 删除文件
+client.delete_files(["/apps/your_app_name/old_file.txt"])
+
+# 使用完毕后关闭
+client.close()
+```
+
+推荐使用上下文管理器自动关闭：
+
+```python
+with BaiduPanClient(client_id, client_secret, app_name) as client:
+    quota = client.get_quota()
+    # ...
+```
+
+## API 参考
+
+### BaiduPanClient
+
+| 方法 | 说明 |
+|------|------|
+| `upload(file_from, file_to=None)` | 上传文件。`file_from` 支持 `Path` / `bytes` / `Generator[bytes]`；`file_to` 为远程路径 `Path`，默认使用文件名 |
+| `download(dlink, file_to=None, chunk_size=1048576)` | 下载文件。`file_to=None` 返回字节迭代器；`file_to=Path` 写入本地文件 |
+| `get_quota()` | 获取空间配额，返回 `ApiQuotaInfo` |
+| `get_file_metas(fsids)` | 获取文件元信息，返回 `list[ApiFileMeta]` |
+| `get_file_list(path)` | 列出目录文件，返回 `list[ApiFileListItem]` |
+| `delete_files(file_paths)` | 批量删除文件 |
+| `fetch_token(code)` | 通过授权码获取 Token |
+| `refresh_token()` | 刷新 Token |
+| `close()` | 关闭客户端 |
+
+### 异常体系
+
+```
+BaiduPanError
+├── BaiduPanNetworkError    # 网络通信异常
+├── BaiduPanAPIError        # API 业务异常 (errno, errmsg, request_id)
+└── TokenExpiredError       # Token 过期或无效
+```
+
+所有异常均继承自 `BaiduPanError`，方便统一捕获。
+
+### 特性
+
+- **自动重试** — 网络请求自动重试（可配置次数），支持指数退避
+- **Token 管理** — 自动持久化、自动刷新、文件权限限制
+- **分片上传** — 大文件自动分片上传（4MB 分片）
+- **流式下载** — 支持断点续传、指数重试
+- **类型安全** — 完整类型标注，支持 PEP 561 (`py.typed`)
+- **报错清晰** — 异常包含 `errno`、`errmsg`、`request_id`、`url` 等上下文
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+python -m pytest -v
+
+# 构建
+pip install build twine
+python -m build
+```
+
+## License
+
+MIT

bdds-0.1.0/README.md

@@ -0,0 +1,139 @@
+# bdds
+
+Baidu Disk SDK - 简单、有效、报错清晰的百度网盘 Python SDK。
+
+基于 [百度网盘开放平台 API](https://pan.baidu.com/union/doc/) 封装，核心依赖仅 `requests`。
+
+## 安装
+
+```bash
+pip install bdds
+```
+
+## 快速开始
+
+### 1. 获取应用凭证
+
+在 [百度网盘开放平台](https://pan.baidu.com/union/doc/) 创建应用，获取 `client_id`、`client_secret` 和 `app_name`。
+
+### 2. 初始化客户端
+
+```python
+from pathlib import Path
+from bdds import BaiduPanClient
+
+client = BaiduPanClient(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+    app_name="your_app_name",
+)
+```
+
+### 3. 授权登录
+
+```python
+# 首次使用需要授权
+if not client.access_token:
+    print(f"请在浏览器打开: {client.auth_url}")
+    code = input("请输入授权码: ")
+    client.fetch_token(code)
+```
+
+Token 会自动保存到 `~/.baidupan/` 目录，下次启动无需重新授权。
+
+### 4. 使用 API
+
+```python
+# 查询空间配额
+quota = client.get_quota()
+print(f"已用: {quota.used / 1024**3:.1f} GB / 总计: {quota.total / 1024**3:.1f} GB")
+
+# 上传文件 - 支持 Path / bytes / Generator
+result = client.upload(Path("local_file.txt"))
+result = client.upload(Path("data.bin"), file_to=Path("/backup/data.bin"))
+result = client.upload(b"hello world", file_to=Path("/hello.txt"))
+
+# 获取文件元信息
+metas = client.get_file_metas([result.fs_id])
+dlink = metas[0].dlink
+
+# 下载文件 - file_to=None 返回流式迭代器，file_to=Path 写入文件
+path = client.download(dlink, file_to=Path("downloaded.txt"))
+
+# 流式下载（适合大文件或自定义处理）
+for chunk in client.download(dlink):
+    process(chunk)
+
+# 列出文件
+items = client.get_file_list("/apps/your_app_name/")
+for item in items:
+    print(f"{'[DIR]' if item.is_dir else '     '} {item.filename} ({item.size} bytes)")
+
+# 删除文件
+client.delete_files(["/apps/your_app_name/old_file.txt"])
+
+# 使用完毕后关闭
+client.close()
+```
+
+推荐使用上下文管理器自动关闭：
+
+```python
+with BaiduPanClient(client_id, client_secret, app_name) as client:
+    quota = client.get_quota()
+    # ...
+```
+
+## API 参考
+
+### BaiduPanClient
+
+| 方法 | 说明 |
+|------|------|
+| `upload(file_from, file_to=None)` | 上传文件。`file_from` 支持 `Path` / `bytes` / `Generator[bytes]`；`file_to` 为远程路径 `Path`，默认使用文件名 |
+| `download(dlink, file_to=None, chunk_size=1048576)` | 下载文件。`file_to=None` 返回字节迭代器；`file_to=Path` 写入本地文件 |
+| `get_quota()` | 获取空间配额，返回 `ApiQuotaInfo` |
+| `get_file_metas(fsids)` | 获取文件元信息，返回 `list[ApiFileMeta]` |
+| `get_file_list(path)` | 列出目录文件，返回 `list[ApiFileListItem]` |
+| `delete_files(file_paths)` | 批量删除文件 |
+| `fetch_token(code)` | 通过授权码获取 Token |
+| `refresh_token()` | 刷新 Token |
+| `close()` | 关闭客户端 |
+
+### 异常体系
+
+```
+BaiduPanError
+├── BaiduPanNetworkError    # 网络通信异常
+├── BaiduPanAPIError        # API 业务异常 (errno, errmsg, request_id)
+└── TokenExpiredError       # Token 过期或无效
+```
+
+所有异常均继承自 `BaiduPanError`，方便统一捕获。
+
+### 特性
+
+- **自动重试** — 网络请求自动重试（可配置次数），支持指数退避
+- **Token 管理** — 自动持久化、自动刷新、文件权限限制
+- **分片上传** — 大文件自动分片上传（4MB 分片）
+- **流式下载** — 支持断点续传、指数重试
+- **类型安全** — 完整类型标注，支持 PEP 561 (`py.typed`)
+- **报错清晰** — 异常包含 `errno`、`errmsg`、`request_id`、`url` 等上下文
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+python -m pytest -v
+
+# 构建
+pip install build twine
+python -m build
+```
+
+## License
+
+MIT

bdds-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bdds"
+version = "0.1.0"
+description = "Baidu Disk SDK - 百度网盘 Python SDK"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "hochenggang" },
+]
+keywords = ["baidu", "pan", "netdisk", "sdk", "baidupan", "baidu-disk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-mock>=3.0",
+    "responses>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/hochenggang"
+Repository = "https://github.com/hochenggang/bdds"
+"Bug Tracker" = "https://github.com/hochenggang/bdds/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bdds-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bdds-0.1.0/src/bdds/__init__.py

@@ -0,0 +1,39 @@
+"""bdds - 百度网盘 Python SDK (baidu-disk-sdk)
+
+简单、有效、报错清晰的百度网盘同步 SDK。
+
+Usage::
+
+    from bdds import BaiduPanClient
+
+    with BaiduPanClient(client_id, client_secret, app_name) as client:
+        quota = client.get_quota()
+        client.upload(Path("file.txt"), file_to=Path("/docs/file.txt"))
+        client.download(dlink, file_to=Path("output.txt"))
+"""
+
+__version__ = "0.1.0"
+
+from .client import BaiduPanClient
+from .errors import (
+    BaiduPanAPIError,
+    BaiduPanError,
+    BaiduPanNetworkError,
+    TokenExpiredError,
+)
+from .models import ApiFileListItem, ApiFileMeta, ApiQuotaInfo, UploadResult
+
+__all__ = [
+    # Client
+    "BaiduPanClient",
+    # Errors
+    "BaiduPanError",
+    "BaiduPanNetworkError",
+    "BaiduPanAPIError",
+    "TokenExpiredError",
+    # Models
+    "UploadResult",
+    "ApiFileMeta",
+    "ApiFileListItem",
+    "ApiQuotaInfo",
+]

bdds-0.1.0/src/bdds/_http.py

@@ -0,0 +1,156 @@
+"""HTTP 传输层 - Session 管理、请求封装、重试策略"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .errors import BaiduPanAPIError, BaiduPanNetworkError, TokenExpiredError
+
+logger = logging.getLogger("bdds")
+
+UserAgent = "netdisk;2.2.51.6;netdisk;10.0;PC;PC;Mac OS X 10.15.7;en-US"
+
+
+def _truncate_data(data: Any, max_len: int = 500) -> Any:
+    """递归截断超长字符串和二进制数据，用于日志安全输出"""
+    if isinstance(data, dict):
+        return {k: _truncate_data(v, max_len) for k, v in data.items()}
+    if isinstance(data, (list, tuple, set)):
+        return [_truncate_data(i, max_len) for i in data]
+    if isinstance(data, (bytes, bytearray)):
+        return f"<Binary Data: {len(data)} bytes>"
+    if isinstance(data, str) and len(data) > max_len:
+        return f"{data[:max_len]}... [truncated]"
+    return data
+
+
+class _HttpTransport:
+    """封装 requests.Session，提供自动 Token 注入、重试和错误处理"""
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        timeout: tuple[int, int] = (100, 600),
+    ) -> None:
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._session = self._init_session()
+        self._access_token: str | None = None
+        self._on_token_expired: Callable[[], str | None] | None = None
+
+    def _init_session(self) -> requests.Session:
+        session = requests.Session()
+        retries = Retry(
+            total=self._max_retries,
+            backoff_factor=1,
+            status_forcelist=[500, 502, 503, 504],
+            allowed_methods=["GET", "POST", "PUT", "DELETE"],
+            raise_on_status=True,
+        )
+        adapter = HTTPAdapter(max_retries=retries)
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+        session.headers.update({"User-Agent": UserAgent})
+        return session
+
+    @property
+    def session(self) -> requests.Session:
+        return self._session
+
+    def set_access_token(self, token: str | None) -> None:
+        self._access_token = token
+
+    def set_token_expired_callback(self, callback: Callable[[], str | None]) -> None:
+        """设置 Token 过期时的刷新回调，回调应返回新的 access_token"""
+        self._on_token_expired = callback
+
+    def request(self, method: str, url: str, **kwargs: Any) -> dict | requests.Response:
+        """
+        核心请求方法：
+        1. 自动注入 access_token
+        2. 处理网络层错误 (由 Session Retry 处理重试)
+        3. 处理业务层错误 (解析 errno)
+        4. Token 失效时自动刷新并重试一次
+        """
+        logger.debug("method:%s url:%s kwargs:%s", method, url, _truncate_data(kwargs))
+
+        if self._session is None:
+            raise RuntimeError("Transport is closed, cannot make requests")
+
+        if not self._access_token:
+            raise TokenExpiredError("Access token not initialized, please login first")
+
+        params = kwargs.pop("params", {})
+        params["access_token"] = self._access_token
+
+        kwargs.setdefault("timeout", self._timeout)
+
+        try:
+            response = self._session.request(method, url, params=params, **kwargs)
+            response.raise_for_status()
+
+            # 流式响应直接返回
+            if kwargs.get("stream"):
+                return response  # type: ignore[return-value]
+
+            try:
+                data = response.json()
+            except (json.JSONDecodeError, ValueError):
+                raise BaiduPanAPIError(-1, "Invalid JSON response")
+            logger.debug("method:%s url:%s response:%s", method, url, _truncate_data(data))
+
+        except requests.RequestException as e:
+            raise BaiduPanNetworkError(
+                f"Request failed: {e}", url=url
+            ) from e
+
+        # 业务错误检查
+        errno = data.get("errno", 0)
+        if errno != 0:
+            # Token 失效 (errno: -6 或 11)
+            if errno in (-6, 11) and self._on_token_expired:
+                logger.warning("Token expired during request, refreshing...")
+                new_token = self._on_token_expired()
+                if new_token:
+                    params["access_token"] = new_token
+                    try:
+                        response = self._session.request(
+                            method, url, params=params, **kwargs
+                        )
+                        response.raise_for_status()
+                        data = response.json()
+                    except requests.RequestException as e:
+                        raise BaiduPanNetworkError(
+                            f"Retry after token refresh failed: {e}", url=url
+                        ) from e
+                    except (json.JSONDecodeError, ValueError):
+                        raise BaiduPanAPIError(-1, "Invalid JSON response")
+
+                    if data.get("errno", 0) == 0:
+                        return data
+
+                # 刷新后仍失败
+                raise BaiduPanAPIError(
+                    data.get("errno", errno),
+                    data.get("errmsg", "Token refresh failed"),
+                    request_id=data.get("request_id", ""),
+                )
+
+            raise BaiduPanAPIError(
+                errno,
+                data.get("errmsg", "Unknown error"),
+                request_id=data.get("request_id", ""),
+            )
+
+        return data
+
+    def close(self) -> None:
+        if self._session is not None:
+            self._session.close()
+            self._session = None