pyqauto 0.3.0__py3-none-any.whl

pyqauto/__init__.py

@@ -0,0 +1,133 @@
+"""Simple public API for pyqauto."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .models import KlineBar, QuoteRecord
+from .router import QuoteRouter
+
+__version__ = "0.3.0"
+
+_default_router: QuoteRouter | None = None
+
+
+def configure(
+    *,
+    pytdx_servers_path: str | Path | None = None,
+    source_policy_path: str | Path | None = None,
+    audit_jsonl_path: str | Path | None = None,
+    audit_sqlite_path: str | Path | None = None,
+) -> QuoteRouter:
+    """Configure and cache the default router for module-level calls."""
+
+    global _default_router
+    _default_router = QuoteRouter.from_config(
+        pytdx_servers_path=pytdx_servers_path,
+        source_policy_path=source_policy_path,
+        audit_jsonl_path=audit_jsonl_path,
+        audit_sqlite_path=audit_sqlite_path,
+    )
+    return _default_router
+
+
+def get_router() -> QuoteRouter:
+    """Return the cached default router, creating it from bundled defaults."""
+
+    global _default_router
+    if _default_router is None:
+        _default_router = QuoteRouter.from_config()
+    return _default_router
+
+
+def quote(symbol: str, *, include_raw: bool = False) -> QuoteRecord:
+    """Fetch one realtime quote."""
+
+    return get_router().realtime_quotes([symbol], include_raw=include_raw)[0]
+
+
+def quotes(symbols: list[str], *, include_raw: bool = False) -> list[QuoteRecord]:
+    """Fetch realtime quotes."""
+
+    return get_router().realtime_quotes(list(symbols), include_raw=include_raw)
+
+
+def full_quotes(symbols: list[str], *, include_raw: bool = False) -> list[QuoteRecord]:
+    """Fetch full realtime quotes."""
+
+    return get_router().full_realtime_quotes(list(symbols), include_raw=include_raw)
+
+
+def index(symbols: list[str], *, include_raw: bool = False) -> list[QuoteRecord]:
+    """Fetch index realtime quotes."""
+
+    return get_router().index_realtime(list(symbols), include_raw=include_raw)
+
+
+def minute(
+    symbol: str,
+    *,
+    period: str = "1m",
+    count: int = 240,
+    include_raw: bool = False,
+) -> list[KlineBar]:
+    """Fetch pytdx-only minute K-line bars."""
+
+    return get_router().minute_kline(
+        symbol,
+        period=period,
+        count=count,
+        include_raw=include_raw,
+    )
+
+
+def daily(
+    symbol: str,
+    *,
+    count: int = 120,
+    include_raw: bool = False,
+) -> list[KlineBar]:
+    """Fetch pytdx-only daily K-line bars."""
+
+    return get_router().daily_kline(symbol, count=count, include_raw=include_raw)
+
+
+def kline(
+    symbol: str,
+    *,
+    period: str = "1m",
+    count: int = 120,
+    include_raw: bool = False,
+) -> list[KlineBar]:
+    """Fetch K-line bars through the unified K-line API."""
+
+    return get_router().kline(
+        symbol,
+        period=period,
+        count=count,
+        include_raw=include_raw,
+    )
+
+
+def diagnose() -> dict:
+    """Return local router configuration without connecting to providers."""
+
+    return get_router().diagnose()
+
+
+__all__ = [
+    "KlineBar",
+    "QuoteRecord",
+    "QuoteRouter",
+    "__version__",
+    "configure",
+    "daily",
+    "diagnose",
+    "full_quotes",
+    "get_router",
+    "index",
+    "kline",
+    "minute",
+    "quote",
+    "quotes",
+]

pyqauto/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Quote source adapters."""
+
+from .easyquotation_sina_adapter import EasyQuotationSinaAdapter
+from .easyquotation_tencent_adapter import EasyQuotationTencentAdapter
+from .pytdx_adapter import PytdxAdapter
+
+__all__ = [
+    "EasyQuotationSinaAdapter",
+    "EasyQuotationTencentAdapter",
+    "PytdxAdapter",
+]

pyqauto/adapters/base.py

@@ -0,0 +1,139 @@
+"""Base adapter contracts and shared helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyqauto.exceptions import AdapterError, UnsupportedSymbolError
+from pyqauto.models import KlineBar, QuoteRecord
+
+
+@dataclass(frozen=True)
+class PytdxServer:
+    """One pytdx server configuration entry."""
+
+    host: str
+    port: int
+    role: str
+    latency_ms: int
+    enabled: bool = True
+
+
+@dataclass(frozen=True)
+class NormalizedSymbol:
+    """Provider-ready symbol code and pytdx market id."""
+
+    code: str
+    market: int
+    suffix: str | None = None
+
+
+class BaseQuoteAdapter:
+    """Synchronous quote adapter interface."""
+
+    source: str = "unknown"
+    source_level: str | None = None
+
+    def realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        raise AdapterError(f"{self.source} does not support realtime_quotes")
+
+    def full_realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self.realtime_quotes(symbols, include_raw=include_raw)
+
+    def index_realtime(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self.realtime_quotes(symbols, include_raw=include_raw)
+
+    def minute_kline(
+        self,
+        symbol: str,
+        *,
+        period: str = "1m",
+        count: int = 240,
+        include_raw: bool = False,
+    ) -> list[KlineBar]:
+        raise AdapterError(f"{self.source} does not support minute_kline")
+
+    def daily_kline(
+        self,
+        symbol: str,
+        *,
+        count: int = 120,
+        include_raw: bool = False,
+    ) -> list[KlineBar]:
+        raise AdapterError(f"{self.source} does not support daily_kline")
+
+
+def as_float(value: Any) -> float | None:
+    """Best-effort conversion to float with empty values mapped to None."""
+
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def first_value(row: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    """Return the first present value for a tuple of candidate keys."""
+
+    for key in keys:
+        if key in row and row[key] not in (None, ""):
+            return row[key]
+    return None
+
+
+def market_for_symbol(symbol: str) -> int:
+    """Return pytdx market id for a common A-share symbol."""
+
+    return normalize_symbol(symbol).market
+
+
+def code_for_symbol(symbol: str) -> str:
+    """Return the six-digit provider code for a documented symbol."""
+
+    return normalize_symbol(symbol).code
+
+
+def normalize_symbol(symbol: str) -> NormalizedSymbol:
+    """Normalize documented A-share symbol forms.
+
+    Supported forms are six digits and six digits followed by .SH or .SZ.
+    Bare 6/5/9 prefixes use Shanghai, while bare 0/3 prefixes use Shenzhen.
+    """
+
+    raw = str(symbol or "").strip().upper()
+    if "." in raw:
+        code, separator, suffix = raw.partition(".")
+        if separator != "." or suffix not in {"SH", "SZ"}:
+            raise UnsupportedSymbolError(f"unsupported symbol suffix: {symbol}")
+        if not _is_six_digit_code(code):
+            raise UnsupportedSymbolError(f"unsupported symbol code: {symbol}")
+        return NormalizedSymbol(code=code, market=1 if suffix == "SH" else 0, suffix=suffix)
+
+    if not _is_six_digit_code(raw):
+        raise UnsupportedSymbolError(f"unsupported symbol code: {symbol}")
+    if raw.startswith(("5", "6", "9")):
+        return NormalizedSymbol(code=raw, market=1)
+    if raw.startswith(("0", "3")):
+        return NormalizedSymbol(code=raw, market=0)
+    raise UnsupportedSymbolError(f"unsupported symbol prefix: {symbol}")
+
+
+def source_id(source: str, source_level: str | None) -> str:
+    """Return a compact source identifier for fallback chains."""
+
+    if source_level:
+        return f"{source}:{source_level}"
+    return source
+
+
+def _is_six_digit_code(value: str) -> bool:
+    return len(value) == 6 and value.isdigit()

pyqauto/adapters/easyquotation_sina_adapter.py

@@ -0,0 +1,100 @@
+"""easyquotation Sina adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyqauto.adapters.base import (
+    BaseQuoteAdapter,
+    as_float,
+    code_for_symbol,
+    first_value,
+)
+from pyqauto.exceptions import AdapterError, ErrorCode, SourceUnavailableError
+from pyqauto.models import QuoteRecord
+
+
+class EasyQuotationSinaAdapter(BaseQuoteAdapter):
+    """Adapter for easyquotation's Sina provider."""
+
+    source = "easyquotation_sina"
+    provider = "sina"
+
+    def realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def full_realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def index_realtime(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._stocks(symbols, include_raw=include_raw)
+
+    def _stocks(self, symbols: list[str], *, include_raw: bool) -> list[QuoteRecord]:
+        if not symbols:
+            return []
+
+        normalized_symbols = [code_for_symbol(symbol) for symbol in symbols]
+        quotation = self._quotation()
+        data = quotation.stocks(normalized_symbols)
+        if not data:
+            raise SourceUnavailableError(
+                f"{self.source} returned no quote records",
+                code=_source_error_code(self.source),
+            )
+
+        records: list[QuoteRecord] = []
+        for symbol in normalized_symbols:
+            row = data.get(symbol) or data.get(symbol.lower()) or data.get(symbol.upper())
+            if row:
+                records.append(self._normalize(symbol, row, include_raw=include_raw))
+        if not records:
+            raise SourceUnavailableError(
+                f"{self.source} returned no requested symbols",
+                code=_source_error_code(self.source),
+            )
+        return records
+
+    def _quotation(self) -> Any:
+        try:
+            import easyquotation
+        except Exception as exc:  # pragma: no cover - depends on user env
+            raise AdapterError("easyquotation package is not available") from exc
+        return easyquotation.use(self.provider)
+
+    def _normalize(
+        self, symbol: str, row: dict[str, Any], *, include_raw: bool
+    ) -> QuoteRecord:
+        date_value = first_value(row, ("date",))
+        time_value = first_value(row, ("time",))
+        if date_value and time_value:
+            dt_value = f"{date_value} {time_value}"
+        else:
+            dt_value = str(first_value(row, ("datetime", "time")) or "") or None
+
+        return QuoteRecord(
+            symbol=symbol,
+            name=first_value(row, ("name",)),
+            price=as_float(first_value(row, ("now", "price", "close"))),
+            open=as_float(first_value(row, ("open",))),
+            high=as_float(first_value(row, ("high",))),
+            low=as_float(first_value(row, ("low",))),
+            pre_close=as_float(first_value(row, ("close", "pre_close", "last_close"))),
+            volume=as_float(first_value(row, ("volume", "vol"))),
+            amount=as_float(first_value(row, ("turnover", "amount"))),
+            datetime=dt_value,
+            source=self.source,
+            source_level=self.source_level,
+            raw=dict(row) if include_raw else None,
+        )
+
+
+def _source_error_code(source: str) -> ErrorCode:
+    if source == "easyquotation_tencent":
+        return ErrorCode.EASYQUOTATION_TENCENT_FAILED
+    return ErrorCode.EASYQUOTATION_SINA_FAILED

pyqauto/adapters/easyquotation_tencent_adapter.py

@@ -0,0 +1,10 @@
+"""easyquotation Tencent adapter."""
+
+from pyqauto.adapters.easyquotation_sina_adapter import EasyQuotationSinaAdapter
+
+
+class EasyQuotationTencentAdapter(EasyQuotationSinaAdapter):
+    """Adapter for easyquotation's Tencent provider."""
+
+    source = "easyquotation_tencent"
+    provider = "tencent"

pyqauto/adapters/pytdx_adapter.py

@@ -0,0 +1,222 @@
+"""pytdx quote adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyqauto.adapters.base import (
+    BaseQuoteAdapter,
+    PytdxServer,
+    as_float,
+    code_for_symbol,
+    first_value,
+    market_for_symbol,
+)
+from pyqauto.exceptions import (
+    AdapterError,
+    ErrorCode,
+    SourceUnavailableError,
+    UnsupportedPeriodError,
+)
+from pyqauto.models import KlineBar, QuoteRecord
+from pyqauto.policy import (
+    SUPPORTED_DAILY_KLINE_PERIODS,
+    SUPPORTED_MINUTE_KLINE_PERIODS,
+)
+
+# pytdx get_security_bars category values for supported K-line periods.
+PYTDX_KLINE_PERIOD_CATEGORIES = {
+    "5m": 0,
+    "15m": 1,
+    "30m": 2,
+    "60m": 3,
+    "1d": 4,
+    "1m": 7,
+}
+
+
+class PytdxAdapter(BaseQuoteAdapter):
+    """Adapter for one pytdx server entry."""
+
+    source = "pytdx"
+
+    def __init__(self, server: PytdxServer, *, timeout: float = 3.0) -> None:
+        self.server = server
+        self.source_level = server.role
+        self.timeout = timeout
+
+    def realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._security_quotes(symbols, include_raw=include_raw)
+
+    def full_realtime_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._security_quotes(symbols, include_raw=include_raw)
+
+    def index_realtime(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        return self._security_quotes(symbols, include_raw=include_raw)
+
+    def minute_kline(
+        self,
+        symbol: str,
+        *,
+        period: str = "1m",
+        count: int = 240,
+        include_raw: bool = False,
+    ) -> list[KlineBar]:
+        if period not in SUPPORTED_MINUTE_KLINE_PERIODS:
+            supported = ", ".join(SUPPORTED_MINUTE_KLINE_PERIODS)
+            raise UnsupportedPeriodError(
+                f"unsupported pytdx minute period: {period}; supported: {supported}"
+            )
+        return self._security_bars(
+            symbol,
+            period=period,
+            count=count,
+            include_raw=include_raw,
+            empty_message="pytdx returned no minute_kline records",
+        )
+
+    def daily_kline(
+        self,
+        symbol: str,
+        *,
+        count: int = 120,
+        include_raw: bool = False,
+    ) -> list[KlineBar]:
+        period = SUPPORTED_DAILY_KLINE_PERIODS[0]
+        return self._security_bars(
+            symbol,
+            period=period,
+            count=count,
+            include_raw=include_raw,
+            empty_message="pytdx returned no daily_kline records",
+        )
+
+    def _security_bars(
+        self,
+        symbol: str,
+        *,
+        period: str,
+        count: int,
+        include_raw: bool,
+        empty_message: str,
+    ) -> list[KlineBar]:
+        category = PYTDX_KLINE_PERIOD_CATEGORIES.get(period)
+        if category is None:
+            supported = ", ".join(PYTDX_KLINE_PERIOD_CATEGORIES)
+            raise UnsupportedPeriodError(
+                f"unsupported pytdx kline period: {period}; supported: {supported}"
+            )
+        normalized_symbol = code_for_symbol(symbol)
+        api = self._new_api()
+        self._connect(api)
+        try:
+            rows = api.get_security_bars(
+                category, market_for_symbol(symbol), normalized_symbol, 0, count
+            )
+        finally:
+            self._disconnect(api)
+
+        if not rows:
+            raise SourceUnavailableError(empty_message)
+        return [
+            self._normalize_kline_row(
+                normalized_symbol,
+                row,
+                period=period,
+                include_raw=include_raw,
+            )
+            for row in rows
+        ]
+
+    def _security_quotes(
+        self, symbols: list[str], *, include_raw: bool = False
+    ) -> list[QuoteRecord]:
+        if not symbols:
+            return []
+
+        api = self._new_api()
+        self._connect(api)
+        try:
+            request_symbols = [
+                (market_for_symbol(symbol), code_for_symbol(symbol)) for symbol in symbols
+            ]
+            rows = api.get_security_quotes(request_symbols)
+        finally:
+            self._disconnect(api)
+
+        if not rows:
+            raise SourceUnavailableError("pytdx returned no quote records")
+        return [
+            self._normalize_quote_row(row, include_raw=include_raw)
+            for row in rows
+        ]
+
+    def _new_api(self) -> Any:
+        try:
+            from pytdx.hq import TdxHq_API
+        except Exception as exc:  # pragma: no cover - depends on user env
+            raise AdapterError("pytdx package is not available") from exc
+        return TdxHq_API(heartbeat=True, auto_retry=False)
+
+    def _connect(self, api: Any) -> None:
+        connected = api.connect(self.server.host, self.server.port, time_out=self.timeout)
+        if not connected:
+            raise SourceUnavailableError(
+                "pytdx server connection failed",
+                code=ErrorCode.PYTDX_CONNECT_FAILED,
+            )
+
+    def _disconnect(self, api: Any) -> None:
+        try:
+            api.disconnect()
+        except Exception:
+            return
+
+    def _normalize_quote_row(
+        self, row: dict[str, Any], *, include_raw: bool
+    ) -> QuoteRecord:
+        symbol = str(first_value(row, ("code", "symbol")) or "")
+        return QuoteRecord(
+            symbol=symbol,
+            name=first_value(row, ("name",)),
+            price=as_float(first_value(row, ("price", "now", "close"))),
+            open=as_float(first_value(row, ("open",))),
+            high=as_float(first_value(row, ("high",))),
+            low=as_float(first_value(row, ("low",))),
+            pre_close=as_float(first_value(row, ("last_close", "pre_close", "close"))),
+            volume=as_float(first_value(row, ("vol", "volume"))),
+            amount=as_float(first_value(row, ("amount",))),
+            datetime=str(first_value(row, ("datetime", "time")) or "") or None,
+            source=self.source,
+            source_level=self.source_level,
+            raw=dict(row) if include_raw else None,
+        )
+
+    def _normalize_kline_row(
+        self,
+        symbol: str,
+        row: dict[str, Any],
+        *,
+        period: str,
+        include_raw: bool,
+    ) -> KlineBar:
+        return KlineBar(
+            symbol=symbol,
+            close=as_float(first_value(row, ("close", "price"))),
+            open=as_float(first_value(row, ("open",))),
+            high=as_float(first_value(row, ("high",))),
+            low=as_float(first_value(row, ("low",))),
+            volume=as_float(first_value(row, ("vol", "volume"))),
+            amount=as_float(first_value(row, ("amount",))),
+            datetime=str(first_value(row, ("datetime", "time")) or "") or None,
+            period=period,
+            source=self.source,
+            source_level=self.source_level,
+            raw=dict(row) if include_raw else None,
+        )