quantzone 0.5.0__cp39-cp39-win_amd64.whl

quantzone/__init__.py

@@ -0,0 +1,127 @@
+"""宽舟科技量化数据平台 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. 模块级单例(推荐用 ``as qz`` 简写)::
+
+    import quantzone as 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 __future__ import annotations
+
+from datetime import date
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+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
+
+try:
+    __version__ = _pkg_version("quantzone")
+except PackageNotFoundError:
+    # 开发模式未安装时回退
+    __version__ = "0.0.0+dev"
+
+
+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",
+    "AuthError",
+    "IpNotAllowedError",
+    "NetworkError",
+    "QuantError",
+    "QuantZone",
+    "Quota",
+    "QuotaExceededError",
+    "SDKVersionError",
+    "SignatureError",
+    "__version__",
+    "get_factors",
+    "get_next_trading_date",
+    "get_previous_trading_date",
+    "get_quota",
+    "get_trading_dates",
+    "init",
+    "is_trading_date",
+    "list_factors",
+    "list_stocks",
+]

quantzone/_auth.pyi

@@ -0,0 +1,3 @@
+from .exceptions import AuthError as AuthError
+
+def get_credentials(access_key: str | None, sign_secret: str | None) -> tuple[str, str]: ...

quantzone/_dates.py

@@ -0,0 +1,66 @@
+"""日期参数归一化工具。
+
+接受 int(YYYYMMDD) / str / date / datetime / Timestamp 多种格式,
+本模块统一归一为 ISO ``YYYY-MM-DD`` 字符串发往服务端。
+"""
+
+from __future__ import annotations
+
+import re
+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
+
+# 严格白名单:只接受三种常见日期字符串格式,拒绝 "now" / "today" / "NaT" 等魔法字符串
+# 以及带时区后缀、多余空格的字符串
+_DATE_STR_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"^\d{4}-\d{2}-\d{2}$"),       # 2024-01-31
+    re.compile(r"^\d{8}$"),                    # 20240131
+    re.compile(r"^\d{4}/\d{2}/\d{2}$"),        # 2024/01/31
+)
+
+
+def normalize_date(value: DateLike | None) -> str | None:
+    """把多种日期表示归一为 ISO ``YYYY-MM-DD`` 字符串。
+
+    Args:
+        value: 日期，支持 ``int(YYYYMMDD)`` / ``str`` / ``date`` / ``datetime`` /
+            ``pd.Timestamp``；为 None 时直接返回 None。字符串只接受
+            ``YYYY-MM-DD`` / ``YYYYMMDD`` / ``YYYY/MM/DD`` 三种格式,其他(含
+            ``"now"`` / ``"today"`` / ``"NaT"`` / 带时区后缀等)一律拒绝。
+
+    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):
+        if not any(p.fullmatch(value) for p in _DATE_STR_PATTERNS):
+            raise ValueError(
+                f"日期字符串格式不合法,必须是 YYYY-MM-DD / YYYYMMDD / YYYY/MM/DD: {value!r}"
+            )
+        return pd.Timestamp(value).date().isoformat()
+    raise ValueError(f"不支持的日期类型: {type(value).__name__}={value!r}")

quantzone/_http.pyi

@@ -0,0 +1,27 @@
+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
+MAX_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
+API_VERSION: str
+API_PREFIX: 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,90 @@
+"""模块级 ``quantzone.init(...)`` 维护的单例 ``QuantZone``。
+
+顶层 init 风格:用户在程序启动时调用一次 ``init``,
+之后通过模块顶层函数(如 ``quantzone.get_factors``)直接使用。
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import QuantZone
+
+_INSTANCE: QuantZone | None = None
+_LOCK = threading.Lock()
+
+
+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 (str | None): 公开标识符,必须显式传入,不再支持 keyring。
+            示例：``"AKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"``。
+        sign_secret (str | None): 签名密钥,必须显式传入,不再支持 keyring。
+            示例：``"sk_xxxx..."``。
+        base_url (str): 服务端地址,必须显式传入。
+            示例：``"https://your-api.example.com"``。
+        timeout (float): 请求超时(秒),默认 ``60.0``。示例：``30.0``。
+        download_dir (Path | str | None): 下载目录;``None`` 时使用 ``~/.quantzone/downloads``。
+            示例：``"/tmp/quantzone-downloads"``。
+
+    Returns:
+        QuantZone: 已初始化的实例。重复调用会先关闭旧实例再创建新的;
+        多线程并发调用时,只有最后一个进入临界区的线程构造的实例会被保留,
+        中间被覆盖的实例都会被 close,避免连接句柄泄漏。
+
+    Raises:
+        AuthError: ``access_key`` 或 ``sign_secret`` 缺失或为空字符串。
+    """
+    from .client import QuantZone
+
+    global _INSTANCE
+    new_instance = QuantZone(
+        access_key=access_key,
+        sign_secret=sign_secret,
+        base_url=base_url,
+        timeout=timeout,
+        download_dir=download_dir,
+    )
+    with _LOCK:
+        old_instance = _INSTANCE
+        _INSTANCE = new_instance
+    if old_instance is not None:
+        old_instance.close()
+    return new_instance
+
+
+def get_instance() -> QuantZone:
+    """获取已初始化的单例。
+
+    Returns:
+        当前单例。
+
+    Raises:
+        RuntimeError: 调用 ``init()`` 之前调用本函数。
+    """
+    with _LOCK:
+        instance = _INSTANCE
+    if instance is None:
+        raise RuntimeError("尚未调用 quantzone.init(),请先初始化")
+    return instance
+
+
+def reset() -> None:
+    """关闭并清除单例(仅用于测试隔离)。"""
+    global _INSTANCE
+    with _LOCK:
+        old_instance = _INSTANCE
+        _INSTANCE = None
+    if old_instance is not None:
+        old_instance.close()

