abdds 0.1.0__tar.gz

abdds-0.1.0/PKG-INFO

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

abdds-0.1.0/README.md

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

abdds-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abdds"
+version = "0.1.0"
+description = "Async 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", "async", "aio"]
+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",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx[http2]>=0.24",
+    "aiofiles>=23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+    "pytest-mock>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hochenggang"
+Repository = "https://github.com/hochenggang/abdds"
+"Bug Tracker" = "https://github.com/hochenggang/abdds/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

abdds-0.1.0/setup.cfg

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

abdds-0.1.0/src/abdds/__init__.py

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

abdds-0.1.0/src/abdds/_http.py

@@ -0,0 +1,165 @@
+"""HTTP 传输层 - 异步 Session 管理、请求封装、重试策略"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Awaitable, Callable
+
+import httpx
+
+from .errors import BaiduPanAPIError, BaiduPanNetworkError, TokenExpiredError
+
+logger = logging.getLogger("abdds")
+
+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:
+    """封装 httpx.AsyncClient，提供自动 Token 注入、重试和错误处理"""
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        timeout: tuple[int, int] = (100, 600),
+    ) -> None:
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+        self._closed: bool = False
+        self._access_token: str | None = None
+        self._on_token_expired: Callable[[], Awaitable[str | None]] | None = None
+
+    def _init_client(self) -> httpx.AsyncClient:
+        transport = httpx.AsyncHTTPTransport(
+            retries=self._max_retries,
+        )
+        client = httpx.AsyncClient(
+            transport=transport,
+            timeout=httpx.Timeout(self._timeout[1], connect=self._timeout[0]),
+            headers={"User-Agent": UserAgent},
+            follow_redirects=True,
+        )
+        return client
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        """获取或初始化 AsyncClient"""
+        if self._closed:
+            raise RuntimeError("Transport is closed, cannot make requests")
+        if self._client is None:
+            self._client = self._init_client()
+        return self._client
+
+    def set_access_token(self, token: str | None) -> None:
+        self._access_token = token
+
+    def set_token_expired_callback(
+        self, callback: Callable[[], Awaitable[str | None]]
+    ) -> None:
+        """设置 Token 过期时的异步刷新回调，回调应返回新的 access_token"""
+        self._on_token_expired = callback
+
+    async def request(
+        self, method: str, url: str, **kwargs: Any
+    ) -> dict | httpx.Response:
+        """
+        核心异步请求方法：
+        1. 自动注入 access_token
+        2. 处理网络层错误 (由 httpx transport retries 处理重试)
+        3. 处理业务层错误 (解析 errno)
+        4. Token 失效时自动刷新并重试一次
+        """
+        logger.debug("method:%s url:%s kwargs:%s", method, url, _truncate_data(kwargs))
+
+        if self._closed:
+            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
+
+        try:
+            response = await self.client.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 httpx.HTTPStatusError as e:
+            raise BaiduPanNetworkError(
+                f"HTTP {e.response.status_code}: {e}", url=url,
+                status_code=e.response.status_code,
+            ) from e
+        except httpx.RequestError 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 = await self._on_token_expired()
+                if new_token:
+                    params["access_token"] = new_token
+                    try:
+                        response = await self.client.request(
+                            method, url, params=params, **kwargs
+                        )
+                        response.raise_for_status()
+                        data = response.json()
+                    except httpx.RequestError 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
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None