quantzone 0.4.0__cp313-cp313-win_amd64.whl

quantzone/__init__.py

@@ -0,0 +1,119 @@
+"""宽舟科技量化数据平台 Python SDK。
+
+两种使用方式:
+
+1. 实例化客户端(推荐)::
+
+    from quantzone import QuantZone
+
+    client = QuantZone(access_key="AK...", sign_secret="...", base_url="https://...")
+    df = client.get_factors(order_book_ids="000001.SZ", factor="alpha1",
+                            start_date="2024-01-01", end_date="2024-12-31")
+
+2. 模块级单例(可用 ``import qz`` 简写)::
+
+    import qz
+
+    qz.init(access_key="AK...", sign_secret="...", base_url="https://...")
+    df = qz.get_factors(order_book_ids="000001.SZ", factor="alpha1",
+                       start_date="2024-01-01", end_date="2024-12-31")
+"""
+
+from datetime import date
+
+import pandas as pd
+
+from ._dates import DateLike
+from ._singleton import get_instance, init
+from .client import QuantZone
+from .exceptions import (
+    ApiKeyRateLimitError,
+    ApiKeyRevokedError,
+    AuthError,
+    IpNotAllowedError,
+    NetworkError,
+    QuantError,
+    QuotaExceededError,
+    SDKVersionError,
+    SignatureError,
+)
+from .quota import Quota
+
+__version__ = "0.4.0"
+
+
+def get_factors(
+    order_book_ids: str | list[str] | None = None,
+    factor: str | list[str] | None = None,
+    start_date: DateLike | None = None,
+    end_date: DateLike | None = None,
+    filename: str | None = None,
+) -> pd.DataFrame:
+    """模块级 ``get_factors``(需先调用 ``quantzone.init``)。"""
+    return get_instance().get_factors(
+        order_book_ids=order_book_ids,
+        factor=factor,
+        start_date=start_date,
+        end_date=end_date,
+        filename=filename,
+    )
+
+
+def list_factors() -> list[dict]:
+    """模块级 ``list_factors``。"""
+    return get_instance().list_factors()
+
+
+def list_stocks() -> pd.DataFrame:
+    """模块级 ``list_stocks``。"""
+    return get_instance().list_stocks()
+
+
+def get_trading_dates(start_date: DateLike, end_date: DateLike) -> list[date]:
+    """模块级 ``get_trading_dates``。"""
+    return get_instance().get_trading_dates(start_date, end_date)
+
+
+def get_previous_trading_date(current_date: DateLike, n: int = 1) -> date:
+    """模块级 ``get_previous_trading_date``。"""
+    return get_instance().get_previous_trading_date(current_date, n)
+
+
+def get_next_trading_date(current_date: DateLike, n: int = 1) -> date:
+    """模块级 ``get_next_trading_date``。"""
+    return get_instance().get_next_trading_date(current_date, n)
+
+
+def is_trading_date(current_date: DateLike) -> bool:
+    """模块级 ``is_trading_date``。"""
+    return get_instance().is_trading_date(current_date)
+
+
+def get_quota() -> Quota:
+    """模块级 ``get_quota``。"""
+    return get_instance().get_quota()
+
+
+__all__ = [
+    "ApiKeyRateLimitError",
+    "ApiKeyRevokedError",
+    "QuantZone",
+    "Quota",
+    "QuantError",
+    "AuthError",
+    "IpNotAllowedError",
+    "QuotaExceededError",
+    "NetworkError",
+    "SignatureError",
+    "SDKVersionError",
+    "init",
+    "get_factors",
+    "list_factors",
+    "list_stocks",
+    "get_trading_dates",
+    "get_previous_trading_date",
+    "get_next_trading_date",
+    "is_trading_date",
+    "get_quota",
+    "__version__",
+]

quantzone/_auth.pyi

@@ -0,0 +1,9 @@
+from .exceptions import AuthError as AuthError
+
+SERVICE_NAME: str
+USERNAME_ACCESS_KEY: str
+USERNAME_SIGN_SECRET: str
+
+def get_credentials(access_key: str | None = None, sign_secret: str | None = None) -> tuple[str, str]: ...
+def save_credentials(access_key: str, sign_secret: str) -> None: ...
+def delete_credentials() -> None: ...

quantzone/_dates.py

