easyquotes 0.1.0__py3-none-any.whl

easyquote/__init__.py

@@ -0,0 +1,24 @@
+"""EasyQuote Python SDK — Global market data in a few lines of code."""
+from ._client import EasyQuoteClient
+from ._exceptions import APIError, AuthError, EasyQuoteError, NotFoundError, RateLimitError
+from ._models import Company, Executive, FinancialReport, FundFlow, KLine, MinuteBar, Quote
+
+__all__ = [
+    "EasyQuoteClient",
+    # Models
+    "Quote",
+    "KLine",
+    "MinuteBar",
+    "FundFlow",
+    "Company",
+    "Executive",
+    "FinancialReport",
+    # Exceptions
+    "EasyQuoteError",
+    "AuthError",
+    "RateLimitError",
+    "NotFoundError",
+    "APIError",
+]
+
+__version__ = "0.1.0"

easyquote/_client.py

@@ -0,0 +1,469 @@
+"""EasyQuote synchronous HTTP client."""
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+import json as _json
+
+from ._exceptions import APIError, AuthError, NotFoundError, RateLimitError
+from ._models import Company, Executive, FinancialReport, FundFlow, KLine, MinuteBar, Quote
+from ._parse import (
+    parse_company,
+    parse_executive,
+    parse_financial_report,
+    parse_kline,
+    parse_minute,
+    parse_quote,
+    split_symbol,
+)
+from ._ws import RealtimeStream
+
+_DEFAULT_BASE_URL = "https://api.easyquote.io"
+
+
+class EasyQuoteClient:
+    """EasyQuote API client.
+
+    Args:
+        api_key: Your API key (``eq_`` prefix). Falls back to the
+            ``EASYQUOTE_API_KEY`` environment variable.
+        base_url: Override the API base URL (useful for self-hosted deployments).
+        timeout: HTTP request timeout in seconds (default 30).
+
+    Example::
+
+        from easyquote import EasyQuoteClient
+
+        client = EasyQuoteClient(api_key="eq_xxx")
+
+        quote = client.get_quote("600519.SH")
+        print(f"{quote.name}: {quote.price} ({quote.change_pct:+.2f}%)")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = 30,
+    ) -> None:
+        self._api_key = api_key or os.environ.get("EASYQUOTE_API_KEY") or ""
+        if not self._api_key:
+            raise AuthError(
+                "No API key provided. Pass api_key= or set EASYQUOTE_API_KEY env var."
+            )
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers                                                      #
+    # ------------------------------------------------------------------ #
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        url = f"{self._base_url}/api/v1{path}"
+        if params:
+            filtered = {k: v for k, v in params.items() if v is not None}
+            url = f"{url}?{urlencode(filtered)}"
+        req = Request(url, headers={"x-api-key": self._api_key})
+        try:
+            with urlopen(req, timeout=self._timeout) as resp:
+                body = _json.loads(resp.read())
+        except Exception as exc:
+            raise APIError(0, str(exc)) from exc
+        return self._unwrap(body)
+
+    def _post(self, path: str, payload: Any) -> Any:
+        url = f"{self._base_url}/api/v1{path}"
+        data = _json.dumps(payload).encode()
+        req = Request(
+            url,
+            data=data,
+            headers={"x-api-key": self._api_key, "Content-Type": "application/json"},
+        )
+        try:
+            with urlopen(req, timeout=self._timeout) as resp:
+                body = _json.loads(resp.read())
+        except Exception as exc:
+            raise APIError(0, str(exc)) from exc
+        return self._unwrap(body)
+
+    @staticmethod
+    def _unwrap(body: dict[str, Any]) -> Any:
+        code = body.get("code", 0)
+        if code == 200 or code == 0:
+            return body.get("data")
+        if code == 401:
+            raise AuthError(body.get("msg", "Unauthorized"))
+        if code == 429:
+            raise RateLimitError(body.get("msg", "Rate limit exceeded"))
+        if code == 404:
+            raise NotFoundError(body.get("msg", "Not found"))
+        raise APIError(code, body.get("msg", "Unknown error"))
+
+    @staticmethod
+    def _market_code(symbol: str) -> tuple[str, str]:
+        return split_symbol(symbol)
+
+    def _sym(self, symbol: str) -> tuple[str, str]:
+        return split_symbol(symbol)
+
+    # ------------------------------------------------------------------ #
+    # Quotes                                                                #
+    # ------------------------------------------------------------------ #
+
+    def get_quote(self, symbol: str) -> Quote:
+        """Get real-time quote for a single symbol.
+
+        Args:
+            symbol: e.g. ``"600519.SH"``, ``"TSLA.US"``, ``"00700.HK"``
+
+        Returns:
+            :class:`Quote` object.
+        """
+        return self.get_quotes([symbol])[0]
+
+    def get_quotes(self, symbols: list[str]) -> list[Quote]:
+        """Get real-time quotes for multiple symbols (batch).
+
+        Args:
+            symbols: List of symbols, e.g. ``["600519.SH", "000001.SZ", "TSLA.US"]``
+
+        Returns:
+            List of :class:`Quote` objects in the same order as input.
+        """
+        payload: list[dict[str, Any]] = []
+        for sym in symbols:
+            market, code = self._market_code(sym)
+            payload.append({"market": market, "code": code})
+        data = self._post("/quotes", {"stocks": payload})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_quote(r, sym) for r, sym in zip(rows, symbols)]
+
+    # ------------------------------------------------------------------ #
+    # K-lines                                                               #
+    # ------------------------------------------------------------------ #
+
+    def get_klines(
+        self,
+        symbol: str,
+        period: str = "daily",
+        count: int = 200,
+        start: int | None = None,
+    ) -> list[KLine]:
+        """Get historical K-lines.
+
+        Args:
+            symbol: e.g. ``"600519.SH"``
+            period: ``"1m"`` / ``"5m"`` / ``"15m"`` / ``"30m"`` / ``"60m"`` /
+                ``"daily"`` / ``"weekly"`` / ``"monthly"``
+            count: Number of bars to return (max 800).
+            start: Start index (0 = latest).
+
+        Returns:
+            List of :class:`KLine` objects, oldest first.
+        """
+        _period_map = {
+            "1m": "MIN_1", "5m": "MIN_5", "15m": "MIN_15",
+            "30m": "MIN_30", "60m": "MIN_60",
+            "daily": "DAY", "day": "DAY",
+            "weekly": "WEEK", "week": "WEEK",
+            "monthly": "MONTH", "month": "MONTH",
+        }
+        category = _period_map.get(period.lower(), period.upper())
+        market, code = self._market_code(symbol)
+        data = self._get("/bars", {"market": market, "code": code, "category": category, "count": count, "start": start})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_kline(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # Intraday                                                              #
+    # ------------------------------------------------------------------ #
+
+    def get_minute(self, symbol: str) -> list[MinuteBar]:
+        """Get today's intraday minute-by-minute data.
+
+        Args:
+            symbol: A-share symbol, e.g. ``"600519.SH"``
+
+        Returns:
+            List of :class:`MinuteBar` objects.
+        """
+        market, code = self._market_code(symbol)
+        data = self._get("/minute", {"market": market, "code": code})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_minute(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # Fund flow                                                             #
+    # ------------------------------------------------------------------ #
+
+    def get_fund_flow(self, symbol: str) -> FundFlow:
+        """Get main-force fund flow for an A-share stock.
+
+        Args:
+            symbol: e.g. ``"600519.SH"``
+
+        Returns:
+            :class:`FundFlow` object.
+        """
+        market, code = self._market_code(symbol)
+        data = self._get("/fund-flow", {"market": market, "code": code})
+        raw: dict[str, Any] = data[0] if isinstance(data, list) and data else (data or {})
+        from ._parse import _float
+        return FundFlow(
+            symbol=symbol,
+            inflow_main=_float(raw.get("inflow_main") or raw.get("main_inflow") or 0),
+            inflow_retail=_float(raw.get("inflow_retail") or raw.get("retail_inflow") or 0),
+            outflow_main=_float(raw.get("outflow_main") or raw.get("main_outflow") or 0),
+            outflow_retail=_float(raw.get("outflow_retail") or raw.get("retail_outflow") or 0),
+            net_main=_float(raw.get("net_main") or raw.get("main_net") or 0),
+            net_retail=_float(raw.get("net_retail") or raw.get("retail_net") or 0),
+            _raw=raw,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Fundamental — global (all markets)                                   #
+    # ------------------------------------------------------------------ #
+
+    def get_company(self, symbol: str) -> Company:
+        """Get company overview.
+
+        Supports all markets: A-share, HK, US, etc.
+
+        Args:
+            symbol: e.g. ``"600519.SH"``, ``"TSLA.US"``, ``"00700.HK"``
+
+        Returns:
+            :class:`Company` object.
+        """
+        data = self._get("/fundamental/company", {"symbol": symbol})
+        raw: dict[str, Any] = data if isinstance(data, dict) else {}
+        return parse_company(raw, symbol)
+
+    def get_executives(self, symbol: str) -> list[Executive]:
+        """Get executive/management information.
+
+        Args:
+            symbol: e.g. ``"600519.SH"``, ``"TSLA.US"``
+
+        Returns:
+            List of :class:`Executive` objects.
+        """
+        data = self._get("/fundamental/executive", {"symbol": symbol})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_executive(r) for r in rows]
+
+    def get_financial_reports(
+        self,
+        symbol: str,
+        kind: str = "ALL",
+    ) -> list[FinancialReport]:
+        """Get financial reports (income statement, balance sheet, cash flow).
+
+        Args:
+            symbol: e.g. ``"600519.SH"``, ``"TSLA.US"``
+            kind: ``"ALL"`` / ``"ANNUAL"`` / ``"QUARTERLY"``
+
+        Returns:
+            List of :class:`FinancialReport` objects.
+        """
+        data = self._get("/fundamental/financial-reports", {"symbol": symbol, "kind": kind})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_financial_report(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # XDXR / Finance (A-share)                                             #
+    # ------------------------------------------------------------------ #
+
+    def get_xdxr(self, symbol: str) -> list[dict]:
+        """除权除息记录。symbol: '600519.SH'"""
+        market, code = self._sym(symbol)
+        return self._get("/xdxr", {"market": market, "code": code}) or []
+
+    def get_finance(self, symbol: str) -> dict:
+        """A股财务指标（PE/PB/EPS 等）。"""
+        market, code = self._sym(symbol)
+        return self._get("/finance", {"market": market, "code": code}) or {}
+
+    # ------------------------------------------------------------------ #
+    # Transactions                                                          #
+    # ------------------------------------------------------------------ #
+
+    def get_transactions(self, symbol: str, start: int = 0, count: int = 200) -> list[dict]:
+        """逐笔成交明细。"""
+        market, code = self._sym(symbol)
+        return self._get("/transaction", {"market": market, "code": code, "start": start, "count": count}) or []
+
+    def get_transaction_history(self, symbol: str, date: str, start: int = 0, count: int = 200) -> list[dict]:
+        """历史逐笔成交。date: '20260617'"""
+        market, code = self._sym(symbol)
+        return self._get("/transaction/history", {"market": market, "code": code, "date": date, "start": start, "count": count}) or []
+
+    # ------------------------------------------------------------------ #
+    # Fund flow history                                                     #
+    # ------------------------------------------------------------------ #
+
+    def get_fund_flow_history(self, symbol: str, start: int = 0, count: int = 10) -> list[dict]:
+        """历史资金流向。"""
+        market, code = self._sym(symbol)
+        return self._get("/fund-flow/history", {"market": market, "code": code, "start": start, "count": count}) or []
+
+    # ------------------------------------------------------------------ #
+    # Minute history                                                        #
+    # ------------------------------------------------------------------ #
+
+    def get_minute_history(self, symbol: str, date: str) -> list[MinuteBar]:
+        """历史某日分时数据。date: '20260617'"""
+        market, code = self._sym(symbol)
+        data = self._get("/minute/history", {"market": market, "code": code, "date": date})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_minute(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # Index K-lines                                                         #
+    # ------------------------------------------------------------------ #
+
+    def get_index_klines(self, symbol: str, period: str = "daily", count: int = 200, start: int | None = None) -> list[KLine]:
+        """指数 K 线（上证指数等）。"""
+        _period_map = {
+            "1m": "MIN_1", "5m": "MIN_5", "15m": "MIN_15",
+            "30m": "MIN_30", "60m": "MIN_60",
+            "daily": "DAY", "day": "DAY",
+            "weekly": "WEEK", "week": "WEEK",
+            "monthly": "MONTH", "month": "MONTH",
+        }
+        category = _period_map.get(period.lower(), period.upper())
+        market, code = self._sym(symbol)
+        data = self._get("/bars/index", {"market": market, "code": code, "category": category, "count": count, "start": start})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_kline(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # Market                                                                #
+    # ------------------------------------------------------------------ #
+
+    def get_market_stat(self) -> dict:
+        """市场统计（涨跌家数、成交额等）。"""
+        return self._get("/market/stat") or {}
+
+    def get_security_list(self, market: str, start: int = 0) -> list[dict]:
+        """获取市场证券列表。market: 'SH'/'SZ'/'BJ'"""
+        return self._get("/security/list", {"market": market, "start": start}) or []
+
+    def get_security_count(self, market: str) -> int:
+        """获取市场证券总数。"""
+        data = self._get("/security/count", {"market": market})
+        if isinstance(data, dict):
+            return int(data.get("count", 0))
+        return int(data or 0)
+
+    # ------------------------------------------------------------------ #
+    # Announcements                                                         #
+    # ------------------------------------------------------------------ #
+
+    def get_announcements(self, code: str, count: int = 20, page: int = 1) -> list[dict]:
+        """公司公告列表。code: '600519'（不含市场前缀）"""
+        return self._get("/announcements", {"code": code, "count": count, "page": page}) or []
+
+    # ------------------------------------------------------------------ #
+    # Sectors / Boards                                                      #
+    # ------------------------------------------------------------------ #
+
+    def get_sectors(self, block_file: str = "block_gn.dat") -> list[dict]:
+        """板块数据。block_file: 'block_zs.dat'(行业指数) / 'block_gn.dat'(概念) / 'block_fg.dat'(风格)"""
+        return self._get("/block", {"filename": block_file}) or []
+
+    def get_board_ranking(self, board_type: str = "industry", top_n: int = 20, sort_by: str = "change_pct", ascending: bool = False) -> list[dict]:
+        """板块涨跌排行。board_type: 'industry'/'concept'/'style'"""
+        return self._get("/board-mac/ranking", {"board_type": board_type, "top_n": top_n, "sort_by": sort_by, "ascending": ascending}) or []
+
+    def get_board_members(self, board_symbol: str, count: int = 50) -> list[dict]:
+        """板块成员列表。board_symbol: 板块代码"""
+        return self._get("/board-mac/members", {"board_symbol": board_symbol, "count": count}) or []
+
+    # ------------------------------------------------------------------ #
+    # Mac protocol — snapshots / depths                                    #
+    # ------------------------------------------------------------------ #
+
+    def get_snapshots(self, symbols: list[dict]) -> list[dict]:
+        """批量行情快照（mac 协议）。symbols: [{'market':'SH','code':'600519'}, ...]"""
+        return self._post("/mac/snapshots", {"stocks": symbols}) or []
+
+    def get_depths(self, symbols: list[dict]) -> list[dict]:
+        """批量五档盘口（mac 协议）。symbols: [{'market':'SH','code':'600519'}, ...]"""
+        return self._post("/mac/depths", {"stocks": symbols}) or []
+
+    # ------------------------------------------------------------------ #
+    # Global (ex-market) quotes / K-lines                                  #
+    # ------------------------------------------------------------------ #
+
+    def get_global_quote(self, market: str, code: str) -> dict:
+        """境外行情（美股/港股/期货等）。market: 'NASDAQ'/'NYSE'/'HKEX' 等"""
+        return self._get("/ex/mac/quote", {"market": market, "code": code}) or {}
+
+    def get_global_klines(self, market: str, code: str, period: str = "daily", count: int = 200, adjust: str | None = None) -> list[KLine]:
+        """境外行情 K 线。adjust: 'qfq'(前复权)/'hfq'(后复权)/None"""
+        _period_map = {
+            "1m": "MIN_1", "5m": "MIN_5", "15m": "MIN_15",
+            "30m": "MIN_30", "60m": "MIN_60",
+            "daily": "DAY", "day": "DAY",
+            "weekly": "WEEK", "week": "WEEK",
+            "monthly": "MONTH", "month": "MONTH",
+        }
+        category = _period_map.get(period.lower(), period.upper())
+        data = self._get("/ex/mac/bars", {"market": market, "code": code, "category": category, "count": count, "adjust": adjust})
+        rows: list[Any] = data if isinstance(data, list) else (data or [])
+        return [parse_kline(r) for r in rows]
+
+    # ------------------------------------------------------------------ #
+    # WebSocket streaming                                                   #
+    # ------------------------------------------------------------------ #
+
+    def stream(self) -> RealtimeStream:
+        """Open a real-time WebSocket stream.
+
+        Requires: ``pip install "easyquote[stream]"``
+
+        Supports A-share, HK, and US symbols simultaneously.
+
+        Example::
+
+            with client.stream() as ws:
+                ws.subscribe(["600519.SH", "00700.HK", "TSLA.US"])
+                for event in ws:
+                    if event["op"] == "quotes":
+                        for q in event["data"]:
+                            print(q["symbol"], q["last_price"])
+
+        Returns:
+            :class:`~easyquote._ws.RealtimeStream` context manager.
+        """
+        ws_url = (
+            self._base_url
+            .replace("https://", "wss://")
+            .replace("http://", "ws://")
+        )
+        url = f"{ws_url}/api/v1/ws/stream?api_key={self._api_key}"
+        return RealtimeStream(url)
+
+    def stream_async(self) -> Any:
+        """Open an async real-time WebSocket stream.
+
+        Requires: ``pip install "easyquote[stream-async]"``
+
+        Example::
+
+            async with client.stream_async() as ws:
+                await ws.subscribe(["600519.SH", "TSLA.US"])
+                async for event in ws:
+                    print(event)
+        """
+        from ._ws import AsyncRealtimeStream
+        ws_url = (
+            self._base_url
+            .replace("https://", "wss://")
+            .replace("http://", "ws://")
+        )
+        url = f"{ws_url}/api/v1/ws/stream?api_key={self._api_key}"
+        return AsyncRealtimeStream(url)

easyquote/_exceptions.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+
+class EasyQuoteError(Exception):
+    """Base exception for all EasyQuote SDK errors."""
+
+
+class AuthError(EasyQuoteError):
+    """Invalid or missing API key."""
+
+
+class RateLimitError(EasyQuoteError):
+    """Daily request quota exceeded."""
+
+
+class NotFoundError(EasyQuoteError):
+    """Requested resource not found."""
+
+
+class APIError(EasyQuoteError):
+    """Unexpected API error."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message

