ashare-data-lite 0.1.0__py3-none-any.whl

ashare_data/__init__.py

@@ -0,0 +1,163 @@
+"""轻量证券行情接口，返回可序列化的 dataclass 对象。"""
+
+from ._default import configure, get_client
+from .async_client import AsyncMarketClient
+from .client import MarketClient
+from typing import Sequence
+
+from .models import Bar, DateLike, FundNav, FundShares, Instrument, Observation, Quote
+from .stock import get_stock_quote, get_stock_quotes, get_stock_history
+from .index import get_index_quote, get_index_quotes, get_index_history
+from .etf import (
+    get_etf_quote,
+    get_etf_quotes,
+    get_etf_history,
+    get_fund_nav_history,
+    get_etf_catalog,
+    get_sse_etf_shares,
+)
+from .exceptions import (
+    MarketDataError,
+    InvalidCodeError,
+    ConfigurationError,
+    RequestError,
+    DataFormatError,
+    QuoteNotFoundError,
+    AllSourcesFailedError,
+)
+from .models import OrderLevel
+
+__version__ = "0.1.0"
+
+
+def get_quotes(codes: Sequence[str], *, instrument: Instrument = "auto") -> list[Quote]:
+    """批量获取实时行情，按首次出现的代码顺序返回 Quote；缺失项带 error。"""
+    return get_client().get_quotes(codes, instrument=instrument)
+
+
+def get_quote(code: str, *, instrument: Instrument = "auto") -> Quote:
+    """获取单只实时行情；缺失时抛出 QuoteNotFoundError。"""
+    return get_client().get_quote(code, instrument=instrument)
+
+
+def get_history(
+    code: str,
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    *,
+    instrument: Instrument = "auto",
+    sources: Sequence[str] | None = None,
+    adjust: str = "none",
+    scale: int = 240,
+    datalen: int = 5049,
+    max_pages: int = 100,
+) -> list[Bar]:
+    """获取升序 K 线；sources 按顺序降级，默认日线腾讯→新浪、分钟线新浪。"""
+    return get_client().get_history(
+        code,
+        start,
+        end,
+        instrument=instrument,
+        sources=sources,
+        adjust=adjust,
+        scale=scale,
+        datalen=datalen,
+        max_pages=max_pages,
+    )
+
+
+def get_fred_series(
+    series_id: str,
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    *,
+    api_key: str | None = None,
+) -> list[Observation]:
+    """获取升序 FRED 观测值；api_key 优先于客户端配置和环境变量。"""
+    return get_client().get_fred_series(series_id, start, end, api_key=api_key)
+
+
+def get_vix_history(
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    *,
+    api_key: str | None = None,
+) -> list[Observation]:
+    """获取 VIX 日度收盘序列 VIXCLS，返回 Observation 列表。"""
+    return get_client().get_vix_history(start, end, api_key=api_key)
+
+
+def get_twelve_bars(
+    symbol: str,
+    *,
+    interval: str = "1day",
+    outputsize: int = 5000,
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    adjust: str = "all",
+    api_key: str | None = None,
+) -> list[Bar]:
+    """获取一页升序海外 K 线，outputsize 为 1～5000，时间使用 UTC。"""
+    return get_client().get_twelve_bars(
+        symbol,
+        interval=interval,
+        outputsize=outputsize,
+        start=start,
+        end=end,
+        adjust=adjust,
+        api_key=api_key,
+    )
+
+
+def get_twelve_daily_history(
+    symbol: str,
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    *,
+    adjust: str = "all",
+    api_key: str | None = None,
+    max_pages: int = 100,
+) -> list[Bar]:
+    """分页获取指定日期区间的升序海外日线，返回 Bar 列表。"""
+    return get_client().get_twelve_daily_history(
+        symbol, start, end, adjust=adjust, api_key=api_key, max_pages=max_pages
+    )
+
+
+__all__ = [
+    "get_quote",
+    "get_quotes",
+    "get_history",
+    "get_fund_nav_history",
+    "get_etf_catalog",
+    "get_sse_etf_shares",
+    "get_fred_series",
+    "get_vix_history",
+    "get_twelve_bars",
+    "get_twelve_daily_history",
+    "get_stock_quote",
+    "get_stock_quotes",
+    "get_stock_history",
+    "get_etf_quote",
+    "get_etf_quotes",
+    "get_etf_history",
+    "get_index_quote",
+    "get_index_quotes",
+    "get_index_history",
+    "configure",
+    "MarketClient",
+    "AsyncMarketClient",
+    "MarketDataError",
+    "InvalidCodeError",
+    "ConfigurationError",
+    "RequestError",
+    "DataFormatError",
+    "QuoteNotFoundError",
+    "AllSourcesFailedError",
+    "Quote",
+    "OrderLevel",
+    "Bar",
+    "FundNav",
+    "FundShares",
+    "Observation",
+]

ashare_data/_convert.py

@@ -0,0 +1,152 @@
+"""将来源数据转换为统一的公开类型与计量单位。"""
+
+from datetime import date, datetime, timedelta, timezone
+
+from .exceptions import DataFormatError
+from .models import Bar, FundNav, FundShares, Observation, OrderLevel, Quote
+
+CHINA_TZ = timezone(timedelta(hours=8))
+
+
+def scaled(value, factor):
+    return value * factor if value is not None else None
+
+
+def quote_model(row, instrument="auto"):
+    kind = row.get("instrument_type", instrument)
+    extension = row.get("etf", row.get("stock", {}))
+    time = row.get("quote_time")
+    book = row.get("order_book", {})
+
+    def levels(side):
+        return tuple(
+            OrderLevel(level["price"], scaled(level["volume_lot"], 100))
+            for level in book.get(side, [])
+        )
+
+    premium = extension.get("premium_rate")
+    if premium is None:
+        premium = extension.get("premium_rate_calculated")
+    average = row.get("average_price")
+    if average is None:
+        average = row.get("average_price_calculated")
+    return Quote(
+        symbol=row["symbol"],
+        code=row.get("code", row["symbol"][2:]),
+        instrument=kind,
+        source=row["source"],
+        name=row.get("name"),
+        timestamp=datetime.fromisoformat(time).replace(tzinfo=CHINA_TZ)
+        if time
+        else None,
+        currency=row.get("currency"),
+        **{
+            key: row.get(key)
+            for key in (
+                "last",
+                "prev_close",
+                "open",
+                "high",
+                "low",
+                "change",
+                "change_pct",
+                "pb",
+                "limit_up",
+                "limit_down",
+                "volume_ratio",
+            )
+        },
+        pe=extension.get("pe"),
+        volume=scaled(row.get("volume_lot"), 100),
+        amount=row.get("amount_yuan"),
+        outer_volume=scaled(row.get("outer_volume_lot"), 100),
+        inner_volume=scaled(row.get("inner_volume_lot"), 100),
+        turnover_rate_pct=row.get("turnover_rate"),
+        amplitude_pct=row.get("amplitude"),
+        market_cap=scaled(row.get("total_market_cap_100m"), 100000000),
+        circulating_market_cap=scaled(
+            row.get("circulating_market_cap_100m"), 100000000
+        ),
+        order_imbalance=scaled(row.get("order_imbalance_calculated"), 100),
+        average_price=average,
+        is_suspended=row.get("is_suspended", False),
+        bids=levels("bids"),
+        asks=levels("asks"),
+        iopv=extension.get("iopv"),
+        premium_rate_pct=premium,
+        circulating_shares=extension.get(
+            "circulating_units", extension.get("circulating_shares")
+        ),
+        total_shares=extension.get("total_units", extension.get("total_shares")),
+        error=row.get("error"),
+    )
+
+
+def bar_models(rows, symbol, interval):
+    result = []
+    for row in rows:
+        try:
+            moment = datetime.fromisoformat(row["datetime"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise DataFormatError("K 线时间字段异常") from exc
+        if row.get("close") is None:
+            raise DataFormatError("K 线收盘价字段异常")
+        overseas = row["source"] == "twelvedata"
+        if moment.tzinfo is None:
+            moment = moment.replace(tzinfo=timezone.utc if overseas else CHINA_TZ)
+        volume = row.get("volume")
+        if row.get("volume_unit") == "lot":
+            volume = scaled(volume, 100)
+        result.append(
+            Bar(
+                symbol=symbol,
+                timestamp=moment,
+                interval=interval,
+                source=row["source"],
+                adjust=row.get("adjust") or "none",
+                open=row.get("open"),
+                high=row.get("high"),
+                low=row.get("low"),
+                close=row.get("close"),
+                volume=volume,
+                volume_unit="provider" if overseas else "share",
+                currency=row.get("meta", {}).get("currency") if overseas else "CNY",
+            )
+        )
+    return result
+
+
+def nav_models(rows):
+    return [
+        FundNav(
+            row["code"],
+            date.fromisoformat(row["valuation_date"]),
+            row["nav"],
+            row["source"],
+        )
+        for row in rows
+    ]
+
+
+def shares_models(rows):
+    return [
+        FundShares(
+            row["code"],
+            date.fromisoformat(row["date"][:10]),
+            row["shares"],
+            row["source"],
+        )
+        for row in rows
+    ]
+
+
+def observation_models(rows):
+    return [
+        Observation(
+            row["series_id"],
+            date.fromisoformat(row["date"]),
+            row["value"],
+            row["source"],
+        )
+        for row in rows
+    ]

ashare_data/_default.py

@@ -0,0 +1,36 @@
+"""进程级默认客户端，连续调用复用净值限速与冷却状态。"""
+
+import threading
+
+from .client import MarketClient
+
+_client = None
+_lock = threading.Lock()
+
+
+def get_client():
+    global _client
+    with _lock:
+        if _client is None:
+            _client = MarketClient()
+        return _client
+
+
+def configure(
+    *,
+    timeout: float = 10,
+    retries: int = 1,
+    fred_api_key: str | None = None,
+    twelve_api_key: str | None = None,
+) -> MarketClient:
+    """设置全局请求超时、重试和账户密钥，返回新的默认客户端。"""
+    global _client
+    client = MarketClient(
+        timeout=timeout,
+        retries=retries,
+        fred_api_key=fred_api_key,
+        twelve_api_key=twelve_api_key,
+    )
+    with _lock:
+        _client = client
+    return client

ashare_data/_http.py

@@ -0,0 +1,86 @@
+"""使用 urllib 请求上游数据，异常消息仅显示主机和路径。"""
+
+import gzip
+import json
+import socket
+import time
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlsplit
+from urllib.request import Request, urlopen
+
+from .exceptions import ConfigurationError, DataFormatError, RequestError
+
+
+def retry_seconds(value):
+    if not value:
+        return 0
+    try:
+        return max(0, float(value))
+    except ValueError:
+        try:
+            return max(
+                0,
+                (
+                    parsedate_to_datetime(value) - datetime.now(timezone.utc)
+                ).total_seconds(),
+            )
+        except (TypeError, ValueError):
+            return 0
+
+
+class HttpClient:
+    def __init__(self, timeout=10, retries=1):
+        if timeout <= 0 or not isinstance(retries, int) or retries < 0:
+            raise ConfigurationError("timeout 应大于 0，retries 应为非负整数")
+        self.timeout = timeout
+        self.retries = retries
+
+    def get_bytes(self, url, *, params=None, headers=None, timeout=None):
+        query = urlencode(
+            {key: value for key, value in (params or {}).items() if value is not None}
+        )
+        request_url = url + ("&" if "?" in url else "?") + query if query else url
+        parts = urlsplit(url)
+        endpoint = parts.netloc + parts.path
+        request = Request(
+            request_url, headers={"User-Agent": "Mozilla/5.0", **(headers or {})}
+        )
+        for attempt in range(self.retries + 1):
+            try:
+                with urlopen(
+                    request, timeout=self.timeout if timeout is None else timeout
+                ) as response:
+                    data = response.read()
+                    return (
+                        gzip.decompress(data)
+                        if response.headers.get("Content-Encoding") == "gzip"
+                        else data
+                    )
+            except HTTPError as exc:
+                status = exc.code
+                delay = retry_seconds(exc.headers.get("Retry-After"))
+                exc.close()
+                error = RequestError(
+                    f"{endpoint} HTTP {status}", status_code=status, retry_after=delay
+                )
+                retryable = status in {502, 503, 504}
+            except (URLError, OSError, socket.timeout) as exc:
+                error = RequestError(f"{endpoint} 网络请求失败（{type(exc).__name__}）")
+                retryable = True
+            if attempt == self.retries or not retryable:
+                raise error from None
+            time.sleep(0.5 * 2**attempt)
+
+    def get_text(self, url, *, encoding="utf-8", **kwargs):
+        try:
+            return self.get_bytes(url, **kwargs).decode(encoding)
+        except UnicodeError as exc:
+            raise DataFormatError("响应文本编码异常") from exc
+
+    def get_json(self, url, **kwargs):
+        try:
+            return json.loads(self.get_text(url, **kwargs))
+        except (ValueError, TypeError) as exc:
+            raise DataFormatError("响应应为 JSON") from exc

ashare_data/_utils.py

@@ -0,0 +1,87 @@
+"""证券代码、日期及数值的共同约定。"""
+
+import math
+import re
+from collections.abc import Sequence
+from datetime import date, datetime, timedelta, timezone
+
+from .exceptions import ConfigurationError, InvalidCodeError
+
+
+def number(value):
+    try:
+        result = float(str(value).replace(",", ""))
+        return result if math.isfinite(result) else None
+    except (TypeError, ValueError):
+        return None
+
+
+def china_today():
+    return datetime.now(timezone(timedelta(hours=8))).date()
+
+
+def date_text(value):
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    try:
+        return date.fromisoformat(str(value)).isoformat()
+    except ValueError as exc:
+        raise ConfigurationError("日期使用 YYYY-MM-DD 或 date 对象") from exc
+
+
+def date_range(start=None, end=None):
+    start = date_text(start) if start is not None else "1970-01-01"
+    end = date_text(end) if end is not None else china_today().isoformat()
+    if start > end:
+        raise ConfigurationError("起始日期应早于或等于截止日期")
+    return start, end
+
+
+def normalize_symbol(code, instrument="auto"):
+    if instrument not in {"auto", "stock", "etf", "index"}:
+        raise ConfigurationError("instrument 使用 auto、stock、etf 或 index")
+    if not isinstance(code, str):
+        raise InvalidCodeError("证券代码使用字符串，以保留前导零")
+    value = code.strip().lower()
+    if re.fullmatch(r"(sh|sz)\d{6}", value):
+        return value
+    suffix = re.fullmatch(r"(\d{6})\.(sh|sz)", value)
+    if suffix:
+        return suffix[2] + suffix[1]
+    if not re.fullmatch(r"\d{6}", value):
+        raise InvalidCodeError(f"证券代码格式错误：{code!r}")
+    if instrument == "index":
+        if value.startswith("000"):
+            return "sh" + value
+        if value.startswith("399"):
+            return "sz" + value
+        raise InvalidCodeError("该指数请使用明确市场前缀，例如 sh000001")
+    return ("sh" if value.startswith(("5", "6", "9")) else "sz") + value
+
+
+def is_index(symbol):
+    return symbol.startswith(("sh000", "sz399"))
+
+
+def fund_code(code):
+    symbol = normalize_symbol(code, "etf")
+    return symbol[2:]
+
+
+def sorted_rows(rows, key="datetime"):
+    unique = {row[key]: row for row in rows}
+    return [unique[value] for value in sorted(unique)]
+
+
+def source_order(sources, default, allowed):
+    """验证并保留来源优先顺序。"""
+    values = default if sources is None else sources
+    if isinstance(values, str) or not isinstance(values, Sequence):
+        raise ConfigurationError("sources 使用按优先级排列的来源列表")
+    if not values or any(
+        not isinstance(value, str) or value not in allowed for value in values
+    ):
+        raise ConfigurationError("sources 可用来源：" + ", ".join(allowed))
+    return tuple(dict.fromkeys(values))