@@ -0,0 +1,49 @@
+"""日期参数归一化工具。
+
+接受 int(YYYYMMDD) / str / date / datetime / Timestamp 多种格式,
+本模块统一归一为 ISO ``YYYY-MM-DD`` 字符串发往服务端。
+"""
+
+from datetime import date, datetime
+from typing import Union
+
+import pandas as pd
+
+DateLike = Union[int, str, date, datetime, pd.Timestamp]
+
+_ISO_LEN = 10
+_INT_DATE_LEN = 8
+_INT_DATE_MIN = 19000101
+_INT_DATE_MAX = 99991231
+
+
+def normalize_date(value: DateLike | None) -> str | None:
+    """把多种日期表示归一为 ISO ``YYYY-MM-DD`` 字符串。
+
+    Args:
+        value: 日期，支持 ``int(YYYYMMDD)`` / ``str`` / ``date`` / ``datetime`` /
+            ``pd.Timestamp``；为 None 时直接返回 None。
+
+    Returns:
+        ISO 格式日期字符串，或 None。
+
+    Raises:
+        ValueError: 类型不支持或字符串无法解析为日期。
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"日期不接受 bool 类型: {value!r}")
+    if isinstance(value, int):
+        if not (_INT_DATE_MIN <= value <= _INT_DATE_MAX) or len(str(value)) != _INT_DATE_LEN:
+            raise ValueError(f"int 日期必须为 8 位 YYYYMMDD: {value!r}")
+        return f"{value // 10000:04d}-{(value // 100) % 100:02d}-{value % 100:02d}"
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, pd.Timestamp):
+        return value.date().isoformat()
+    if isinstance(value, str):
+        return pd.Timestamp(value).date().isoformat()
+    raise ValueError(f"不支持的日期类型: {type(value).__name__}={value!r}")

quantzone/_http.pyi

@@ -0,0 +1,24 @@
+from ._signer import sign_request as sign_request
+from .exceptions import ApiKeyRateLimitError as ApiKeyRateLimitError, ApiKeyRevokedError as ApiKeyRevokedError, AuthError as AuthError, IpNotAllowedError as IpNotAllowedError, NetworkError as NetworkError, QuantError as QuantError, QuotaExceededError as QuotaExceededError, SDKVersionError as SDKVersionError, SignatureError as SignatureError
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+DEFAULT_TIMEOUT: float
+SDK_VERSION_STATUS: int
+STREAM_CHUNK_SIZE: int
+HEADER_API_KEY: str
+HEADER_SDK_VERSION: str
+HEADER_ESTIMATED_BYTES: str
+HEADER_ROW_COUNT: str
+
+class HttpClient:
+    def __init__(self, access_key: str, sign_secret: str, base_url: str, timeout: float = ...) -> None: ...
+    def close(self) -> None: ...
+    def request(self, method: str, path: str, *, params: dict[str, Any] | None = None, json_body: Any | None = None) -> Any: ...
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any: ...
+    def post(self, path: str, *, json_body: Any | None = None, params: dict[str, Any] | None = None) -> Any: ...
+    def stream_post(self, path: str, json_body: dict[str, Any], out_file: Path) -> dict[str, int]: ...
+    @contextmanager
+    def stream_post_iter(self, path: str, json_body: dict[str, Any]) -> Iterator[Iterator[bytes]]: ...

quantzone/_logger.py

@@ -0,0 +1,17 @@
+"""SDK 共享 logger,默认输出到 stderr。
+
+用户可通过 ``logging.getLogger("quantzone").setLevel(...)`` 调整级别;
+若用户已配置 root logger,可设置 ``logger.propagate = True`` 让消息传递。
+"""
+
+import logging
+import sys
+
+logger = logging.getLogger("quantzone")
+
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("[quantzone] %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False

quantzone/_signer.pyi

@@ -0,0 +1 @@
+def sign_request(sign_secret: str, method: str, path: str, body: bytes | None = None, *, params: dict[str, str] | None = None) -> dict[str, str]: ...

quantzone/_singleton.py

@@ -0,0 +1,72 @@
+"""模块级 ``quantzone.init(...)`` 维护的单例 ``QuantZone``。
+
+顶层 init 风格:用户在程序启动时调用一次 ``init``,
+之后通过模块顶层函数(如 ``quantzone.get_factors``)直接使用。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import QuantZone
+
+_INSTANCE: "QuantZone | None" = None
+
+
+def init(
+    access_key: str | None = None,
+    sign_secret: str | None = None,
+    *,
+    base_url: str,
+    timeout: float = 60.0,
+    download_dir: Path | str | None = None,
+) -> "QuantZone":
+    """初始化模块级单例 ``QuantZone``。
+
+    Args:
+        access_key: 公开标识符;None 时从 keyring 读取。
+        sign_secret: 签名密钥;None 时从 keyring 读取。
+        base_url: 服务端地址,必须显式传入。
+        timeout: 请求超时(秒)。
+        download_dir: 下载目录;None 时使用 ``~/.quantzone/downloads``。
+
+    Returns:
+        已初始化的 ``QuantZone``。重复调用会先关闭旧实例再创建新的。
+    """
+    from .client import QuantZone
+
+    global _INSTANCE
+    if _INSTANCE is not None:
+        _INSTANCE.close()
+    _INSTANCE = QuantZone(
+        access_key=access_key,
+        sign_secret=sign_secret,
+        base_url=base_url,
+        timeout=timeout,
+        download_dir=download_dir,
+    )
+    return _INSTANCE
+
+
+def get_instance() -> "QuantZone":
+    """获取已初始化的单例。
+
+    Returns:
+        当前单例。
+
+    Raises:
+        RuntimeError: 调用 ``init()`` 之前调用本函数。
+    """
+    if _INSTANCE is None:
+        raise RuntimeError("尚未调用 quantzone.init(),请先初始化")
+    return _INSTANCE
+
+
+def reset() -> None:
+    """关闭并清除单例(仅用于测试隔离)。"""
+    global _INSTANCE
+    if _INSTANCE is not None:
+        _INSTANCE.close()
+    _INSTANCE = None

quantzone/calendar.py

