bdds 0.1.0__py3-none-any.whl

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/_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

bdds/client.py

@@ -0,0 +1,390 @@
+"""BaiduPanClient - 百度网盘 Python SDK 主类"""
+
+from __future__ import annotations
+
+import json
+import logging
+import stat
+import time
+from pathlib import Path, PurePosixPath
+from typing import Generator
+from urllib.parse import quote
+
+import requests
+
+from ._http import _HttpTransport
+from .download import download as _download
+from .errors import BaiduPanNetworkError, TokenExpiredError
+from .models import ApiFileListItem, ApiFileMeta, ApiQuotaInfo, UploadResult
+from .upload import upload as _upload
+from .upload import UploadSource, _is_generator
+
+logger = logging.getLogger("bdds")
+
+
+class BaiduPanClient:
+    """
+    百度网盘 Python SDK 客户端
+
+    具备自动重试、Token 管理、流式下载和分片上传。
+
+    Usage::
+
+        with BaiduPanClient(client_id, client_secret, app_name) as client:
+            if not client.access_token:
+                print(client.auth_url)
+                code = input("Enter code: ")
+                client.fetch_token(code)
+
+            quota = client.get_quota()
+            result = client.upload(Path("local_file.txt"))
+    """
+
+    HOST_OAUTH = "https://openapi.baidu.com/oauth/2.0"
+    HOST_PAN = "https://pan.baidu.com"
+
+    URL_QUOTA = f"{HOST_PAN}/api/quota"
+    URL_FILE = f"{HOST_PAN}/rest/2.0/xpan/file"
+    URL_MULTIMEDIA = f"{HOST_PAN}/rest/2.0/xpan/multimedia"
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        app_name: str,
+        config_dir: Path | None = None,
+        max_retries: int = 3,
+        timeout: tuple[int, int] | None = None,
+    ) -> None:
+        """
+        初始化百度网盘客户端
+
+        Args:
+            client_id: 百度开放平台应用的 API Key
+            client_secret: 百度开放平台应用的 Secret Key
+            app_name: 应用名称
+            config_dir: Token 存储目录，默认 ~/.baidupan
+            max_retries: 请求重试次数，默认 3
+            timeout: 请求超时 (connect, read)，默认 (100, 600)
+        """
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self.app_name = app_name
+        self.pan_dir_base = f"/apps/{app_name}"
+
+        if config_dir is None:
+            config_dir = Path.home() / ".baidupan"
+        self.config_dir = config_dir
+        self._token_file = self.config_dir / f"access_token_{client_id}.json"
+
+        self._token_data: dict = {}
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+
+        # 初始化 HTTP 传输层
+        self._transport = _HttpTransport(
+            max_retries=max_retries,
+            timeout=timeout or (100, 600),
+        )
+        self._transport.set_token_expired_callback(self._handle_token_expired)
+
+        # 加载已保存的 Token
+        self._load_token()
+
+    # ---- 上下文管理器 ----
+
+    def close(self) -> None:
+        """关闭客户端，释放资源"""
+        self._transport.close()
+
+    def __enter__(self) -> BaiduPanClient:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: object) -> bool | None:
+        self.close()
+        return False
+
+    # ---- Token 管理 ----
+
+    @property
+    def access_token(self) -> str | None:
+        """当前 access_token（只读）"""
+        return self._access_token
+
+    @property
+    def auth_url(self) -> str:
+        """生成用户授权 URL"""
+        return (
+            f"{self.HOST_OAUTH}/authorize?"
+            f"response_type=code&client_id={self._client_id}&redirect_uri=oob&scope=basic,netdisk"
+        )
+
+    def fetch_token(self, code: str) -> None:
+        """
+        通过授权码获取 Access Token
+
+        Args:
+            code: 用户授权后获得的授权码
+        """
+        url = f"{self.HOST_OAUTH}/token"
+        params = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "redirect_uri": "oob",
+        }
+        try:
+            resp = self._transport.session.get(url, params=params, timeout=10)
+            resp.raise_for_status()
+            result = resp.json()
+        except requests.RequestException as e:
+            raise BaiduPanNetworkError(f"Fetch token failed: {e}") from e
+
+        # 检查 API 层面错误
+        if "error" in result:
+            raise TokenExpiredError(
+                f"Fetch token failed: {result.get('error_description', result['error'])}"
+            )
+        self._save_token(result)
+
+    def refresh_token(self) -> str:
+        """
+        刷新 Access Token
+
+        Returns:
+            新的 access_token
+
+        Raises:
+            TokenExpiredError: 无 refresh_token 可用
+        """
+        if not self._refresh_token:
+            raise TokenExpiredError("No refresh token available, please re-login")
+
+        url = f"{self.HOST_OAUTH}/token"
+        params = {
+            "grant_type": "refresh_token",
+            "refresh_token": self._refresh_token,
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        try:
+            resp = self._transport.session.get(url, params=params, timeout=10)
+            resp.raise_for_status()
+            result = resp.json()
+        except requests.RequestException as e:
+            raise BaiduPanNetworkError(f"Refresh token failed: {e}") from e
+
+        # 检查 API 层面错误
+        if "error" in result:
+            raise TokenExpiredError(
+                f"Refresh token failed: {result.get('error_description', result['error'])}"
+            )
+        self._save_token(result)
+        return self._access_token  # type: ignore[return-value]
+
+    def _handle_token_expired(self) -> str | None:
+        """Token 过期回调，供 _HttpTransport 调用"""
+        try:
+            return self.refresh_token()
+        except (TokenExpiredError, BaiduPanNetworkError):
+            logger.error("Token refresh failed in auto-retry")
+            return None
+
+    def _load_token(self) -> None:
+        """从本地文件加载 Token"""
+        if not self._token_file.exists():
+            return
+        try:
+            data = json.loads(self._token_file.read_text(encoding="utf-8"))
+            self._token_data = data
+            self._access_token = data.get("access_token")
+            self._refresh_token = data.get("refresh_token")
+            self._transport.set_access_token(self._access_token)
+        except (json.JSONDecodeError, IOError) as e:
+            logger.error("Failed to load token: %s", e)
+
+    def _save_token(self, data: dict) -> None:
+        """持久化保存 Token"""
+        if "access_token" not in data:
+            error_desc = data.get("error_description", data.get("Error", "Unknown error"))
+            raise TokenExpiredError(f"Token response missing access_token: {error_desc}")
+
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        data["update_at"] = int(time.time())
+        self._token_data = data
+        self._access_token = data["access_token"]
+        self._refresh_token = data.get("refresh_token")
+        self._transport.set_access_token(self._access_token)
+
+        self._token_file.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        # 限制文件权限为仅拥有者可读写
+        try:
+            self._token_file.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass  # Windows 不完全支持 chmod
+
+        logger.info("Access token saved")
+
+    # ---- 业务 API ----
+
+    def get_quota(self) -> ApiQuotaInfo:
+        """
+        获取网盘空间配额
+
+        https://pan.baidu.com/union/doc/Cksg0s9ic
+        """
+        data = self._transport.request("GET", self.URL_QUOTA)
+        return ApiQuotaInfo(total=data.get("total", 0), used=data.get("used", 0))
+
+    def get_file_metas(self, fsids: list[int]) -> list[ApiFileMeta]:
+        """
+        获取文件元信息
+
+        https://pan.baidu.com/union/doc/Fksg0sbcm
+
+        Args:
+            fsids: 文件 ID 列表
+        """
+        if not fsids:
+            return []
+
+        params = {"method": "filemetas", "fsids": json.dumps(fsids), "dlink": 1}
+        data = self._transport.request("GET", self.URL_MULTIMEDIA, params=params)
+        items = data.get("list", [])
+
+        return [
+            ApiFileMeta(
+                fs_id=item["fs_id"],
+                filename=item["filename"],
+                path=item["path"],
+                size=item["size"],
+                md5=item.get("md5", ""),
+                dlink=item.get("dlink", ""),
+            )
+            for item in items
+        ]
+
+    def get_file_list(self, path: str) -> list[ApiFileListItem]:
+        """
+        获取指定目录下的文件列表
+
+        https://pan.baidu.com/union/doc/nksg0sat9
+
+        Args:
+            path: 目录路径
+        """
+        params = {"method": "list", "dir": quote(path)}
+        data = self._transport.request("GET", self.URL_FILE, params=params)
+        items = data.get("list", [])
+
+        return [
+            ApiFileListItem(
+                fs_id=item["fs_id"],
+                filename=item["server_filename"],
+                path=item["path"],
+                size=item["size"],
+                md5=item.get("md5", ""),
+                is_dir=item.get("isdir", 0),
+            )
+            for item in items
+        ]
+
+    def delete_files(self, file_paths: list[str]) -> None:
+        """
+        批量删除文件
+
+        https://pan.baidu.com/union/doc/mksg0s9l4
+
+        Args:
+            file_paths: 要删除的文件路径列表
+        """
+        if not file_paths:
+            return
+        params = {"method": "filemanager", "opera": "delete"}
+        data = {"async": 2, "filelist": json.dumps(file_paths)}
+        self._transport.request("POST", self.URL_FILE, params=params, data=data)
+        logger.info("Deleted %d file(s)", len(file_paths))
+
+    # ---- 上传 ----
+
+    def upload(
+        self,
+        file_from: UploadSource,
+        file_to: Path | None = None,
+    ) -> UploadResult:
+        """
+        上传数据到百度网盘
+
+        - 小文件 (<=4MB): 单步上传
+        - 大文件 (>4MB): 分片上传
+
+        Args:
+            file_from: 数据来源，支持 Path / bytes / Generator[bytes]
+            file_to: 远程路径 (Path)，拼接在 /apps/{app_name} 之后。
+                默认使用 file_from 的文件名 (Path 时) 或 "upload"
+
+        Returns:
+            UploadResult: 上传结果
+
+        Raises:
+            TypeError: file_from 或 file_to 类型不正确
+        """
+        # 类型校验
+        if not isinstance(file_from, (Path, bytes)) and not _is_generator(file_from):
+            raise TypeError(
+                f"file_from must be Path, bytes, or Generator[bytes], "
+                f"got {type(file_from).__name__}"
+            )
+        if file_to is not None and not isinstance(file_to, Path):
+            raise TypeError(
+                f"file_to must be Path or None, got {type(file_to).__name__}"
+            )
+
+        if isinstance(file_from, Path):
+            default_name = file_from.name
+        else:
+            default_name = "upload"
+
+        if file_to is None:
+            remote_path = PurePosixPath(f"/{default_name}")
+        else:
+            # 将 Path 转为 PurePosixPath 以确保 POSIX 风格
+            remote_path = PurePosixPath(file_to.as_posix())
+            if not remote_path.is_absolute():
+                remote_path = PurePosixPath(f"/{remote_path}")
+
+        return _upload(self._transport, file_from, remote_path, self.pan_dir_base)
+
+    # ---- 下载 ----
+
+    def download(
+        self,
+        dlink: str,
+        file_to: Path | None = None,
+        chunk_size: int = 1024 * 1024,
+    ) -> Generator[bytes, None, None] | Path:
+        """
+        下载文件
+
+        - file_to=None: 返回字节迭代器 (流式下载)
+        - file_to=Path: 下载到本地文件，返回 Path
+
+        https://pan.baidu.com/union/doc/pkuo3snyp
+
+        Args:
+            dlink: 下载链接 (通过 get_file_metas 获取)
+            file_to: 本地保存路径 (Path)，为 None 时返回迭代器
+            chunk_size: 分块大小，默认 1MB
+
+        Returns:
+            Generator[bytes] 当 file_to=None，Path 当 file_to 指定路径
+
+        Raises:
+            TypeError: file_to 类型不正确
+        """
+        if file_to is not None and not isinstance(file_to, Path):
+            raise TypeError(
+                f"file_to must be Path or None, got {type(file_to).__name__}"
+            )
+        return _download(self._transport, dlink, file_to, chunk_size)

bdds/download.py

@@ -0,0 +1,124 @@
+"""下载相关逻辑 - 流式下载、断点续传"""
+
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Generator
+
+import requests
+
+from ._http import UserAgent
+from .errors import BaiduPanNetworkError
+
+if TYPE_CHECKING:
+    from ._http import _HttpTransport
+
+logger = logging.getLogger("bdds")
+
+
+def download(
+    transport: _HttpTransport,
+    dlink: str,
+    file_to: Path | None = None,
+    chunk_size: int = 1024 * 1024,
+    max_retries: int = 5,
+) -> Generator[bytes, None, None] | Path:
+    """
+    下载文件
+
+    - file_to=None: 返回字节迭代器 (流式下载)
+    - file_to=Path: 下载到本地文件，返回 Path
+
+    Args:
+        transport: HTTP 传输层
+        dlink: 下载链接
+        file_to: 本地保存路径 (Path)，为 None 时返回迭代器
+        chunk_size: 分块大小，默认 1MB
+        max_retries: 最大重试次数，默认 5
+
+    Returns:
+        Generator[bytes] 当 file_to=None，Path 当 file_to 指定路径
+
+    Raises:
+        TypeError: file_to 类型不正确
+    """
+    if file_to is not None and not isinstance(file_to, Path):
+        raise TypeError(
+            f"file_to must be Path or None, got {type(file_to).__name__}"
+        )
+    if chunk_size <= 0:
+        raise ValueError(f"chunk_size must be positive, got {chunk_size}")
+
+    stream = _download_stream(transport, dlink, chunk_size, max_retries)
+
+    if file_to is None:
+        return stream
+
+    file_to.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(file_to, "wb") as f:
+        for chunk in stream:
+            f.write(chunk)
+
+    logger.info("Downloaded to %s", file_to)
+    return file_to
+
+
+def _download_stream(
+    transport: _HttpTransport,
+    dlink: str,
+    chunk_size: int = 1024 * 1024,
+    max_retries: int = 5,
+) -> Generator[bytes, None, None]:
+    """
+    通过 dlink 流式下载文件，支持断点续传和指数重试
+    """
+    downloaded_bytes = 0
+    retry_count = 0
+
+    while True:
+        try:
+            headers = {"User-Agent": UserAgent}
+
+            if downloaded_bytes > 0:
+                headers["Range"] = f"bytes={downloaded_bytes}-"
+                logger.info("Resuming download from byte %d...", downloaded_bytes)
+
+            response = transport.session.get(
+                dlink,
+                headers=headers,
+                params={"access_token": transport._access_token},
+                stream=True,
+                timeout=(15, 60),
+            )
+            response.raise_for_status()
+
+            # 请求了 Range 但服务器返回 200，说明不支持断点续传
+            if downloaded_bytes > 0 and response.status_code == 200:
+                logger.warning("Server does not support Range, restarting from beginning")
+                downloaded_bytes = 0
+
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                if chunk:
+                    yield chunk
+                    downloaded_bytes += len(chunk)
+
+            break  # 下载完成
+
+        except requests.RequestException as e:
+            retry_count += 1
+            if retry_count > max_retries:
+                raise BaiduPanNetworkError(
+                    f"Download failed after {max_retries} retries "
+                    f"({downloaded_bytes} bytes downloaded): {e}",
+                    url=dlink,
+                ) from e
+
+            wait_time = 2 ** (retry_count - 1)
+            logger.warning(
+                "Download interrupted at %d bytes: %s. Retrying in %ds...",
+                downloaded_bytes, e, wait_time,
+            )
+            time.sleep(wait_time)

bdds/errors.py

@@ -0,0 +1,38 @@
+"""bdds 异常体系"""
+
+
+class BaiduPanError(Exception):
+    """SDK 基础异常"""
+
+
+class BaiduPanNetworkError(BaiduPanError):
+    """网络通信异常"""
+
+    def __init__(
+        self, message: str, *, url: str = "", status_code: int | None = None
+    ):
+        self.url = url
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class BaiduPanAPIError(BaiduPanError):
+    """API 业务异常 (errno != 0)"""
+
+    def __init__(
+        self, errno: int, errmsg: str = "", *, request_id: str = ""
+    ):
+        self.errno = errno
+        self.errmsg = errmsg
+        self.request_id = request_id
+        detail = f"[errno:{errno}] {errmsg}"
+        if request_id:
+            detail += f" (request_id:{request_id})"
+        super().__init__(detail)
+
+
+class TokenExpiredError(BaiduPanError):
+    """Token 过期或无效"""
+
+    def __init__(self, message: str = "Access token expired or invalid"):
+        super().__init__(message)

bdds/models.py

@@ -0,0 +1,58 @@
+"""bdds 数据模型"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class UploadResult:
+    """上传结果"""
+
+    fs_id: int | None
+    md5: str
+    path: str
+    size: int | None
+
+
+@dataclass
+class _ApiPreUploadResponse:
+    """预上传响应（内部模型）"""
+
+    path: str
+    uploadid: str
+    block_list: list[int]
+    block_list_md5: list[str]
+    file_size: int
+
+
+@dataclass
+class ApiFileMeta:
+    """文件元信息"""
+
+    md5: str
+    path: str
+    size: int
+    fs_id: int
+    dlink: str
+    filename: str
+
+
+@dataclass
+class ApiFileListItem:
+    """文件列表项"""
+
+    md5: str
+    path: str
+    size: int
+    fs_id: int
+    is_dir: int
+    filename: str
+
+
+@dataclass
+class ApiQuotaInfo:
+    """空间配额信息"""
+
+    total: int
+    used: int

bdds/upload.py

@@ -0,0 +1,308 @@
+"""上传相关逻辑 - 小文件单步上传 & 大文件分片上传"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import logging
+from collections.abc import Generator as _GeneratorABC
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Generator
+
+from .errors import BaiduPanAPIError
+from .models import _ApiPreUploadResponse, UploadResult
+
+if TYPE_CHECKING:
+    from ._http import _HttpTransport
+
+logger = logging.getLogger("bdds")
+
+BLOCK_SIZE = 4 * 1024 * 1024  # 4MB
+
+# file_from 参数可接受类型
+UploadSource = Path | bytes | Generator[bytes, None, None]
+
+
+def upload(
+    transport: _HttpTransport,
+    file_from: UploadSource,
+    to: PurePosixPath,
+    pan_dir_base: str,
+) -> UploadResult:
+    """
+    上传数据到百度网盘
+
+    - 小文件 (<=4MB): 单步上传 (precreate + direct upload)
+    - 大文件 (>4MB):  分片上传 (precreate + 分片 + merge)
+
+    Args:
+        transport: HTTP 传输层
+        file_from: 数据来源，支持 Path / bytes / Generator[bytes]
+        to: 远程路径 (PurePosixPath)，将拼接在 /apps/{app_name} 之后
+        pan_dir_base: 应用目录前缀，如 /apps/myapp
+
+    Raises:
+        TypeError: file_from 类型不正确
+    """
+    # 类型校验
+    if not isinstance(file_from, (Path, bytes)) and not _is_generator(file_from):
+        raise TypeError(
+            f"file_from must be Path, bytes, or Generator[bytes], "
+            f"got {type(file_from).__name__}"
+        )
+
+    # 构造完整远程路径: pan_dir_base + to
+    remote_path = f"{pan_dir_base}{to.as_posix()}"
+
+    # 根据 file_from 类型提取数据
+    if isinstance(file_from, Path):
+        if not file_from.is_file():
+            raise FileNotFoundError(f"File not found: {file_from}")
+        file_size = file_from.stat().st_size
+        if file_size == 0:
+            raise ValueError("Cannot upload empty file (0 bytes)")
+        block_md5_list = _calculate_file_md5_blocks(file_from)
+    elif isinstance(file_from, bytes):
+        file_size = len(file_from)
+        if file_size == 0:
+            raise ValueError("Cannot upload empty data (0 bytes)")
+        block_md5_list = _calculate_bytes_md5_blocks(file_from)
+    elif _is_generator(file_from):
+        # 生成器需要消费一次来计算大小和 MD5，缓存在内存中
+        chunks: list[bytes] = []
+        file_size = 0
+        md5_list: list[str] = []
+        current_chunk = io.BytesIO()
+
+        for data in file_from:
+            current_chunk.write(data)
+            file_size += len(data)
+            if current_chunk.tell() >= BLOCK_SIZE:
+                block_data = current_chunk.getvalue()
+                chunks.append(block_data)
+                md5_list.append(hashlib.md5(block_data).hexdigest())
+                current_chunk = io.BytesIO()
+
+        # 处理最后不足一个 BLOCK_SIZE 的数据
+        remaining = current_chunk.getvalue()
+        if remaining:
+            chunks.append(remaining)
+            md5_list.append(hashlib.md5(remaining).hexdigest())
+
+        block_md5_list = md5_list
+
+        if file_size == 0:
+            raise ValueError("Cannot upload empty generator (0 bytes yielded)")
+
+        # 将 chunks 重新组装为生成器供上传使用
+        file_from = (chunk for chunk in chunks)
+    else:
+        raise TypeError(f"file_from must be Path, bytes, or Generator[bytes], got {type(file_from).__name__}")
+
+    logger.info("Uploading -> %s (%d bytes)", remote_path, file_size)
+
+    # 预上传
+    pre_resp = _api_pre_create(transport, remote_path, file_size, block_md5_list)
+
+    # 获取上传服务器
+    upload_host = _get_upload_server(transport, remote_path, pre_resp.uploadid)
+
+    if file_size <= BLOCK_SIZE:
+        return _upload_small(transport, upload_host, pre_resp, file_from, file_size)
+    else:
+        return _upload_multipart(transport, upload_host, pre_resp, file_from, block_md5_list)
+
+
+def _is_generator(obj: object) -> bool:
+    """判断对象是否为生成器"""
+    return isinstance(obj, _GeneratorABC)
+
+
+def _upload_small(
+    transport: _HttpTransport,
+    host: str,
+    pre_resp: _ApiPreUploadResponse,
+    file_from: UploadSource,
+    file_size: int,
+) -> UploadResult:
+    """小文件单步上传"""
+    url = f"{host}/rest/2.0/pcs/file"
+    params = {"method": "upload", "path": pre_resp.path}
+
+    if isinstance(file_from, Path):
+        data = file_from.read_bytes()
+    elif isinstance(file_from, bytes):
+        data = file_from
+    else:
+        # 生成器
+        data = b"".join(file_from)
+
+    files = {"file": ("blob", data)}
+    resp = transport.request("POST", url, params=params, files=files)
+    return UploadResult(
+        fs_id=resp.get("fs_id"),
+        md5=resp.get("md5"),
+        path=resp.get("path"),
+        size=resp.get("size"),
+    )
+
+
+def _upload_multipart(
+    transport: _HttpTransport,
+    host: str,
+    pre_resp: _ApiPreUploadResponse,
+    file_from: UploadSource,
+    block_md5_list: list[str],
+) -> UploadResult:
+    """大文件分片上传"""
+    url_prefix = f"{host}/rest/2.0/pcs/superfile2"
+
+    if isinstance(file_from, Path):
+        with open(file_from, "rb") as f:
+            for idx in range(len(block_md5_list)):
+                f.seek(idx * BLOCK_SIZE)
+                chunk_data = f.read(BLOCK_SIZE)
+                _upload_part(transport, url_prefix, pre_resp, idx, chunk_data)
+    elif isinstance(file_from, bytes):
+        for idx in range(len(block_md5_list)):
+            chunk_data = file_from[idx * BLOCK_SIZE : (idx + 1) * BLOCK_SIZE]
+            _upload_part(transport, url_prefix, pre_resp, idx, chunk_data)
+    else:
+        # 生成器（已在上层收集为 chunks 列表后重建的生成器）
+        for idx, chunk_data in enumerate(file_from):
+            _upload_part(transport, url_prefix, pre_resp, idx, chunk_data)
+
+    # 合并分片
+    return _api_create_file(
+        transport, pre_resp.path, pre_resp.uploadid, pre_resp.file_size, block_md5_list
+    )
+
+
+def _upload_part(
+    transport: _HttpTransport,
+    url_prefix: str,
+    pre_resp: _ApiPreUploadResponse,
+    partseq: int,
+    chunk_data: bytes,
+) -> None:
+    """上传单个分片"""
+    logger.debug("Uploading part %d", partseq + 1)
+    params = {
+        "method": "upload",
+        "type": "tmpfile",
+        "path": pre_resp.path,
+        "uploadid": pre_resp.uploadid,
+        "partseq": str(partseq),
+    }
+    files = {"file": ("blob", chunk_data)}
+    transport.request("POST", url_prefix, params=params, files=files)
+
+
+def _api_pre_create(
+    transport: _HttpTransport,
+    path: str,
+    size: int,
+    block_list: list[str],
+) -> _ApiPreUploadResponse:
+    """预上传 - 通知云端新建上传任务"""
+    params = {"method": "precreate"}
+    data = {
+        "path": path,
+        "size": size,
+        "isdir": "0",
+        "autoinit": "1",
+        "rtype": "3",  # 覆盖
+        "block_list": json.dumps(block_list),
+    }
+    resp = transport.request("POST", "https://pan.baidu.com/rest/2.0/xpan/file", params=params, data=data)
+    return _ApiPreUploadResponse(
+        path=path,
+        uploadid=resp["uploadid"],
+        block_list=resp.get("block_list", []),
+        block_list_md5=block_list,
+        file_size=size,
+    )
+
+
+def _get_upload_server(transport: _HttpTransport, path: str, uploadid: str) -> str:
+    """获取上传服务器域名"""
+    params = {
+        "method": "locateupload",
+        "appid": "250528",
+        "path": path,
+        "uploadid": uploadid,
+        "upload_version": "2.0",
+    }
+    resp = transport.request("GET", "https://pan.baidu.com/rest/2.0/xpan/file", params=params)
+    servers = resp.get("servers", [])
+    if not servers:
+        raise BaiduPanAPIError(-1, "No upload server available")
+
+    for s in servers:
+        server_url = s.get("server", "")
+        if server_url.startswith("https"):
+            return server_url
+
+    # 降级：返回第一个有效 server
+    for s in servers:
+        server_url = s.get("server", "")
+        if server_url:
+            return server_url
+
+    raise BaiduPanAPIError(-1, "No valid upload server in response")
+
+
+def _api_create_file(
+    transport: _HttpTransport,
+    path: str,
+    uploadid: str,
+    size: int,
+    block_list: list[str],
+) -> UploadResult:
+    """合并分片完成上传"""
+    params = {"method": "create"}
+    data = {
+        "path": path,
+        "size": size,
+        "isdir": "0",
+        "rtype": "3",
+        "uploadid": uploadid,
+        "block_list": json.dumps(block_list),
+    }
+    resp = transport.request("POST", "https://pan.baidu.com/rest/2.0/xpan/file", params=params, data=data)
+    return UploadResult(
+        fs_id=resp.get("fs_id"),
+        md5=resp.get("md5"),
+        path=resp.get("path"),
+        size=resp.get("size"),
+    )
+
+
+def _calculate_file_md5_blocks(file_path: Path) -> list[str]:
+    """高效计算文件分片 MD5"""
+    file_size = file_path.stat().st_size
+
+    with open(file_path, "rb") as f:
+        if file_size <= BLOCK_SIZE:
+            return [hashlib.md5(f.read()).hexdigest()]
+
+        md5_list: list[str] = []
+        while True:
+            chunk = f.read(BLOCK_SIZE)
+            if not chunk:
+                break
+            md5_list.append(hashlib.md5(chunk).hexdigest())
+
+    return md5_list
+
+
+def _calculate_bytes_md5_blocks(data: bytes) -> list[str]:
+    """计算 bytes 对象的分片 MD5"""
+    if len(data) <= BLOCK_SIZE:
+        return [hashlib.md5(data).hexdigest()]
+
+    md5_list: list[str] = []
+    for i in range(0, len(data), BLOCK_SIZE):
+        md5_list.append(hashlib.md5(data[i : i + BLOCK_SIZE]).hexdigest())
+    return md5_list

bdds-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+bdds/__init__.py,sha256=SRKoBKAWmw5AoZ4x-oq9cevDyQzA-8gerIz2IGLCoUw,944
+bdds/_http.py,sha256=42ZrEKfUxYyUjIpQa-JwXN9GUMSg_baf3gXKkUZ68M0,5855
+bdds/client.py,sha256=9SLNRK7bMUl808_tLU6jtwl01HJXkbnVSOi6PrqrqHs,13095
+bdds/download.py,sha256=DswF5FiPesluRpWYxQe-oUuewiB_mACDoX5glOXHyA0,3777
+bdds/errors.py,sha256=yPozB5NPvtiFLXIQC1VqYznSO37qd9Er9TSXoZzXDwU,1000
+bdds/models.py,sha256=1toQNjm5SKAj3T64dWkNhMwBmusIB2KgCJlrxNgUVUA,867
+bdds/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bdds/upload.py,sha256=-JiQZCjOCtZhDO3xbzpma3w0upxfrG6bzIsiWKcqC4Q,9638
+bdds-0.1.0.dist-info/licenses/LICENSE,sha256=GAcztkuPxpRYGIXQOS-6xyuNzexyrrVi1VGd2r7wCjQ,1074
+bdds-0.1.0.dist-info/METADATA,sha256=2gdJh71PVz88o1VubnU-r31IgaKam6SFz8uGM_tF72M,5142
+bdds-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+bdds-0.1.0.dist-info/top_level.txt,sha256=YYJOdAVbaazGkHpjqiN-6_DYagn_RjA5WVS-v0otllU,5
+bdds-0.1.0.dist-info/RECORD,,

bdds-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bdds-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+bdds