easyquote/_models.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Quote:
+    symbol: str
+    name: str
+    price: float
+    open: float
+    high: float
+    low: float
+    prev_close: float
+    change: float
+    change_pct: float
+    volume: int
+    amount: float
+    turnover_rate: float | None = None
+    timestamp: str | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __repr__(self) -> str:
+        sign = "+" if self.change >= 0 else ""
+        return f"<Quote {self.symbol} {self.name} {self.price} {sign}{self.change_pct:.2f}%>"
+
+
+@dataclass
+class KLine:
+    datetime: str
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: int
+    amount: float
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __repr__(self) -> str:
+        return f"<KLine {self.datetime} O={self.open} H={self.high} L={self.low} C={self.close}>"
+
+
+@dataclass
+class MinuteBar:
+    time: str
+    price: float
+    volume: int
+    amount: float
+    avg_price: float | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class FundFlow:
+    symbol: str
+    inflow_main: float
+    inflow_retail: float
+    outflow_main: float
+    outflow_retail: float
+    net_main: float
+    net_retail: float
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class Company:
+    symbol: str
+    name: str
+    exchange: str | None = None
+    industry: str | None = None
+    description: str | None = None
+    employees: int | None = None
+    website: str | None = None
+    founded: str | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __repr__(self) -> str:
+        return f"<Company {self.symbol} {self.name}>"
+
+
+@dataclass
+class Executive:
+    name: str
+    title: str
+    gender: str | None = None
+    age: int | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __repr__(self) -> str:
+        return f"<Executive {self.name} ({self.title})>"
+
+
+@dataclass
+class FinancialReport:
+    period: str
+    report_type: str
+    revenue: float | None = None
+    net_income: float | None = None
+    eps: float | None = None
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)

easyquote/_parse.py

@@ -0,0 +1,142 @@
+"""Symbol parsing and response mapping helpers."""
+from __future__ import annotations
+
+from typing import Any
+
+from ._models import (
+    Company,
+    Executive,
+    FinancialReport,
+    FundFlow,
+    KLine,
+    MinuteBar,
+    Quote,
+)
+
+_SUFFIX_TO_MARKET = {
+    "SH": "SH",
+    "SZ": "SZ",
+    "BJ": "BJ",
+}
+
+
+def split_symbol(symbol: str) -> tuple[str, str]:
+    """Split '600519.SH' → ('SH', '600519'). Pass-through for global symbols."""
+    if "." in symbol:
+        code, suffix = symbol.rsplit(".", 1)
+        suffix = suffix.upper()
+        if suffix in _SUFFIX_TO_MARKET:
+            return _SUFFIX_TO_MARKET[suffix], code
+    raise ValueError(
+        f"Cannot split symbol '{symbol}' into (market, code). "
+        "Use market= and code= parameters explicitly for A-share endpoints, "
+        "or use dot notation like '600519.SH'."
+    )
+
+
+def _float(v: Any) -> float:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _int(v: Any) -> int:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return 0
+
+
+def parse_quote(raw: dict[str, Any], symbol: str = "") -> Quote:
+    # Try common field names from the API
+    price = _float(raw.get("close") or raw.get("price") or raw.get("last_price") or 0)
+    prev = _float(raw.get("last_close") or raw.get("prev_close") or 0)
+    change = _float(raw.get("change") or (price - prev if prev else 0))
+    change_pct = _float(raw.get("change_pct") or raw.get("pct") or (change / prev * 100 if prev else 0))
+
+    market_map = {0: "SZ", 1: "SH"}
+    mkt = raw.get("market")
+    code = raw.get("code", "")
+    if isinstance(mkt, int):
+        sym = f"{code}.{market_map.get(mkt, str(mkt))}"
+    elif mkt:
+        sym = f"{code}.{mkt}"
+    else:
+        sym = symbol or code
+
+    return Quote(
+        symbol=sym,
+        name=raw.get("name") or raw.get("stock_name") or "",
+        price=price,
+        open=_float(raw.get("open") or 0),
+        high=_float(raw.get("high") or 0),
+        low=_float(raw.get("low") or 0),
+        prev_close=prev,
+        change=change,
+        change_pct=change_pct,
+        volume=_int(raw.get("vol") or raw.get("volume") or 0),
+        amount=_float(raw.get("amount") or 0),
+        turnover_rate=_float(raw.get("turnover_rate") or 0) or None,
+        timestamp=raw.get("timestamp") or raw.get("time"),
+        _raw=raw,
+    )
+
+
+def parse_kline(raw: dict[str, Any]) -> KLine:
+    return KLine(
+        datetime=str(raw.get("datetime") or raw.get("date") or raw.get("time") or ""),
+        open=_float(raw.get("open") or 0),
+        high=_float(raw.get("high") or 0),
+        low=_float(raw.get("low") or 0),
+        close=_float(raw.get("close") or 0),
+        volume=_int(raw.get("vol") or raw.get("volume") or 0),
+        amount=_float(raw.get("amount") or 0),
+        _raw=raw,
+    )
+
+
+def parse_minute(raw: dict[str, Any]) -> MinuteBar:
+    return MinuteBar(
+        time=str(raw.get("time") or raw.get("datetime") or ""),
+        price=_float(raw.get("price") or raw.get("close") or 0),
+        volume=_int(raw.get("vol") or raw.get("volume") or 0),
+        amount=_float(raw.get("amount") or 0),
+        avg_price=_float(raw.get("avg_price") or 0) or None,
+        _raw=raw,
+    )
+
+
+def parse_company(raw: dict[str, Any], symbol: str = "") -> Company:
+    return Company(
+        symbol=raw.get("symbol") or symbol,
+        name=raw.get("name") or raw.get("company_name") or "",
+        exchange=raw.get("exchange"),
+        industry=raw.get("industry") or raw.get("industry_name"),
+        description=raw.get("description") or raw.get("profile"),
+        employees=_int(raw.get("employees") or 0) or None,
+        website=raw.get("website"),
+        founded=raw.get("founded") or raw.get("listing_date"),
+        _raw=raw,
+    )
+
+
+def parse_executive(raw: dict[str, Any]) -> Executive:
+    return Executive(
+        name=raw.get("name") or "",
+        title=raw.get("title") or raw.get("position") or "",
+        gender=raw.get("gender"),
+        age=_int(raw.get("age") or 0) or None,
+        _raw=raw,
+    )
+
+
+def parse_financial_report(raw: dict[str, Any]) -> FinancialReport:
+    return FinancialReport(
+        period=raw.get("period") or raw.get("report_date") or "",
+        report_type=raw.get("report_type") or raw.get("kind") or "",
+        revenue=_float(raw.get("revenue") or 0) or None,
+        net_income=_float(raw.get("net_income") or raw.get("net_profit") or 0) or None,
+        eps=_float(raw.get("eps") or 0) or None,
+        _raw=raw,
+    )

easyquote/_ws.py

@@ -0,0 +1,155 @@
+"""WebSocket streaming client for real-time market data."""
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any, Callable, Iterator
+
+
+class RealtimeStream:
+    """Synchronous WebSocket stream. Use as a context manager.
+
+    Example::
+
+        with client.stream() as ws:
+            ws.subscribe(["600519.SH", "TSLA.US"])
+            for event in ws:
+                if event["op"] == "quotes":
+                    for q in event["data"]:
+                        print(q["symbol"], q["last_price"])
+    """
+
+    def __init__(self, url: str) -> None:
+        self._url = url
+        self._ws: Any = None
+        self._queue: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._event = threading.Event()
+        self._closed = False
+        self._error: Exception | None = None
+
+    def _connect(self) -> None:
+        try:
+            import websocket  # type: ignore[import]
+        except ImportError as exc:
+            raise ImportError(
+                "websocket-client is required for streaming: pip install websocket-client"
+            ) from exc
+
+        def _on_message(ws: Any, msg: str) -> None:
+            try:
+                data = json.loads(msg)
+            except json.JSONDecodeError:
+                return
+            with self._lock:
+                self._queue.append(data)
+            self._event.set()
+
+        def _on_error(ws: Any, err: Exception) -> None:
+            self._error = err
+            self._event.set()
+
+        def _on_close(ws: Any, code: int, reason: str) -> None:
+            self._closed = True
+            self._event.set()
+
+        self._ws = websocket.WebSocketApp(
+            self._url,
+            on_message=_on_message,
+            on_error=_on_error,
+            on_close=_on_close,
+        )
+        t = threading.Thread(target=self._ws.run_forever, daemon=True)
+        t.start()
+
+    def subscribe(self, symbols: list[str]) -> None:
+        """Subscribe to real-time quotes and depth for the given symbols."""
+        self._send({"op": "subscribe", "symbols": symbols})
+
+    def unsubscribe(self, symbols: list[str]) -> None:
+        self._send({"op": "unsubscribe", "symbols": symbols})
+
+    def status(self) -> None:
+        """Request current subscription status."""
+        self._send({"op": "status"})
+
+    def _send(self, msg: dict[str, Any]) -> None:
+        if self._ws is None:
+            raise RuntimeError("Stream not connected. Use as a context manager.")
+        self._ws.send(json.dumps(msg))
+
+    def __enter__(self) -> "RealtimeStream":
+        self._connect()
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._closed = True
+        if self._ws:
+            self._ws.close()
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        while not self._closed:
+            self._event.wait(timeout=1.0)
+            self._event.clear()
+            if self._error:
+                raise self._error
+            with self._lock:
+                items, self._queue = self._queue[:], []
+            yield from items
+
+
+class AsyncRealtimeStream:
+    """Async WebSocket stream.
+
+    Example::
+
+        async with client.stream_async() as ws:
+            await ws.subscribe(["600519.SH", "TSLA.US"])
+            async for event in ws:
+                print(event)
+    """
+
+    def __init__(self, url: str) -> None:
+        self._url = url
+        self._ws: Any = None
+
+    async def _connect(self) -> None:
+        try:
+            import websockets  # type: ignore[import]
+        except ImportError as exc:
+            raise ImportError(
+                "websockets is required for async streaming: pip install websockets"
+            ) from exc
+        self._ws = await websockets.connect(self._url)
+
+    async def subscribe(self, symbols: list[str]) -> None:
+        await self._send({"op": "subscribe", "symbols": symbols})
+
+    async def unsubscribe(self, symbols: list[str]) -> None:
+        await self._send({"op": "unsubscribe", "symbols": symbols})
+
+    async def status(self) -> None:
+        await self._send({"op": "status"})
+
+    async def _send(self, msg: dict[str, Any]) -> None:
+        await self._ws.send(json.dumps(msg))
+
+    async def __aenter__(self) -> "AsyncRealtimeStream":
+        await self._connect()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self._ws.close()
+
+    def __aiter__(self) -> "AsyncRealtimeStream":
+        return self
+
+    async def __anext__(self) -> dict[str, Any]:
+        try:
+            msg = await self._ws.recv()
+            return json.loads(msg)  # type: ignore[no-any-return]
+        except Exception as exc:
+            raise StopAsyncIteration from exc

easyquotes-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: easyquotes
+Version: 0.1.0
+Summary: EasyQuote Python SDK — global market data (A-share, HK, US) in a few lines of code
+Project-URL: Homepage, https://easyquote.io
+Project-URL: Documentation, https://easyquote.io/docs
+Project-URL: Repository, https://github.com/easyquotes/easyquotes
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Provides-Extra: stream
+Requires-Dist: websocket-client>=1.6; extra == 'stream'
+Provides-Extra: stream-async
+Requires-Dist: websockets>=12.0; extra == 'stream-async'
+Description-Content-Type: text/markdown
+
+# EasyQuote Python SDK
+
+A股、港股、美股及境外市场行情数据 Python 客户端。基于 EasyQuote HTTP API，支持实时行情、历史 K 线、逐笔成交、资金流向、基本面数据、板块数据及 WebSocket 推送。
+
+## 安装
+
+```bash
+pip install easyquotes
+```
+
+可选扩展：
+
+```bash
+pip install "easyquotes[stream]"        # WebSocket 同步推送
+pip install "easyquotes[stream-async]"  # WebSocket 异步推送
+```
+
+Python 版本要求：>= 3.10
+
+## 快速开始
+
+通过环境变量配置 API Key：
+
+```bash
+export EASYQUOTE_API_KEY="eq_your_key_here"
+```
+
+```python
+from easyquote import EasyQuoteClient
+
+client = EasyQuoteClient()  # 自动读取 EASYQUOTE_API_KEY
+quote = client.get_quote("600519.SH")
+print(f"{quote.name}: {quote.price} ({quote.change_pct:+.2f}%)")
+```
+
+也可以直接传入 api_key：
+
+```python
+client = EasyQuoteClient(api_key="eq_your_key_here")
+```
+
+## 标的代码格式
+
+| 市场     | 格式示例         | 说明                     |
+|----------|------------------|--------------------------|
+| A 股上交 | `600519.SH`      | 沪市，后缀 `.SH`         |
+| A 股深交 | `000001.SZ`      | 深市，后缀 `.SZ`         |
+| A 股北交 | `836239.BJ`      | 北交所，后缀 `.BJ`       |
+| 港股     | `00700.HK`       | 五位数代码，后缀 `.HK`   |
+| 美股     | `TSLA.US`        | 股票代码，后缀 `.US`     |
+| 指数     | `000001.SH`      | 上证指数等               |
+
+## API 参考
+
+### 行情 (Quotes)
+
+| 方法 | 说明 |
+|------|------|
+| `get_quote(symbol)` | 单只标的实时行情，返回 `Quote` |
+| `get_quotes(symbols)` | 批量实时行情，返回 `list[Quote]` |
+| `get_snapshots(symbols)` | 批量行情快照（mac 协议），`symbols` 为 `[{'market':'SH','code':'600519'}]` |
+| `get_depths(symbols)` | 批量五档盘口（mac 协议） |
+
+### K 线 (K-Lines)
+
+| 方法 | 说明 |
+|------|------|
+| `get_klines(symbol, period, count, start)` | A 股/港股/美股历史 K 线，返回 `list[KLine]` |
+| `get_index_klines(symbol, period, count, start)` | 指数 K 线 |
+| `get_global_klines(market, code, period, count, adjust)` | 境外行情 K 线，`adjust='qfq'`（前复权）/`'hfq'`（后复权） |
+
+`period` 可选值：`"1m"` / `"5m"` / `"15m"` / `"30m"` / `"60m"` / `"daily"` / `"weekly"` / `"monthly"`
+
+### 分时 (Intraday)
+
+| 方法 | 说明 |
+|------|------|
+| `get_minute(symbol)` | 当日分时数据，返回 `list[MinuteBar]` |
+| `get_minute_history(symbol, date)` | 历史某日分时数据，`date='20260617'` |
+
+### 逐笔 (Transactions)
+
+| 方法 | 说明 |
+|------|------|
+| `get_transactions(symbol, start, count)` | 今日逐笔成交明细 |
+| `get_transaction_history(symbol, date, start, count)` | 历史逐笔成交，`date='20260617'` |
+
+### 资金流向 (Fund Flow)
+
+| 方法 | 说明 |
+|------|------|
+| `get_fund_flow(symbol)` | 当日主力资金流向，返回 `FundFlow` |
+| `get_fund_flow_history(symbol, start, count)` | 历史资金流向列表 |
+
+### 基本面 A 股 (A-share Fundamentals)
+
+| 方法 | 说明 |
+|------|------|
+| `get_finance(symbol)` | A 股财务指标（PE/PB/EPS 等） |
+| `get_xdxr(symbol)` | 除权除息记录 |
+| `get_announcements(code, count, page)` | 公司公告列表，`code='600519'`（不含市场后缀） |
+
+### 基本面 全球 (Global Fundamentals)
+
+| 方法 | 说明 |
+|------|------|
+| `get_company(symbol)` | 公司概况，返回 `Company`，支持 A 股/港股/美股 |
+| `get_executives(symbol)` | 高管信息，返回 `list[Executive]` |
+| `get_financial_reports(symbol, kind)` | 财务报告，`kind='ALL'/'ANNUAL'/'QUARTERLY'` |
+
+### 板块 (Sectors)
+
+| 方法 | 说明 |
+|------|------|
+| `get_sectors(block_file)` | 板块数据，`block_file` 可选 `'block_zs.dat'`（行业指数）/ `'block_gn.dat'`（概念）/ `'block_fg.dat'`（风格） |
+| `get_board_ranking(board_type, top_n, sort_by, ascending)` | 板块涨跌排行，`board_type='industry'/'concept'/'style'` |
+| `get_board_members(board_symbol, count)` | 板块成员列表 |
+
+### 市场 (Market)
+
+| 方法 | 说明 |
+|------|------|
+| `get_market_stat()` | 市场统计（涨跌家数、成交额等） |
+| `get_security_list(market, start)` | 证券列表，`market='SH'/'SZ'/'BJ'` |
+| `get_security_count(market)` | 证券总数，返回 `int` |
+
+### 境外行情 (Global Quotes)
+
+| 方法 | 说明 |
+|------|------|
+| `get_global_quote(market, code)` | 境外单只行情，`market='NASDAQ'/'NYSE'/'HKEX'` 等 |
+| `get_global_klines(market, code, period, count, adjust)` | 境外 K 线 |
+
+### 实时推送 (Streaming)
+
+| 方法 | 说明 |
+|------|------|
+| `stream()` | 同步 WebSocket 推送，需安装 `easyquotes[stream]` |
+| `stream_async()` | 异步 WebSocket 推送，需安装 `easyquotes[stream-async]` |
+
+## 使用示例
+
+### 批量获取行情
+
+```python
+quotes = client.get_quotes(["600519.SH", "000001.SZ", "TSLA.US", "00700.HK"])
+for q in quotes:
+    print(f"{q.symbol}  {q.price:>10.2f}  {q.change_pct:+.2f}%")
+```
+
+### K 线数据
+
+```python
+klines = client.get_klines("600519.SH", period="daily", count=120)
+for k in klines[-5:]:
+    print(f"{k.datetime}  O:{k.open}  H:{k.high}  L:{k.low}  C:{k.close}  V:{k.volume}")
+```
+
+### 历史分时
+
+```python
+bars = client.get_minute_history("600519.SH", date="20260617")
+for b in bars[:10]:
+    print(b.time, b.price, b.volume)
+```
+
+### 资金流向
+
+```python
+ff = client.get_fund_flow("600519.SH")
+print(f"主力净流入: {ff.net_main / 1e8:.2f} 亿")
+```
+
+### 板块排行
+
+```python
+ranking = client.get_board_ranking(board_type="industry", top_n=10, sort_by="change_pct")
+for b in ranking:
+    print(b["name"], b["change_pct"])
+```
+
+### 同步 WebSocket 推送
+
+```python
+with client.stream() as ws:
+    ws.subscribe(["600519.SH", "000001.SZ", "TSLA.US"])
+    for event in ws:
+        if event["op"] == "quotes":
+            for q in event["data"]:
+                print(q["symbol"], q["last_price"])
+```
+
+### 异步 WebSocket 推送
+
+```python
+import asyncio
+
+async def main():
+    async with client.stream_async() as ws:
+        await ws.subscribe(["600519.SH", "TSLA.US"])
+        async for event in ws:
+            print(event)
+
+asyncio.run(main())
+```
+
+### 逐笔成交
+
+```python
+ticks = client.get_transactions("600519.SH", start=0, count=50)
+for t in ticks:
+    print(t["time"], t["price"], t["volume"], t["direction"])
+```
+
+### 境外行情
+
+```python
+# 获取纳斯达克个股 K 线
+klines = client.get_global_klines("NASDAQ", "TSLA", period="daily", count=60)
+
+# 获取港股行情
+quote = client.get_global_quote("HKEX", "00700")
+```
+
+## 错误处理
+
+```python
+from easyquote import EasyQuoteClient
+from easyquote import AuthError, RateLimitError, APIError, NotFoundError
+
+client = EasyQuoteClient(api_key="eq_your_key")
+
+try:
+    quote = client.get_quote("600519.SH")
+except AuthError:
+    print("API Key 无效或未设置")
+except RateLimitError:
+    print("请求频率超限，请稍后重试")
+except NotFoundError:
+    print("标的不存在")
+except APIError as e:
+    print(f"API 错误 {e.code}: {e.message}")
+```
+
+## 自托管部署
+
+如果使用自托管的 EasyQuote 后端（基于 easy-tdx 的 FastAPI 服务），可以通过 `base_url` 参数指定服务地址：
+
+```python
+client = EasyQuoteClient(
+    api_key="eq_your_key",
+    base_url="http://localhost:8000",
+)
+```
+
+HTTP 和 WebSocket 均会自动切换到指定地址（`wss://` 对应 HTTPS，`ws://` 对应 HTTP）。
+
+## 许可证
+
+MIT

easyquotes-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+easyquote/__init__.py,sha256=KPjGCAPhjhy5GUgqZwdBn0avoyPp9KTE1aYGa6ymozM,598
+easyquote/_client.py,sha256=7xSTFTeYL6NpfCPVgbaf6uPTeL7Zl2grIm63yiO7bfQ,20170
+easyquote/_exceptions.py,sha256=lIbgYoiBHcpyXnYAyL6BrP85LFxIjNn7iHROGBPoNrQ,597
+easyquote/_models.py,sha256=GpoHqMpJ61dzUvzj4kxRMjlJ6lUGbI7CBQUmOrokHXo,2331
+easyquote/_parse.py,sha256=ZwylAc9ky1XqTKkwWSN3ukrVkxJ1aocIxLHfVVZSyTY,4521
+easyquote/_ws.py,sha256=362cM84LRpCBSUhUoX1_Tix8pLs_coWsOsD2JwVc4ng,4754
+easyquotes-0.1.0.dist-info/METADATA,sha256=W1MLsyqh2FRE8WSvOkZ11ls_O6zFXoNpXsaPEvt6h6c,8447
+easyquotes-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+easyquotes-0.1.0.dist-info/licenses/LICENSE,sha256=H1fZkYpkk2PpCje142VjP2mHdQAt2oteOk2zlMBGw2M,1079
+easyquotes-0.1.0.dist-info/RECORD,,

easyquotes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

easyquotes-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EasyQuote contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.