quantzone/calendar.py

@@ -0,0 +1,88 @@
+"""交易日历查询服务（仅 A 股）。"""
+
+from datetime import date
+
+from ._dates import DateLike, normalize_date
+from ._http import API_PREFIX, 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(f"{API_PREFIX}/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(f"{API_PREFIX}/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(f"{API_PREFIX}/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(f"{API_PREFIX}/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,158 @@
+"""QuantZone 主类 — 组装所有模块,提供统一 API。"""
+
+from __future__ import annotations
+
+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 (str | None): 公开标识符,必须显式传入,不再支持 keyring。
+                长度由服务端约束,示例：``"AKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"``。
+            sign_secret (str | None): 签名密钥,必须显式传入,不再支持 keyring。
+                示例：``"sk_xxxx..."``。
+            base_url (str): 服务端地址,必须显式提供(SDK 不内置默认地址)。
+                示例：``"https://your-api.example.com"``。
+            timeout (float): 请求超时(秒),默认 ``60.0``，上限 ``60.0``；超过会被截断。
+                取值范围 ``(0, 60]``。示例：``30.0``。
+            download_dir (Path | str | None): 默认下载目录;``None`` 表示
+                ``~/.quantzone/downloads``。示例：``"/tmp/quantzone-downloads"``。
+
+        Raises:
+            AuthError: ``access_key`` 或 ``sign_secret`` 缺失或为空字符串。
+        """
+        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:
+        """退出上下文,关闭底层 HTTP 连接。"""
+        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=全市场),
+                支持纯 6 位或带交易所后缀,详见 :meth:`FactorService.get_factors`。
+            factor: 因子名(``str`` / ``list[str]``),必填,1-20 个。
+            start_date: 起始日期,必填。
+            end_date: 截止日期,省略 = 服务端当日。
+            filename: 自定义保存文件名。
+
+        Returns:
+            窄表 ``DataFrame``,列:``date / order_book_id / value / factor``。
+        """
+        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,110 @@
+"""宽舟科技 SDK 异常定义."""
+
+from __future__ import annotations
+
+
+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,252 @@
+"""因子查询。
+
+对外仅提供 :meth:`FactorService.get_factors` — 一次性返回完整 ``DataFrame``。
+
+- 边收边解码 Arrow IPC stream:每个 RecordBatch 立即转 ``DataFrame``。
+- 边收边落盘:HTTP 字节同时写到 ``download_dir/temp/<id>.arrow``。
+- 流自然结束 → 原子重命名到 ``download_dir/factors_<ts>.arrow``。
+- 失败 → temp 文件保留,不删除。
+
+返回窄表,列固定 4 列:``date / order_book_id / value / factor``。
+"""
+
+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 API_PREFIX, HttpClient
+from ._logger import logger
+
+DEFAULT_DOWNLOAD_DIR = Path.home() / ".quantzone" / "downloads"
+PERSIST_FILENAME_PREFIX = "factors_"
+TEMP_SUBDIR = "temp"
+ARROW_EXT = ".arrow"
+
+_PUBLIC_FACTOR_META_FIELDS = ("factorname", "startDate", "endDate")
+
+
+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:
+        """一次性返回完整因子数据(窄表)。
+
+        响应以 Arrow IPC 流式返回,SDK 边收边解码、边落盘到
+        ``download_dir/temp/<id>.arrow``。流自然结束后原子重命名到
+        ``download_dir/<filename or factors_<ts>.arrow>``;失败 → temp 文件保留,
+        不删除。
+
+        Args:
+            order_book_ids: 股票代码,``str`` 或 ``list[str]``,最多 100 个,None 表示全市场。
+                支持两种等价格式:
+
+                - 纯 6 位数字:``"000001"`` / ``["000001", "600036"]``
+                - 6 位 + 交易所后缀:``"000001.SZ"`` / ``["600036.SH", "430047.BJ"]``
+            factor: 因子名(``str`` 或 ``list[str]``),必填,1-20 个。
+                示例:``"alpha1"`` 或 ``["alpha1", "vwap"]``。省略会被服务端拒绝。
+            start_date: 起始日期,必填,支持 ``int(YYYYMMDD)`` / ``str`` / ``date`` /
+                ``datetime`` / ``Timestamp``。
+            end_date: 截止日期,格式同上;省略 = 服务端当日。
+            filename: 自定义最终文件名(落到 ``download_dir`` 下);None 时按时间戳生成。
+
+        Returns:
+            窄表 ``DataFrame``,列:``date / order_book_id / value / factor``。
+            空结果时返回带正确列名的空 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}"
+        if filename is not None:
+            # 路径遍历防护:filename 只能是纯文件名,不允许任何路径分隔符或父目录引用
+            # 注意 POSIX 下 Path("a\\b").name 返回 "a\\b",必须显式拒绝反斜杠以保证跨平台安全
+            if (
+                filename in ("", ".", "..")
+                or "/" in filename
+                or "\\" in filename
+                or filename != Path(filename).name
+            ):
+                raise ValueError(
+                    f"filename 必须是纯文件名(不含路径分隔符 / 或 \\,不含 . .. 前缀): {filename!r}"
+                )
+            final_name = filename
+        else:
+            final_name = (
+                f"{PERSIST_FILENAME_PREFIX}{datetime.now():%Y%m%d_%H%M%S}_{uuid.uuid4().hex[:8]}{ARROW_EXT}"
+            )
+        final_path = download_dir / final_name
+        # 最终验证:解析后的路径必须仍在 download_dir 下,防止符号链接/相对路径绕过
+        if final_path.resolve().parent != download_dir.resolve():
+            raise ValueError(f"filename 解析后超出下载目录: {filename!r}")
+
+        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=["date", "order_book_id", "value", "factor"])
+        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(f"{API_PREFIX}/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]:
+        """获取可用因子元信息列表。
+
+        Returns:
+            因子列表,每个元素含 ``factorname`` / ``startDate`` / ``endDate`` 三个字段。
+            服务端返回的其他字段一律丢弃,不暴露未知字段。
+        """
+        data = self._http.get(f"{API_PREFIX}/factors")
+        raw = data if isinstance(data, list) else data.get("items", data.get("factors", []))
+        return [
+            {k: item[k] for k in _PUBLIC_FACTOR_META_FIELDS if k in item}
+            for item in raw
+        ]

quantzone/quota.py

@@ -0,0 +1,77 @@
+"""配额查询服务。
+
+对外暴露三层配额视图:今日基础额度(``daily_quota_bytes`` / ``daily_used_bytes``)、
+扩容包余额(``extra_quota_bytes``)、合并后的精确可用余量(``available_bytes``),
+以及套餐元信息(``remaining_days`` / ``license_type``)。
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from ._http import API_PREFIX, HttpClient
+
+# 注:remaining_days 单独处理(可为 None 表示永久套餐),不放此列表
+_PUBLIC_INT_FIELDS = (
+    "daily_quota_bytes",
+    "daily_used_bytes",
+    "extra_quota_bytes",
+    "available_bytes",
+)
+
+
+class Quota(TypedDict, total=False):
+    """配额信息字典。
+
+    Attributes:
+        daily_quota_bytes: 今日基础流量额度上限(字节)。次日重置。
+        daily_used_bytes: 今日已用流量(字节)。次日重置。
+        extra_quota_bytes: 扩容包剩余流量(字节)。永久有效,用完为止,默认 0。
+        available_bytes: 当前实际可用余量(字节),三层合并扣除已用与冻结后的精确值。
+        remaining_days: 套餐剩余天数;``None`` 表示永久套餐(如免费版)。
+        license_type: 套餐类型(如 ``"trial"`` / ``"commercial"`` / ``"免费版"``)。
+    """
+
+    daily_quota_bytes: int
+    daily_used_bytes: int
+    extra_quota_bytes: int
+    available_bytes: int
+    remaining_days: int | None
+    license_type: str
+
+
+class QuotaService:
+    """用户配额查询服务。"""
+
+    def __init__(self, http: HttpClient) -> None:
+        """初始化。
+
+        Args:
+            http: HTTP 客户端。
+        """
+        self._http = http
+
+    def get_quota(self) -> Quota:
+        """获取当前用户配额。
+
+        Returns:
+            配额字典,含 ``daily_quota_bytes`` / ``daily_used_bytes`` /
+            ``extra_quota_bytes`` / ``available_bytes`` / ``remaining_days`` /
+            ``license_type`` 六个字段。响应缺失的字段在结果中也会缺失;
+            ``remaining_days`` 可能为 ``None`` 表示永久套餐(如免费版)。
+        """
+        data = self._http.get(f"{API_PREFIX}/quota")
+        if not isinstance(data, dict):
+            return {}
+
+        result: Quota = {}
+        for key in _PUBLIC_INT_FIELDS:
+            if key in data:
+                result[key] = int(data[key])
+        # remaining_days 单独处理:服务端可能返 None(永久套餐),保持 None 不转 int
+        if "remaining_days" in data:
+            value = data["remaining_days"]
+            result["remaining_days"] = None if value is None else int(value)
+        if "license_type" in data:
+            result["license_type"] = str(data["license_type"])
+        return result

quantzone/stock.py

@@ -0,0 +1,49 @@
+"""股票/合约元信息查询服务。
+
+返回 ``DataFrame``,列固定 3 列:``order_book_id / industry_name / symbol``。
+"""
+
+import pandas as pd
+
+from ._http import API_PREFIX, 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(f"{API_PREFIX}/stocks")
+        items = data if isinstance(data, list) else data.get("items", data.get("stocks", []))
+        return _to_dataframe(items)

quantzone-0.5.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: quantzone
+Version: 0.5.0
+Summary: 宽舟科技量化数据平台 Python SDK
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<2.0,>=0.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.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"
+Requires-Dist: tomli; python_version < "3.11" and 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.
+
+## 文档
+
+完整使用文档、API 说明、示例与配额规则请见官网:
+
+**http://www.quantzone.tech**

quantzone-0.5.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+quantzone/__init__.py,sha256=Rkqbbtf0jXhZOEhZRKe7TNkcEfAKo9QsC82PjlBg5YY,3522
+quantzone/_auth.cp39-win_amd64.pyd,sha256=0rEDbPjuD1kb-au8urWBoLGJVZxpTgMv51tEN678WKI,37376
+quantzone/_auth.pyi,sha256=mJJgyic2dHSa-Cbo9iWRN8PbsNcqm5q8FOKDWoQUkAE,144
+quantzone/_dates.py,sha256=gEKMSFPVKb20NrbnVbTyUjwpGMTwLhpTR-i-nlsYLnw,2586
+quantzone/_http.cp39-win_amd64.pyd,sha256=nEKK51d1r6acUnb1Lu2vkZqE5-_uQMXC6oIiSFYIkko,141824
+quantzone/_http.pyi,sha256=Zgz3_yp5LV88mCbFThqyELx8QEb9krNBDKuYnGMOvKs,1470
+quantzone/_logger.py,sha256=KIyFcJpfZ4x4-HbIDQguNVnR_pqEyVPDN7gKfwWsUAY,542
+quantzone/_signer.cp39-win_amd64.pyd,sha256=hsrAh1WKZzXbtqU6VQMEhemKU-QG5fU94slm1i4VwdY,49152
+quantzone/_signer.pyi,sha256=CZyftqqAx8B4EBNMQ4kFdtBZWqrOLH5cmMY0ljwFb9w,151
+quantzone/_singleton.py,sha256=jTqyVnRDKmWkTGaWLJxHEPk6rLTA0457v31rpiEUG4w,2840
+quantzone/calendar.py,sha256=Vts8UXYAjyipaEylTtuL707gNeqt1tk5zSg-gOgjDAg,2936
+quantzone/client.py,sha256=qURt3CJws6ygg8S5a3cSQDPKeVBGxNWplgT20yCZZsE,6221
+quantzone/exceptions.py,sha256=SBSw6V-qs9qL2LoltAtnXZAS4hnO9U0DxnW63gIvH98,3367
+quantzone/factor.py,sha256=xmq_fNZlnS8_kEp9RcMowtnCNMLzYg1fwpOtR33aXqE,9537
+quantzone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quantzone/quota.py,sha256=CqFaWhWR48y0wiI22RIG-t2CUK7eECZZNq2iNiExgXg,2762
+quantzone/stock.py,sha256=tu69BQ2MXmiVfb4qGLiA5Jn63mFP-o8VE5m8r-oRt00,1522
+quantzone-0.5.0.dist-info/METADATA,sha256=GOAldrkbdhZuoyp7DUYJSOEz3al60Wz5zlDiWX8xE6Q,1511
+quantzone-0.5.0.dist-info/WHEEL,sha256=zuNlb9Um05hyCt8XRmFaVi795Ee7Bc9lOiOIpwTM7Gs,99
+quantzone-0.5.0.dist-info/top_level.txt,sha256=81VUVakCg5LCWs-GJ5_jyQ5aTSQPllguMTGwu1h4YEU,10
+quantzone-0.5.0.dist-info/RECORD,,

quantzone-0.5.0.dist-info/WHEEL

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

quantzone-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantzone