abdds 0.1.0__tar.gz → 0.2.0__tar.gz

{abdds-0.1.0 → abdds-0.2.0}/PKG-INFO

@@ -1,20 +1,21 @@
 Metadata-Version: 2.4
 Name: abdds
-Version: 0.1.0
+Version: 0.2.0
 Summary: Async Baidu Disk SDK - 百度网盘异步 Python SDK
 Author: hochenggang
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/hochenggang
+Project-URL: Homepage, https://github.com/hochenggang/abdds
 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: Development Status :: 4 - Beta
 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: Programming Language :: Python :: 3.13
 Classifier: Framework :: AsyncIO
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
@@ -27,6 +28,8 @@ 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"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
 
 # abdds
 
@@ -54,74 +57,60 @@ pip install abdds
 from pathlib import Path
 from abdds import AsyncBaiduPanClient
 
-client = AsyncBaiduPanClient(
+async with 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)
+) as client:
+    if not client.is_authenticated:
+        print(f"请在浏览器打开: {client.auth_url}")
+        code = input("请输入授权码: ")
+        await client.fetch_token(code)
 ```
 
 Token 会自动保存到 `~/.baidupan/` 目录，下次启动无需重新授权。
 
-### 4. 使用 API
+### 3. 使用 API
 
 ```python
 # 查询空间配额
-quota = await client.get_quota()
-print(f"已用: {quota.used / 1024**3:.1f} GB / 总计: {quota.total / 1024**3:.1f} GB")
+q = await client.quota()
+print(f"已用: {q.used / 1024**3:.1f} GB / 总计: {q.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"))
+result = await client.upload(Path("data.bin"), remote_path="/backup/data.bin")
+result = await client.upload(b"hello world", remote_path="/hello.txt")
 
 # 获取文件元信息
-metas = await client.get_file_metas([result.fs_id])
+metas = await client.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"))
+# 下载文件到本地路径
+await client.download_to_file(dlink, Path("downloaded.txt"))
 
 # 流式下载（适合大文件或自定义处理）
-stream = await client.download(dlink)
-async for chunk in stream:
+async for chunk in client.download_stream(dlink):
+    process(chunk)
+
+# 带断点续传的流式下载
+async for chunk in client.download_stream_with_range(dlink, range=(1024, None)):
     process(chunk)
 
 # 列出文件
-items = await client.get_file_list("/apps/your_app_name/")
+items = await client.list_files("/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()
-    # ...
+await client.delete(["/apps/your_app_name/old_file.txt"])
 ```
 
 或使用异步工厂方法：
 
 ```python
 client = await AsyncBaiduPanClient.create(client_id, client_secret, app_name)
-quota = await client.get_quota()
+q = await client.quota()
 await client.close()
 ```
 
@@ -131,14 +120,17 @@ await client.close()
 
 | 方法 | 说明 |
 |------|------|
-| `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 upload(source, remote_path="")` | 异步上传数据。`source` 支持 `Path` / `bytes` / `Generator[bytes]` / `AsyncGenerator[bytes]`；`remote_path` 为远程路径字符串 |
+| `await download_to_file(dlink, local_path, *, chunk_size=1048576)` | 下载文件到本地路径，返回 `Path` |
+| `download_stream(dlink, *, chunk_size=1048576)` | 异步流式下载，返回 `AsyncGenerator[bytes]` |
+| `download_stream_with_range(dlink, range, *, chunk_size=1048576, max_retries=5)` | 带断点续传的异步流式下载，`range` 为 `(start, end)` 元组 |
+| `await quota()` | 获取空间配额，返回 `ApiQuotaInfo` |
+| `await file_metas(fsids)` | 获取文件元信息（含 dlink），返回 `list[ApiFileMeta]` |
+| `await list_files(path="/")` | 列出目录文件，返回 `list[ApiFileListItem]` |
+| `await delete(paths)` | 批量删除文件 |
 | `await fetch_token(code)` | 通过授权码获取 Token |
 | `await refresh_token()` | 刷新 Token |
+| `is_authenticated` | 是否已认证（属性） |
 | `await close()` | 关闭客户端 |
 
 ### 异常体系
@@ -158,7 +150,7 @@ BaiduPanError
 - **自动重试** — 网络请求自动重试（可配置次数）
 - **Token 管理** — 自动持久化、自动刷新、文件权限限制
 - **分片上传** — 大文件自动分片上传（4MB 分片）
-- **流式下载** — 支持断点续传、指数重试
+- **流式下载** — 支持断点续传、Range 分片、指数重试
 - **类型安全** — 完整类型标注，支持 PEP 561 (`py.typed`)
 - **报错清晰** — 异常包含 `errno`、`errmsg`、`request_id`、`url` 等上下文
 
@@ -184,7 +176,6 @@ pip install -e ".[dev]"
 python -m pytest -v
 
 # 构建
-pip install build twine
 python -m build
 ```
 

{abdds-0.1.0 → abdds-0.2.0}/README.md

@@ -24,74 +24,60 @@ pip install abdds
 from pathlib import Path
 from abdds import AsyncBaiduPanClient
 
-client = AsyncBaiduPanClient(
+async with 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)
+) as client:
+    if not client.is_authenticated:
+        print(f"请在浏览器打开: {client.auth_url}")
+        code = input("请输入授权码: ")
+        await client.fetch_token(code)
 ```
 
 Token 会自动保存到 `~/.baidupan/` 目录，下次启动无需重新授权。
 
-### 4. 使用 API
+### 3. 使用 API
 
 ```python
 # 查询空间配额
