powerquant-cli 0.2.6__py3-none-any.whl

pqdata/client.py

@@ -0,0 +1,389 @@
+"""有界、强类型行情客户端；不引入 ORM、供应商 SDK 或应用配置。"""
+
+import asyncio
+from collections.abc import AsyncIterator
+from datetime import date, datetime
+from hashlib import sha256
+from types import TracebackType
+from typing import Any, Self
+from urllib.parse import quote
+
+import httpx
+from pydantic import TypeAdapter, ValidationError
+
+from pqdata.exceptions import MarketAPIError, MarketProtocolError
+from pqdata.schema.adjustment_schema import AdjustedBarSeries, BarViewRequest
+from pqdata.schema.bar_content_schema import BarContent
+from pqdata.schema.bar_schema import BarFrequency, BarPage, BarQuery, BarResponse
+from pqdata.schema.history_schema import HistoryFacts, HistoryFactsQuery
+from pqdata.schema.pit_daily_window import PITDailyWindow
+from pqdata.schema.query_schema import (
+    BarWindowQuery,
+    DataHealthQuery,
+    InstrumentRangeQuery,
+    PITWindowQuery,
+)
+from pqdata.schema.quote_schema import DailyBasicResponse
+from pqdata.schema.reference_schema import (
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+from pqdata.schema.reliability_schema import DatasetHealthResult
+
+
+class MarketClient:
+    """持有一个连接池；通过 async with 或 aclose 显式释放连接。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not 0 <= max_retries <= 5:
+            raise ValueError("max_retries must be between 0 and 5")
+        self._max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/") + "/",
+            headers={"Authorization": f"Bearer {token}"} if token else {},
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    @property
+    def source_id(self) -> str:
+        """服务地址的稳定摘要，用于隔离不同数据源的本地缓存。"""
+        return sha256(str(self._http.base_url).encode("utf-8")).hexdigest()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        response_type: Any,
+        *,
+        params: dict[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        # 所有当前端点均为只读查询；未来写入端点不能复用此重试路径。
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http.request(method, path, params=params, json=body)
+            except httpx.TransportError:
+                if attempt == self._max_retries:
+                    raise
+                await asyncio.sleep(min(0.25 * 2**attempt, 2.0))
+                continue
+            if response.status_code not in {429, 502, 503, 504} or attempt == self._max_retries:
+                break
+            delay = min(0.25 * 2**attempt, 2.0)
+            retry_after = response.headers.get("retry-after", "")
+            if retry_after.isdecimal():
+                delay = min(max(delay, int(retry_after)), 5.0)
+            await response.aclose()
+            await asyncio.sleep(delay)
+        if not response.is_success:
+            raise MarketAPIError(response.status_code, response.headers.get("x-request-id"))
+        try:
+            return TypeAdapter(response_type).validate_json(response.content)
+        except ValidationError as error:
+            raise MarketProtocolError("Invalid market response") from error
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse:
+        return await self._request(
+            "GET",
+            f"instruments/{quote(instrument_id, safe='')}",
+            InstrumentResponse,
+        )
+
+    async def get_history_facts(self, query: HistoryFactsQuery) -> HistoryFacts:
+        result = await self._request(
+            "POST", "history/facts", HistoryFacts, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and result.revision != query.revision:
+            raise MarketProtocolError("History facts revision changed")
+        if result.instrument.instrument_id != query.instrument_id:
+            raise MarketProtocolError("History facts instrument differs from query")
+        return result
+
+    async def get_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> list[BarResponse]:
+        query = BarWindowQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+            limit=limit,
+        )
+        return await self._request(
+            "POST", "bars/window", list[BarResponse], body=query.model_dump(mode="json")
+        )
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> AdjustedBarSeries:
+        query = BarWindowQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+            limit=limit,
+            view=BarViewRequest.model_validate(view.model_dump(mode="json")),
+        )
+        return await self._request(
+            "POST", "bars/view", AdjustedBarSeries, body=query.model_dump(mode="json")
+        )
+
+    async def verify_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+        )
+        return await self._request(
+            "POST", "verify/bars", DatasetHealthResult, body=query.model_dump(mode="json")
+        )
+
+    async def verify_adjustment_factors(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+        )
+        return await self._request(
+            "POST",
+            "verify/adjustment-factors",
+            DatasetHealthResult,
+            body=query.model_dump(mode="json"),
+        )
+
+    async def verify_corporate_actions(
+        self,
+        instrument_id: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(instrument_id=instrument_id, start=start, end=end)
+        return await self._request(
+            "POST",
+            "verify/corporate-actions",
+            DatasetHealthResult,
+            body=query.model_dump(mode="json"),
+        )
+
+    async def snapshot(self, start: date, end: date) -> dict[str, str]:
+        return await self._request(
+            "GET",
+            "revisions",
+            dict[str, str],
+            params={
+                "start": start.isoformat(),
+                "end": end.isoformat(),
+            },
+        )
+
+    async def search_instruments(
+        self,
+        keyword: str | None = None,
+        instrument_type: str | None = None,
+        exchange: str | None = None,
+        limit: int = 100,
+    ) -> list[InstrumentResponse]:
+        params = {
+            key: value
+            for key, value in {
+                "keyword": keyword,
+                "instrument_type": instrument_type,
+                "exchange": exchange,
+                "limit": limit,
+            }.items()
+            if value is not None
+        }
+        return await self._request("GET", "instruments", list[InstrumentResponse], params=params)
+
+    async def list_instruments_on(
+        self, on_date: date, limit: int = 10000
+    ) -> list[InstrumentResponse]:
+        return await self._request(
+            "GET",
+            "universe",
+            list[InstrumentResponse],
+            params={
+                "on_date": on_date.isoformat(),
+                "limit": limit,
+            },
+        )
+
+    async def list_trading_rules(
+        self,
+        instrument_ids: list[str],
+        start: date,
+        end: date,
+    ) -> list[TradingRuleResponse]:
+        query = InstrumentRangeQuery(instrument_ids=instrument_ids, start=start, end=end)
+        return await self._request(
+            "POST",
+            "trading-rules/query",
+            list[TradingRuleResponse],
+            body=query.model_dump(mode="json"),
+        )
+
+    async def list_trading_days(
+        self,
+        exchange: str,
+        start: date,
+        end: date,
+    ) -> list[TradingCalendarDayResponse]:
+        return await self._request(
+            "GET",
+            "calendar",
+            list[TradingCalendarDayResponse],
+            params={
+                "exchange": exchange,
+                "start": start.isoformat(),
+                "end": end.isoformat(),
+            },
+        )
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool:
+        return await self._request(
+            "GET",
+            "calendar/is-open",
+            bool,
+            params={
+                "exchange": exchange,
+                "trade_date": trade_date.isoformat(),
+            },
+        )
+
+    async def list_daily_basic_at(
+        self,
+        decision_time: datetime,
+        limit: int = 10000,
+    ) -> list[DailyBasicResponse]:
+        return await self._request(
+            "GET",
+            "daily-basic/visible",
+            list[DailyBasicResponse],
+            params={
+                "decision_time": decision_time.isoformat(),
+                "limit": limit,
+            },
+        )
+
+    async def get_pit_daily_windows(
+        self,
+        instrument_id: str,
+        days: list[date],
+        next_days: list[date],
+        lookback: int,
+    ) -> tuple[PITDailyWindow, ...]:
+        query = PITWindowQuery(
+            instrument_id=instrument_id,
+            days=days,
+            next_days=next_days,
+            lookback=lookback,
+        )
+        return await self._request(
+            "POST",
+            "bars/pit-windows",
+            tuple[PITDailyWindow, ...],
+            body=query.model_dump(mode="json"),
+        )
+
+    async def query_bars(self, query: BarQuery) -> BarPage:
+        """读取一页数据；错误内容不混入行情结果。"""
+        page = await self._request(
+            "POST", "bars/query", BarPage, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and page.revision != query.revision:
+            raise MarketProtocolError("Market revision changed during pagination")
+        if len(page.items) > query.page_size:
+            raise MarketProtocolError("Server exceeded requested page size")
+        previous: tuple | None = None
+        for bar in page.items:
+            key = (bar.timestamp, bar.instrument_id)
+            if (
+                bar.instrument_id not in query.instrument_ids
+                or bar.frequency != query.frequency
+                or not query.start <= bar.timestamp <= query.end
+                or (previous is not None and key <= previous)
+            ):
+                raise MarketProtocolError("Bar page violates query range or ordering")
+            previous = key
+        return page
+
+    async def describe_bars(self, query: BarQuery) -> BarContent:
+        """只传输范围摘要；服务端仍需扫描数据，不能视为常数成本的查询。"""
+        if query.cursor is not None:
+            raise ValueError("Content queries must start at the first page")
+        result = await self._request(
+            "POST", "bars/content", BarContent, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and result.revision != query.revision:
+            raise MarketProtocolError("Content revision differs from query")
+        return result
+
+    async def iter_bar_pages(self, query: BarQuery) -> AsyncIterator[BarPage]:
+        """逐页消费，固定 revision，检测重复游标与跨页重复数据。"""
+        seen: set[str] = {query.cursor} if query.cursor else set()
+        previous: tuple | None = None
+        while True:
+            page = await self.query_bars(query)
+            if previous is not None and page.items:
+                first = page.items[0]
+                if (first.timestamp, first.instrument_id) <= previous:
+                    raise MarketProtocolError("Bar pages overlap or are out of order")
+            if page.next_cursor and (page.next_cursor in seen or not page.items):
+                raise MarketProtocolError("Pagination did not advance")
+            yield page
+            if page.next_cursor is None:
+                return
+            last = page.items[-1]
+            previous = (last.timestamp, last.instrument_id)
+            seen.add(page.next_cursor)
+            query = query.model_copy(update={"cursor": page.next_cursor, "revision": page.revision})

pqdata/download.py

@@ -0,0 +1,60 @@
+"""流式落盘；完整下载后才替换目标文件，失败保留原文件。"""
+
+import hashlib
+import os
+import tempfile
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from pqdata.client import MarketClient
+from pqdata.schema.bar_schema import BarQuery
+
+
+class DownloadReceipt(BaseModel):
+    """供本地缓存记录查询条件、版本及内容校验和。"""
+
+    query: BarQuery
+    revision: str
+    row_count: int = Field(ge=0)
+    byte_count: int = Field(ge=0)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+async def download_bars(
+    client: MarketClient, query: BarQuery, destination: Path
+) -> DownloadReceipt:
+    """完整范围以 JSON Lines 落盘；内存上限为一页数据。"""
+    if query.cursor is not None:
+        raise ValueError("Downloads must start at the first page")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary: Path | None = None
+    digest = hashlib.sha256()
+    row_count = byte_count = 0
+    revision = ""
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb", dir=destination.parent, prefix=".market-", suffix=".part", delete=False
+        ) as output:
+            temporary = Path(output.name)
+            async for page in client.iter_bar_pages(query):
+                revision = page.revision
+                for bar in page.items:
+                    line = (bar.model_dump_json() + "\n").encode("utf-8")
+                    output.write(line)
+                    digest.update(line)
+                    row_count += 1
+                    byte_count += len(line)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, destination)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return DownloadReceipt(
+        query=query,
+        revision=revision,
+        row_count=row_count,
+        byte_count=byte_count,
+        sha256=digest.hexdigest(),
+    )

pqdata/exceptions.py

@@ -0,0 +1,14 @@
+"""客户端错误不依赖服务端异常实现。"""
+
+
+class MarketAPIError(Exception):
+    """服务拒绝请求；保留状态码和可追踪的请求 ID，不暴露凭据。"""
+
+    def __init__(self, status_code: int, request_id: str | None = None) -> None:
+        self.status_code = status_code
+        self.request_id = request_id
+        super().__init__(f"Market request failed (HTTP {status_code}, request_id={request_id})")
+
+
+class MarketProtocolError(Exception):
+    """响应不符合契约或下载内容不一致，禁止继续消费。"""

pqdata/schema/__init__.py

@@ -0,0 +1 @@
+"""客户端公开数据契约。"""

pqdata/schema/adjustment_schema.py

@@ -0,0 +1,67 @@
+"""复权因子与价格视图契约。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from pqdata.schema.bar_schema import BarResponse
+
+
+class AdjustmentType(str, Enum):
+    NONE = "none"
+    PRE = "pre"
+    POST = "post"
+
+
+class AdjustmentAnchorMode(str, Enum):
+    FIXED_DATE = "fixed_date"
+    LATEST = "latest"
+    DECISION_TIME = "decision_time"
+
+
+class AdjustmentFactorResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str
+    trade_date: date
+    factor: Decimal = Field(gt=0)
+    dataset_revision: str
+    source_provider: str
+    source_updated_at: datetime | None = None
+    recorded_at: datetime
+
+
+class AdjustedBarResponse(BarResponse):
+    """BarResponse 的合成视图；仅放宽 volume 为可含小数的 Decimal。"""
+
+    volume: Decimal
+
+
+class BarViewRequest(BaseModel):
+    adjustment_type: AdjustmentType = AdjustmentType.NONE
+    anchor_mode: AdjustmentAnchorMode | None = None
+    anchor_date: date | None = None
+    decision_time: datetime | None = None
+    known_at: datetime | None = None
+
+    @model_validator(mode="after")
+    def validate_anchor(self) -> "BarViewRequest":
+        if self.adjustment_type in {AdjustmentType.NONE, AdjustmentType.POST}:
+            return self
+        if self.anchor_mode is None:
+            raise ValueError("复权查询必须指定 anchor_mode")
+        if self.anchor_mode is AdjustmentAnchorMode.FIXED_DATE and self.anchor_date is None:
+            raise ValueError("fixed_date 必须指定 anchor_date")
+        if self.anchor_mode is AdjustmentAnchorMode.DECISION_TIME and self.decision_time is None:
+            raise ValueError("decision_time 模式必须指定 decision_time")
+        return self
+
+
+class AdjustedBarSeries(BaseModel):
+    instrument_id: str
+    adjustment_type: AdjustmentType
+    anchor_date: date | None
+    factor_revision: str | None
+    bars: list[AdjustedBarResponse | BarResponse]

pqdata/schema/bar_content_schema.py

@@ -0,0 +1,24 @@
+"""范围内容凭据；摘要包含完整行，能识别更正、补数和删除。"""
+
+import hashlib
+from collections.abc import Iterable
+
+from pydantic import BaseModel, Field
+
+from pqdata.schema.bar_schema import BarResponse
+
+
+class BarContent(BaseModel):
+    """查询范围的内容身份，不宣称该范围已完成行情质量验收。"""
+
+    revision: str
+    row_count: int = Field(ge=0)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+def bar_content_digest(rows: Iterable[BarResponse]) -> str:
+    """以分页规范的行顺序计算摘要，避免浮点转换损失价格精度。"""
+    digest = hashlib.sha256()
+    for row in rows:
+        digest.update((row.model_dump_json() + "\n").encode("utf-8"))
+    return digest.hexdigest()

pqdata/schema/bar_schema.py

@@ -0,0 +1,56 @@
+"""标准行情与有界批量读取契约；时间戳表示 Bar 结束时间。"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+BarFrequency = Literal["1m", "5m", "15m", "30m", "1h", "1d", "1w"]
+
+
+class BarResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, frozen=True)
+
+    instrument_id: str
+    timestamp: AwareDatetime
+    frequency: BarFrequency
+    open: Decimal
+    high: Decimal
+    low: Decimal
+    close: Decimal
+    volume: int = Field(ge=0)
+    amount: Decimal | None = None
+    previous_close: Decimal | None = None
+    suspended: bool
+
+
+class BarQuery(BaseModel):
+    """批量范围与游标；每页按 timestamp、instrument_id 稳定排序。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    instrument_ids: list[str] = Field(min_length=1, max_length=1000)
+    frequency: BarFrequency
+    start: AwareDatetime
+    end: AwareDatetime
+    page_size: int = Field(default=10000, ge=1, le=100000)
+    cursor: str | None = Field(default=None, max_length=8192)
+    revision: str | None = None
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "BarQuery":
+        if self.start > self.end:
+            raise ValueError("start must not be after end")
+        if len(set(self.instrument_ids)) != len(self.instrument_ids):
+            raise ValueError("instrument_ids must be unique")
+        return self
+
+
+class BarPage(BaseModel):
+    """revision 在分页期间必须稳定；内容被修订时服务返回冲突。"""
+
+    items: list[BarResponse]
+    revision: str = Field(min_length=1)
+    next_cursor: str | None = None
+    generated_at: datetime

pqdata/schema/corporate_action_schema.py

@@ -0,0 +1,46 @@
+"""公司行动 Canonical Fact 与运行时阶段事件。"""
+
+from datetime import date
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class CorporateActionPhase(str, Enum):
+    RECORD = "record"
+    EX_DATE = "ex_date"
+    LISTING_DATE = "listing_date"
+    PAY_DATE = "pay_date"
+
+
+class CorporateActionResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    action_id: str
+    instrument_id: str
+    record_date: date
+    ex_date: date
+    pay_date: date | None = None
+    listing_date: date | None = None
+    cash_per_share: Decimal = Field(Decimal(0), ge=0)
+    stock_ratio: Decimal = Field(Decimal(0), ge=0)
+    dataset_revision: str
+    source_provider: str
+
+    @model_validator(mode="after")
+    def validate_dates_and_value(self) -> "CorporateActionResponse":
+        if self.record_date > self.ex_date:
+            raise ValueError("公司行动日期必须满足 record_date <= ex_date")
+        if self.cash_per_share == 0 and self.stock_ratio == 0:
+            raise ValueError("公司行动必须至少包含现金或送转比例")
+        if self.cash_per_share > 0 and (self.pay_date is None or self.pay_date < self.ex_date):
+            raise ValueError("现金分红必须有不早于 ex_date 的 pay_date")
+        if self.stock_ratio > 0 and (self.listing_date is None or self.listing_date < self.ex_date):
+            raise ValueError("送转股必须有不早于 ex_date 的 listing_date")
+        return self
+
+
+class CorporateActionEventPayload(BaseModel):
+    action: CorporateActionResponse
+    phase: CorporateActionPhase