@@ -0,0 +1,96 @@
+"""交易日历查询服务（仅 A 股）。
+
+接口约定（服务端实现见 quant-cloud）：
+
+- ``GET /api/calendar/trading-dates?start_date=&end_date=`` → ``["2024-01-02", ...]``
+- ``GET /api/calendar/previous?date=&n=1`` → ``"2024-01-12"``
+- ``GET /api/calendar/next?date=&n=1`` → ``"2024-01-16"``
+- ``GET /api/calendar/is-trading-date?date=`` → ``{"is_trading": true}``
+"""
+
+from datetime import date
+
+from ._dates import DateLike, normalize_date
+from ._http import HttpClient
+
+
+def _to_date(s: str) -> date:
+    """ISO 字符串转 ``date``。"""
+    return date.fromisoformat(s)
+
+
+class CalendarService:
+    """交易日历查询服务。"""
+
+    def __init__(self, http: HttpClient) -> None:
+        """初始化。
+
+        Args:
+            http: HTTP 客户端。
+        """
+        self._http = http
+
+    def get_trading_dates(self, start_date: DateLike, end_date: DateLike) -> list[date]:
+        """获取区间内所有交易日（含起止两端）。
+
+        Args:
+            start_date: 起始日期。
+            end_date: 截止日期。
+
+        Returns:
+            升序排列的交易日列表。
+        """
+        params = {
+            "start_date": normalize_date(start_date),
+            "end_date": normalize_date(end_date),
+        }
+        data = self._http.get("/api/calendar/trading-dates", params=params)
+        items = data if isinstance(data, list) else data.get("items", [])
+        return [_to_date(s) for s in items]
+
+    def get_previous_trading_date(self, current_date: DateLike, n: int = 1) -> date:
+        """返回 ``current_date`` 之前第 n 个交易日。
+
+        Args:
+            current_date: 参考日期（不计入返回结果）。
+            n: 向前偏移的交易日数，默认 1。
+
+        Returns:
+            交易日。
+        """
+        params = {"date": normalize_date(current_date), "n": str(n)}
+        data = self._http.get("/api/calendar/previous", params=params)
+        if isinstance(data, dict):
+            return _to_date(data["date"])
+        return _to_date(data)
+
+    def get_next_trading_date(self, current_date: DateLike, n: int = 1) -> date:
+        """返回 ``current_date`` 之后第 n 个交易日。
+
+        Args:
+            current_date: 参考日期（不计入返回结果）。
+            n: 向后偏移的交易日数，默认 1。
+
+        Returns:
+            交易日。
+        """
+        params = {"date": normalize_date(current_date), "n": str(n)}
+        data = self._http.get("/api/calendar/next", params=params)
+        if isinstance(data, dict):
+            return _to_date(data["date"])
+        return _to_date(data)
+
+    def is_trading_date(self, current_date: DateLike) -> bool:
+        """判断给定日期是否为交易日。
+
+        Args:
+            current_date: 待判断日期。
+
+        Returns:
+            是否为交易日。
+        """
+        params = {"date": normalize_date(current_date)}
+        data = self._http.get("/api/calendar/is-trading-date", params=params)
+        if isinstance(data, dict):
+            return bool(data.get("is_trading", False))
+        return bool(data)

quantzone/client.py