-quota = await client.get_quota()
-print(f"已用: {quota.used / 1024**3:.1f} GB / 总计: {quota.total / 1024**3:.1f} GB")
+q = await client.quota()
+print(f"已用: {q.used / 1024**3:.1f} GB / 总计: {q.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"))
+result = await client.upload(Path("data.bin"), remote_path="/backup/data.bin")
+result = await client.upload(b"hello world", remote_path="/hello.txt")
 
 # 获取文件元信息
-metas = await client.get_file_metas([result.fs_id])
+metas = await client.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"))
+# 下载文件到本地路径
+await client.download_to_file(dlink, Path("downloaded.txt"))
 
 # 流式下载（适合大文件或自定义处理）
-stream = await client.download(dlink)
-async for chunk in stream:
+async for chunk in client.download_stream(dlink):
+    process(chunk)
+
+# 带断点续传的流式下载
+async for chunk in client.download_stream_with_range(dlink, range=(1024, None)):
     process(chunk)
 
 # 列出文件
-items = await client.get_file_list("/apps/your_app_name/")
+items = await client.list_files("/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()
-    # ...
+await client.delete(["/apps/your_app_name/old_file.txt"])
 ```
 
 或使用异步工厂方法：
 
 ```python
 client = await AsyncBaiduPanClient.create(client_id, client_secret, app_name)
-quota = await client.get_quota()
+q = await client.quota()
 await client.close()
 ```
 
@@ -101,14 +87,17 @@ await client.close()
 
 | 方法 | 说明 |
 |------|------|
-| `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 upload(source, remote_path="")` | 异步上传数据。`source` 支持 `Path` / `bytes` / `Generator[bytes]` / `AsyncGenerator[bytes]`；`remote_path` 为远程路径字符串 |
+| `await download_to_file(dlink, local_path, *, chunk_size=1048576)` | 下载文件到本地路径，返回 `Path` |
+| `download_stream(dlink, *, chunk_size=1048576)` | 异步流式下载，返回 `AsyncGenerator[bytes]` |
+| `download_stream_with_range(dlink, range, *, chunk_size=1048576, max_retries=5)` | 带断点续传的异步流式下载，`range` 为 `(start, end)` 元组 |
+| `await quota()` | 获取空间配额，返回 `ApiQuotaInfo` |
+| `await file_metas(fsids)` | 获取文件元信息（含 dlink），返回 `list[ApiFileMeta]` |
+| `await list_files(path="/")` | 列出目录文件，返回 `list[ApiFileListItem]` |
+| `await delete(paths)` | 批量删除文件 |
 | `await fetch_token(code)` | 通过授权码获取 Token |
 | `await refresh_token()` | 刷新 Token |
+| `is_authenticated` | 是否已认证（属性） |
 | `await close()` | 关闭客户端 |
 
 ### 异常体系
@@ -128,7 +117,7 @@ BaiduPanError
 - **自动重试** — 网络请求自动重试（可配置次数）
 - **Token 管理** — 自动持久化、自动刷新、文件权限限制
 - **分片上传** — 大文件自动分片上传（4MB 分片）
-- **流式下载** — 支持断点续传、指数重试
+- **流式下载** — 支持断点续传、Range 分片、指数重试
 - **类型安全** — 完整类型标注，支持 PEP 561 (`py.typed`)
 - **报错清晰** — 异常包含 `errno`、`errmsg`、`request_id`、`url` 等上下文
 
@@ -154,7 +143,6 @@ pip install -e ".[dev]"
 python -m pytest -v
 
 # 构建
-pip install build twine
 python -m build
 ```
 

{abdds-0.1.0 → abdds-0.2.0}/pyproject.toml

@@ -1,51 +1,54 @@
-[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"
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abdds"
+version = "0.2.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 :: 4 - Beta",
+    "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",
+    "Programming Language :: Python :: 3.13",
+    "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",
+    "build>=1.0",
+    "twine>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hochenggang/abdds"
+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 → abdds-0.2.0}/src/abdds/__init__.py

@@ -4,12 +4,18 @@
 
 Usage::
 
+    from pathlib import Path
     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"))
+        if not client.is_authenticated:
+            print(client.auth_url)
+            code = input("Enter code: ")
+            await client.fetch_token(code)
+
+        q = await client.quota()
+        result = await client.upload(Path("file.txt"), remote_path="/docs/file.txt")
+        await client.download_to_file(dlink, Path("output.txt"))
 """
 
 __version__ = "0.1.0"

{abdds-0.1.0 → abdds-0.2.0}/src/abdds/_http.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any, Awaitable, Callable
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 import httpx
 
@@ -12,7 +13,7 @@ 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"
+_USER_AGENT = "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:
@@ -50,7 +51,7 @@ class _HttpTransport:
         client = httpx.AsyncClient(
             transport=transport,
             timeout=httpx.Timeout(self._timeout[1], connect=self._timeout[0]),
-            headers={"User-Agent": UserAgent},
+            headers={"User-Agent": _USER_AGENT},
             follow_redirects=True,
         )
         return client