@@ -0,0 +1,145 @@
+"""QuantZone 主类 — 组装所有模块,提供统一 API。"""
+
+from datetime import date
+from pathlib import Path
+
+import pandas as pd
+
+from ._auth import get_credentials
+from ._dates import DateLike
+from ._http import HttpClient
+from .calendar import CalendarService
+from .factor import FactorService
+from .quota import Quota, QuotaService
+from .stock import StockService
+
+
+class QuantZone:
+    """宽舟科技量化数据平台客户端(AK/SK 双密钥)。
+
+    使用示例::
+
+        from quantzone import QuantZone
+
+        client = QuantZone(
+            access_key="AKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+            sign_secret="...",
+            base_url="https://your-api.example.com",
+        )
+
+        df = client.get_factors(
+            order_book_ids=["000001.SZ", "000002.SZ"],
+            factor=["alpha1", "vwap"],
+            start_date="2024-01-01",
+            end_date="2024-12-31",
+        )
+
+        client.close()
+    """
+
+    def __init__(
+        self,
+        access_key: str | None = None,
+        sign_secret: str | None = None,
+        *,
+        base_url: str,
+        timeout: float = 60.0,
+        download_dir: Path | str | None = None,
+    ) -> None:
+        """初始化客户端。
+
+        Args:
+            access_key: 公开标识符;None 时从 keyring 读取。
+            sign_secret: 签名密钥;None 时从 keyring 读取。
+            base_url: 服务端地址,必须显式提供(SDK 不内置默认地址)。
+            timeout: 请求超时(秒),默认 60。大数据量查询调到 600+。
+            download_dir: 默认下载目录;None 表示 ``~/.quantzone/downloads``。
+        """
+        resolved_ak, resolved_sk = get_credentials(access_key, sign_secret)
+
+        self._http = HttpClient(
+            access_key=resolved_ak,
+            sign_secret=resolved_sk,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        resolved_dir = Path(download_dir).expanduser() if download_dir else None
+        self._factor_svc = FactorService(self._http, download_dir=resolved_dir)
+        self._stock_svc = StockService(self._http)
+        self._quota_svc = QuotaService(self._http)
+        self._calendar_svc = CalendarService(self._http)
+
+    def close(self) -> None:
+        """关闭底层 HTTP 连接。"""
+        self._http.close()
+
+    def __enter__(self) -> "QuantZone":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        self.close()
+        return False
+
+    # ── 因子 ──────────────────────────────────────────────
+
+    def get_factors(
+        self,
+        order_book_ids: str | list[str] | None = None,
+        factor: str | list[str] | None = None,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        filename: str | None = None,
+    ) -> pd.DataFrame:
+        """一次性返回完整因子数据(窄表)。
+
+        Args:
+            order_book_ids: 股票代码(``str`` / ``list[str]`` / None=全市场)。
+            factor: 因子名(``str`` / ``list[str]`` / None=全部)。
+            start_date: 起始日期。
+            end_date: 截止日期。
+            filename: 自定义保存文件名。
+
+        Returns:
+            窄表 ``DataFrame``,列:``DataDate / ukey / x / factorname``。
+        """
+        return self._factor_svc.get_factors(
+            order_book_ids=order_book_ids,
+            factor=factor,
+            start_date=start_date,
+            end_date=end_date,
+            filename=filename,
+        )
+
+    def list_factors(self) -> list[dict]:
+        """获取因子元信息列表(含描述、分类)。"""
+        return self._factor_svc.list_factors()
+
+    # ── 合约元信息 ────────────────────────────────────
+
+    def list_stocks(self) -> pd.DataFrame:
+        """获取全量合约(``order_book_id / industry_name / symbol``)。"""
+        return self._stock_svc.list_stocks()
+
+    # ── 交易日历 ──────────────────────────────────────
+
+    def get_trading_dates(self, start_date: DateLike, end_date: DateLike) -> list[date]:
+        """获取区间内交易日列表。"""
+        return self._calendar_svc.get_trading_dates(start_date, end_date)
+
+    def get_previous_trading_date(self, current_date: DateLike, n: int = 1) -> date:
+        """前 n 个交易日。"""
+        return self._calendar_svc.get_previous_trading_date(current_date, n)
+
+    def get_next_trading_date(self, current_date: DateLike, n: int = 1) -> date:
+        """后 n 个交易日。"""
+        return self._calendar_svc.get_next_trading_date(current_date, n)
+
+    def is_trading_date(self, current_date: DateLike) -> bool:
+        """判断是否为交易日。"""
+        return self._calendar_svc.is_trading_date(current_date)
+
+    # ── 配额 ──────────────────────────────────────────
+
+    def get_quota(self) -> Quota:
+        """获取当前用户配额。"""
+        return self._quota_svc.get_quota()

quantzone/exceptions.py

@@ -0,0 +1,108 @@
+"""宽舟科技 SDK 异常定义."""
+
+
+class QuantError(Exception):
+    """SDK 基类异常.
+
+    Attributes:
+        message: 错误信息。
+        status_code: HTTP 状态码;非 HTTP 错误为 None。
+        code: 服务端业务错误码(对齐 dwyeapi ApiResponse.code);
+            未知/未携带时为 None。
+    """
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        super().__init__(message)
+
+
+class AuthError(QuantError):
+    """API Key 无效或已过期."""
+
+    def __init__(self, message: str = "API Key 无效或已过期", *, code: str | None = None):
+        super().__init__(message, status_code=401, code=code)
+
+
+class ApiKeyRevokedError(AuthError):
+    """API Key 已被吊销 → 服务端返回 401 + code=API_KEY_REVOKED.
+
+    用户应在 admin 后台重置 / 重新申请 API Key 后再调用 SDK。
+    """
+
+    def __init__(
+        self,
+        message: str = "API Key 已被吊销,请联系管理员或重新申请",
+    ):
+        super().__init__(message, code="API_KEY_REVOKED")
+
+
+class IpNotAllowedError(QuantError):
+    """请求来源 IP 不在白名单 → 服务端返回 403 + code=IP_NOT_ALLOWED.
+
+    用户应检查 admin 后台为该 API Key 设置的 IP 白名单是否覆盖当前出口 IP。
+    """
+
+    def __init__(
+        self,
+        message: str = "请求来源 IP 不在 API Key 白名单内",
+    ):
+        super().__init__(message, status_code=403, code="IP_NOT_ALLOWED")
+
+
+class ApiKeyRateLimitError(QuantError):
+    """API Key 调用频率超限 → 服务端返回 422 + code=API_KEY_RATE_LIMITED.
+
+    与 QuotaExceededError 区分:前者是按"调用次数"限流(防滥用),
+    后者是按"流量字节"扣费(配额耗尽)。
+    """
+
+    def __init__(
+        self,
+        message: str = "API Key 调用频率超限,请稍后再试",
+    ):
+        super().__init__(message, status_code=422, code="API_KEY_RATE_LIMITED")
+
+
+class QuotaExceededError(QuantError):
+    """配额不足."""
+
+    def __init__(self, message: str = "配额不足", *, remaining: int = 0, required: int = 0):
+        self.remaining = remaining
+        self.required = required
+        super().__init__(message, status_code=429)
+
+
+class NetworkError(QuantError):
+    """网络连接问题."""
+
+    def __init__(self, message: str = "网络连接失败", *, cause: Exception | None = None):
+        self.cause = cause
+        super().__init__(message)
+
+
+class SignatureError(QuantError):
+    """签名校验失败（服务端返回 401）."""
+
+    def __init__(self, message: str = "请求签名校验失败"):
+        super().__init__(message, status_code=401)
+
+
+class SDKVersionError(QuantError):
+    """SDK 版本过低,服务端已停止支持（HTTP 426）。
+
+    错误消息包含升级命令,用户按提示执行 `pip install -U quantzone` 即可。
+    """
+
+    def __init__(
+        self,
+        message: str = "当前 SDK 版本已停止支持,请执行 `pip install -U quantzone` 升级后重试",
+    ):
+        super().__init__(message, status_code=426)

quantzone/factor.py

@@ -0,0 +1,231 @@
+"""因子查询。
+
+对外仅提供 :meth:`FactorService.get_factors` — 一次性返回完整 ``DataFrame``。
+
+底层走 ``POST /api/factors/stream`` 拉 Arrow IPC stream:
+- 边收边解码:每个 RecordBatch 立即转 ``DataFrame``。
+- 边收边落盘:HTTP 字节同时写到 ``download_dir/temp/<id>.arrow``。
+- 流自然结束 → 原子重命名到 ``download_dir/factors_<ts>.arrow``。
+- 失败 → temp 文件保留,不删除。
+
+字段名与 DolphinDB 表 ``dfs://factor_day/normal_factors_DB`` 一致:
+``DataDate / ukey / x / factorname``。SDK 不做列名转换或宽表 pivot。
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import uuid
+from collections.abc import Iterator
+from datetime import datetime
+from pathlib import Path
+from typing import IO, Any
+
+import pandas as pd
+import pyarrow.ipc as ipc
+
+from ._dates import DateLike, normalize_date
+from ._http import HttpClient
+from ._logger import logger
+
+DEFAULT_DOWNLOAD_DIR = Path.home() / ".quantzone" / "downloads"
+PERSIST_FILENAME_PREFIX = "factors_"
+TEMP_SUBDIR = "temp"
+ARROW_EXT = ".arrow"
+
+
+class _TeeReader(io.RawIOBase):
+    """把上游 chunk 流复制一份到磁盘文件,同时对外暴露 file-like ``read`` 接口。
+
+    用于 ``pa.ipc.open_stream`` 这种需要 file-like 的解码器:它从这里 ``read``,
+    我们一边给它字节、一边把字节写到 temp 文件,实现 tee。
+
+    继承 ``io.RawIOBase`` 是为了一次性补齐 ``closed`` / ``seekable`` / ``writable``
+    等 pyarrow 校验需要的属性。
+    """
+
+    def __init__(self, chunks: Iterator[bytes], sink: IO[bytes]) -> None:
+        """初始化。
+
+        Args:
+            chunks: 上游 HTTP chunk 字节迭代器(``httpx.Response.iter_bytes``)。
+            sink: 已打开的 temp 文件句柄(二进制写)。
+        """
+        super().__init__()
+        self._chunks = chunks
+        self._sink = sink
+        self._buffer = bytearray()
+
+    def _pull_one(self) -> bool:
+        """从上游再拉一个 chunk,同时写入 sink。返回是否拉到。"""
+        try:
+            chunk = next(self._chunks)
+        except StopIteration:
+            return False
+        if not chunk:
+            return True
+        self._buffer.extend(chunk)
+        self._sink.write(chunk)
+        return True
+
+    def read(self, n: int = -1) -> bytes:
+        """读取至多 n 字节;n<0 表示读到 EOF。"""
+        if n is None or n < 0:
+            while self._pull_one():
+                pass
+            data = bytes(self._buffer)
+            self._buffer.clear()
+            return data
+        while len(self._buffer) < n:
+            if not self._pull_one():
+                break
+        take = bytes(self._buffer[:n])
+        del self._buffer[:n]
+        return take
+
+    def readall(self) -> bytes:
+        return self.read(-1)
+
+    def readinto(self, b) -> int:
+        data = self.read(len(b))
+        n = len(data)
+        b[:n] = data
+        return n
+
+    def readable(self) -> bool:
+        return True
+
+    def writable(self) -> bool:
+        return False
+
+    def seekable(self) -> bool:
+        return False
+
+
+def _to_str_list(value: str | list[str] | None) -> list[str] | None:
+    """把 ``str`` / ``list[str]`` / None 归一为 ``list[str]`` 或 None。"""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    return list(value)
+
+
+class FactorService:
+    """因子数据查询服务。"""
+
+    def __init__(self, http: HttpClient, download_dir: Path | None = None) -> None:
+        """初始化。
+
+        Args:
+            http: HTTP 客户端。
+            download_dir: 默认下载目录;None 表示 ``~/.quantzone/downloads``。
+        """
+        self._http = http
+        self._download_dir = download_dir or DEFAULT_DOWNLOAD_DIR
+
+    def get_factors(
+        self,
+        order_book_ids: str | list[str] | None = None,
+        factor: str | list[str] | None = None,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        filename: str | None = None,
+    ) -> pd.DataFrame:
+        """一次性返回完整因子数据(窄表)。
+
+        服务端按月分批查 DolphinDB,每个 RecordBatch 立即推过来;SDK 边收边解码、
+        边落盘到 ``download_dir/temp/<id>.arrow``。流自然结束后原子重命名到
+        ``download_dir/<filename or factors_<ts>.arrow>``;失败 → temp 文件保留,
+        不删除。
+
+        Args:
+            order_book_ids: 股票代码(``str`` 或 ``list[str]``),None 表示全市场。
+                示例:``"000001.SZ"`` 或 ``["000001.SZ", "000002.SZ"]``。
+            factor: 因子名(``str`` 或 ``list[str]``),None 表示全部因子。
+                示例:``"alpha1"`` 或 ``["alpha1", "vwap"]``。
+            start_date: 起始日期,支持 ``int(YYYYMMDD)`` / ``str`` / ``date`` /
+                ``datetime`` / ``Timestamp``。None 表示不限。
+            end_date: 截止日期,格式同上。
+            filename: 自定义最终文件名(落到 ``download_dir`` 下);None 时按时间戳生成。
+
+        Returns:
+            窄表 ``DataFrame``,列:``DataDate / ukey / x / factorname``。
+            空结果时返回带正确列名的空 DataFrame。
+        """
+        ids_list = _to_str_list(order_book_ids)
+        factor_list = _to_str_list(factor)
+
+        body: dict[str, Any] = {}
+        if factor_list:
+            body["factor"] = factor_list
+        if ids_list:
+            body["order_book_ids"] = ids_list
+        if start_date is not None:
+            body["start_date"] = normalize_date(start_date)
+        if end_date is not None:
+            body["end_date"] = normalize_date(end_date)
+
+        download_dir = self._download_dir
+        temp_dir = download_dir / TEMP_SUBDIR
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        download_dir.mkdir(parents=True, exist_ok=True)
+
+        temp_path = temp_dir / f"{uuid.uuid4().hex}{ARROW_EXT}"
+        final_name = filename or (
+            f"{PERSIST_FILENAME_PREFIX}{datetime.now():%Y%m%d_%H%M%S}_{uuid.uuid4().hex[:8]}{ARROW_EXT}"
+        )
+        final_path = download_dir / final_name
+
+        logger.info("下载文件(temp): %s", temp_path)
+
+        chunks_dfs = list(self._iter_batches(body, temp_path, final_path))
+        if not chunks_dfs:
+            return pd.DataFrame(columns=["DataDate", "ukey", "x", "factorname"])
+        return pd.concat(chunks_dfs, ignore_index=True)
+
+    def _iter_batches(
+        self,
+        body: dict[str, Any],
+        temp_path: Path,
+        final_path: Path,
+    ) -> Iterator[pd.DataFrame]:
+        """流式解码生成器:每个 RecordBatch 立即 yield ``DataFrame``,边收边写 temp。"""
+        success = False
+        sink = temp_path.open("wb")
+        try:
+            with self._http.stream_post_iter("/api/factors/stream", body) as chunks:
+                tee = _TeeReader(chunks, sink)
+                reader = ipc.open_stream(tee)
+                while True:
+                    try:
+                        batch = reader.read_next_batch()
+                    except StopIteration:
+                        break
+                    if batch is None:
+                        break
+                    yield batch.to_pandas()
+            success = True
+        finally:
+            sink.flush()
+            sink.close()
+            if success:
+                os.replace(temp_path, final_path)
+                size = final_path.stat().st_size
+                logger.info("已保存到: %s (%d bytes)", final_path, size)
+            else:
+                logger.info("流未正常结束,temp 文件保留: %s", temp_path)
+
+    def list_factors(self) -> list[dict]:
+        """获取可用因子元信息列表。
+
+        字段与 DolphinDB 表 ``dfs://factor_meta/factor_meta_info`` 原始列对齐。
+
+        Returns:
+            因子列表,每个元素含 ``factorname`` / ``startDate`` / ``endDate`` 三个字段。
+        """
+        data = self._http.get("/api/factors/")
+        if isinstance(data, list):
+            return data
+        return data.get("items", data.get("factors", []))

quantzone/quota.py

@@ -0,0 +1,66 @@
+"""配额查询服务。
+
+对外暴露简洁字段:``bytes_limit / bytes_used / remaining_days / license_type``。
+
+后端 ``/api/quota/`` 返回的是三层账本字段(``daily_quota_bytes`` / ``daily_used_bytes``
+/ ``extra_quota_bytes`` 等),SDK 在此处映射为对外简洁字段。
+"""
+
+from typing import TypedDict
+
+from ._http import HttpClient
+
+
+class Quota(TypedDict, total=False):
+    """配额信息字典。
+
+    Attributes:
+        bytes_limit: 总流量上限（字节）。
+        bytes_used: 已用流量（字节）。
+        remaining_days: 许可剩余天数。
+        license_type: 许可证类型（如 ``"trial"`` / ``"commercial"``）。
+    """
+
+    bytes_limit: int
+    bytes_used: int
+    remaining_days: int
+    license_type: str
+
+
+class QuotaService:
+    """用户配额查询服务。"""
+
+    def __init__(self, http: HttpClient) -> None:
+        """初始化。
+
+        Args:
+            http: HTTP 客户端。
+        """
+        self._http = http
+
+    def get_quota(self) -> Quota:
+        """获取当前用户配额。
+
+        把后端三层字段映射为对外简洁字段:
+        - ``bytes_limit = daily_quota_bytes + extra_quota_bytes``
+        - ``bytes_used  = daily_used_bytes``
+        - ``remaining_days`` / ``license_type`` 透传
+
+        Returns:
+            配额字典,含 ``bytes_limit`` / ``bytes_used`` / ``remaining_days`` /
+            ``license_type``。服务端缺失的源字段在结果中也会缺失。
+        """
+        data = self._http.get("/api/quota/")
+        if not isinstance(data, dict):
+            return {}
+
+        result: Quota = {}
+        if "daily_quota_bytes" in data and "extra_quota_bytes" in data:
+            result["bytes_limit"] = int(data["daily_quota_bytes"]) + int(data["extra_quota_bytes"])
+        if "daily_used_bytes" in data:
+            result["bytes_used"] = int(data["daily_used_bytes"])
+        if "remaining_days" in data:
+            result["remaining_days"] = int(data["remaining_days"])
+        if "license_type" in data:
+            result["license_type"] = str(data["license_type"])
+        return result

quantzone/stock.py

@@ -0,0 +1,53 @@
+"""股票/合约元信息查询服务。
+
+接口约定:
+
+- ``GET /api/stocks/`` → 全量合约列表(服务端缓存,12h TTL)
+
+返回 ``DataFrame``,列固定 3 列:``order_book_id / industry_name / symbol``。
+"""
+
+import pandas as pd
+
+from ._http import HttpClient
+
+INSTRUMENT_COLUMNS = ["order_book_id", "industry_name", "symbol"]
+
+
+def _to_dataframe(items: list[dict]) -> pd.DataFrame:
+    """把 ``list[dict]`` 转为合约 ``DataFrame``,缺失列补 ``NA``,列顺序固定。"""
+    if not items:
+        return pd.DataFrame(columns=INSTRUMENT_COLUMNS)
+    df = pd.DataFrame(items)
+    for col in INSTRUMENT_COLUMNS:
+        if col not in df.columns:
+            df[col] = pd.NA
+    return df[INSTRUMENT_COLUMNS]
+
+
+class StockService:
+    """股票/合约信息查询服务。"""
+
+    def __init__(self, http: HttpClient) -> None:
+        """初始化。
+
+        Args:
+            http: HTTP 客户端。
+        """
+        self._http = http
+
+    def list_stocks(self) -> pd.DataFrame:
+        """获取全量合约列表。
+
+        服务端不再支持按交易所过滤,客户端拿全量后自行筛选,例如::
+
+            df = client.list_stocks()
+            sz = df[df["order_book_id"].str.endswith(".SZ")]
+
+        Returns:
+            合约 ``DataFrame``,列固定 3 列:
+            ``order_book_id / industry_name / symbol``。
+        """
+        data = self._http.get("/api/stocks/")
+        items = data if isinstance(data, list) else data.get("items", data.get("stocks", []))
+        return _to_dataframe(items)

quantzone-0.4.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: quantzone
+Version: 0.4.0
+Summary: 宽舟科技量化数据平台 Python SDK
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<2.0,>=0.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: keyring>=25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# quantzone
+
+宽舟科技量化数据平台 Python SDK。
+
+## 安装
+
+```bash
+pip install quantzone
+```
+
+## Supported Platforms
+
+| OS | Architecture | Python |
+|----|--------------|--------|
+| Linux (glibc, e.g. Ubuntu/Debian/CentOS) | x86_64, aarch64 | 3.11, 3.12, 3.13, 3.14 |
+| Linux (musl, e.g. Alpine) | x86_64, aarch64 | 3.11, 3.12, 3.13, 3.14 |
+| macOS | Intel (10.9+), Apple Silicon (11.0+) | 3.11, 3.12, 3.13, 3.14 |
+| Windows | AMD64 (Windows 10/11) | 3.11, 3.12, 3.13, 3.14 |
+
+Other platforms (32-bit Linux/Windows, FreeBSD, ppc64le, s390x, RISC-V, Python <= 3.10) are not supported.
+If `pip install quantzone` reports `No matching distribution found`, your platform/Python version is not in the supported matrix.
+
+## 快速开始
+
+```python
+# 方式 1:实例化客户端
+from quantzone import QuantZone
+
+# base_url 必须显式传入(SDK 不内置默认服务端地址)
+client = QuantZone(
+    access_key="AKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    sign_secret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    base_url="https://your-api.example.com",
+)
+
+# 方式 2:模块级单例(短别名 qz)
+import qz
+
+qz.init(
+    access_key="AKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    sign_secret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    base_url="https://your-api.example.com",
+)
+df = qz.get_factors(factor="alpha1", start_date="2024-01-01", end_date="2024-12-31")
+```
+
+## API
+
+### 因子查询
+
+```python
+# 查询因子数据 → 窄表 DataFrame,列:DataDate / ukey / x / factorname
+# 4 个参数都可省略,服务端按缺省维度展开:
+#   factor 空           → 全部因子
+#   order_book_ids 空   → 全市场
+df = client.get_factors(
+    factor=["alpha1", "alpha2", "vwap"],
+    order_book_ids=["000001.SZ", "000002.SZ"],
+    start_date="2024-01-01",
+    end_date="2024-12-31",
+)
+
+# 因子元信息(含 name / description / category)
+factors = client.list_factors()
+```
+
+### 合约元信息
+
+```python
+df = client.list_stocks(exchange="SZ")             # 全量合约 → DataFrame
+df = client.instruments(["000001.SZ", "600000.SH"]) # 指定合约 → DataFrame
+```
+
+### 交易日历
+
+```python
+client.get_trading_dates("2024-01-01", "2024-01-31")  # list[date]
+client.get_previous_trading_date("2024-01-15", n=1)   # date
+client.get_next_trading_date("2024-01-15", n=1)       # date
+client.is_trading_date("2024-01-01")                  # bool
+```
+
+### 配额查询
+
+```python
+quota = client.get_quota()
+# {bytes_limit, bytes_used, remaining_days, license_type}
+```
+
+### Context Manager
+
+```python
+with QuantZone(access_key="AK...", sign_secret="...", base_url="https://your-api.example.com") as client:
+    df = client.get_factors(factor=["alpha1"])
+```
+
+### 大查询超时
+
+```python
+# 全市场全因子单日 ~12M 数据点,默认 60s 超时会被打断 → 显式调到 600s+
+client = QuantZone(
+    access_key="AK...", sign_secret="...",
+    base_url="https://your-api.example.com",
+    timeout=600,
+)
+```
+
+### 数据本地存储
+
+**所有下载的 Arrow 文件都会持久化保留**,SDK 不主动删除。
+
+```python
+# 默认:落到 ~/.quantzone/downloads/factors_<timestamp>_<short>.arrow
+client = QuantZone(
+    access_key="AK...", sign_secret="...",
+    base_url="https://your-api.example.com",
+)
+df = client.get_factors(factor=["alpha1"])
+
+# 全局指定下载目录
+client = QuantZone(
+    access_key="AK...", sign_secret="...",
+    base_url="https://your-api.example.com",
+    download_dir="~/data/quantzone",
+)
+
+# 单次指定文件名(落到 download_dir/<filename>)
+df = client.get_factors(factor=["alpha1"], filename="alpha1_2024.arrow")
+```
+
+每次下载都会通过 logger 打印落盘位置,默认输出到 stderr:
+```
+[quantzone] 下载文件(temp): /Users/me/.quantzone/downloads/temp/abc123.arrow
+[quantzone] 已保存到: /Users/me/.quantzone/downloads/factors_20240115_120000_abc123.arrow (1024 bytes)
+```
+
+历史文件由用户自行管理(SDK 不做任何 GC)。
+
+## 特性
+
+- **请求签名**:每个请求自动带 HMAC-SHA256 签名
+- **流式下载**:Arrow IPC 边收边写临时文件,完毕后原子重命名为最终文件并加载为 DataFrame
+- **凭证安全存储**:通过 keyring 自动读取系统密钥环(`QuantZone()` 不传 AK/SK 时生效)
+- **不自动重试**:量化接口非幂等(消耗配额、跑昂贵 DDB 查询),SDK 不内置重试。需要重试请用 `tenacity` / `backoff` 装饰 `client.get_factors`,自定义退避策略
+
+## 异常处理
+
+```python
+from quantzone import QuantZone, AuthError, QuotaExceededError, NetworkError
+
+try:
+    df = client.get_factors(factor=["alpha1"])
+except AuthError:
+    print("API Key 无效")
+except QuotaExceededError as e:
+    print(f"配额不足:剩余 {e.remaining},需要 {e.required}")
+except NetworkError:
+    print("网络连接失败")
+```
+
+## 开发
+
+```bash
+cd quant-sdk
+uv sync --dev
+uv run pytest tests/ -v
+uv run ruff check src/ --fix && uv run ruff format src/
+```

quantzone-0.4.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+quantzone/__init__.py,sha256=MKQ3ppq4KX8t8ZKyqgFc8-AYkvZhmeWgjgIzhELk1sM,3236
+quantzone/_auth.cp313-win_amd64.pyd,sha256=WzreMWWBQpAy51luLLbb2qCr0WXyUzrj6T--zDxq5OA,46592
+quantzone/_auth.pyi,sha256=oysbXAov0OROpOFWTLrK3t_cjlsE5lz6AgSdeGMjruE,341
+quantzone/_dates.py,sha256=cK8gQOxexVcRHSnOPXlN40gFvU68Rfb-9Gz0RoCHksg,1722
+quantzone/_http.cp313-win_amd64.pyd,sha256=s6TO8x154xa44D8nz0eUqjbTVFz9xHxAzQeInj6Crz8,130048
+quantzone/_http.pyi,sha256=PKWgtY3JgdWunoxmWnjeDuvqHQuGMpxe7-lvKmrsdvI,1415
+quantzone/_logger.py,sha256=KIyFcJpfZ4x4-HbIDQguNVnR_pqEyVPDN7gKfwWsUAY,542
+quantzone/_signer.cp313-win_amd64.pyd,sha256=lyv5EDRpZkZL6Ks8IehliaZfUosrnuVaAbJyRZZXSSM,48640
+quantzone/_signer.pyi,sha256=CZyftqqAx8B4EBNMQ4kFdtBZWqrOLH5cmMY0ljwFb9w,151
+quantzone/_singleton.py,sha256=tMgjS9LoMzU_8qqRwzFCPQeCp9LMP6msB7VURPsCQe4,1970
+quantzone/calendar.py,sha256=HPdqWF2-VL2NL9W8qJCr8YezHzdGC-1AA970fyAousk,3238
+quantzone/client.py,sha256=5CS45tyd2oR2BKZU2QcFy20kw9dATO38AdQonHenazc,5399
+quantzone/exceptions.py,sha256=KVlk0sQDdqnPb01aKXtB-Iw_GKgBwD1FfOgvumTP_SM,3329
+quantzone/factor.py,sha256=KbTg0MhhBX-O5I5q96-Ns0LOjNigalX974l8BxAw3kw,8360
+quantzone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quantzone/quota.py,sha256=zfJ_P2ARypHckGrg_tiUO3vyLAAevJ1fb537Otnmcyw,2185
+quantzone/stock.py,sha256=OA7wZx1KJnW1UGZuTCrG9gdcWlqlomtdh5YDmym-Amk,1593
+qz/__init__.py,sha256=rECZe7WlcRO7cpmutEBArlfMXbNSVl60Te97keD4JLA,334
+qz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quantzone-0.4.0.dist-info/METADATA,sha256=xlmmTXe2ze4qgo7mka3SaaWifc43jl_BDa2plUjpFcw,5718
+quantzone-0.4.0.dist-info/WHEEL,sha256=x5Wpw_tLx5PQKiWdxpqvs0e7Sg-SO0mTWdEADYDGPGA,101
+quantzone-0.4.0.dist-info/top_level.txt,sha256=Nc-VKur3jcc8XKj1BL-PJbYSx_x50zrYhVEGe0iMX5g,13
+quantzone-0.4.0.dist-info/RECORD,,

quantzone-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

quantzone-0.4.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+quantzone
+qz

qz/__init__.py

@@ -0,0 +1,8 @@
+"""``qz`` — ``quantzone`` 的短别名。
+
+允许用户 ``import qz`` 然后直接 ``qz.init(...)`` / ``qz.get_factors(...)`` /
+``qz.QuantZone(...)``。与 ``import quantzone as qz`` 等价,无需用户手动 alias。
+"""
+
+from quantzone import *  # noqa: F401, F403
+from quantzone import __all__, __version__  # noqa: F401