zzshare 0.1.2__py3-none-any.whl

zzshare/__init__.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+from typing import Any, Callable, Optional
+
+from zzshare.client import DataApi
+
+
+_default_api: Optional[DataApi] = None
+
+
+def pro_api(token: str = "", timeout: int = 10, http_url: str = "https://api.zizizaizai.com") -> DataApi:
+    return DataApi(token=token, timeout=timeout, http_url=http_url)
+
+
+def _get_default_api() -> DataApi:
+    global _default_api
+    if _default_api is None:
+        _default_api = DataApi()
+    return _default_api
+
+
+def daily(
+    ts_code: Optional[str] = None,
+    trade_date: Optional[str] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    offset: Optional[int] = None,
+    limit: Optional[int] = None,
+    fields: Optional[str] = None,
+    **kwargs: Any,
+):
+    return _get_default_api().daily(
+        ts_code=ts_code,
+        trade_date=trade_date,
+        start_date=start_date,
+        end_date=end_date,
+        offset=offset,
+        limit=limit,
+        fields=fields,
+        **kwargs,
+    )
+
+
+def stock_basic(
+    ts_code: Optional[str] = None,
+    exchange: Optional[str] = None,
+    list_status: str = "L",
+    is_hs: Optional[str] = None,
+    fields: Optional[str] = None,
+    name: Optional[str] = None,
+    **kwargs: Any,
+):
+    return _get_default_api().stock_basic(
+        ts_code=ts_code,
+        exchange=exchange,
+        list_status=list_status,
+        is_hs=is_hs,
+        fields=fields,
+        name=name,
+        **kwargs,
+    )
+
+
+def query(api_name: str, params: Optional[dict] = None):
+    return _get_default_api().query(api_name, params=params)
+
+
+def _create_shortcut_proxy(name: str) -> Callable[..., Any]:
+    def _proxy(*args: Any, **kwargs: Any) -> Any:
+        return getattr(_get_default_api(), name)(*args, **kwargs)
+
+    _proxy.__name__ = name
+    return _proxy
+
+
+for _shortcut_name in DataApi.SHORTCUTS:
+    if _shortcut_name in {"daily", "stock_basic"}:
+        continue
+    globals()[_shortcut_name] = _create_shortcut_proxy(_shortcut_name)
+
+
+__all__ = ["DataApi", "pro_api", "daily", "stock_basic", "query", *[name for name in DataApi.SHORTCUTS if name != "daily"]]

zzshare/client.py

@@ -0,0 +1,579 @@
+import requests
+from typing import Any, Optional, Dict, Callable, List, Union
+import pandas as pd
+
+from zzshare.core import BaseDataApi
+from zzshare.utils import kline_data_to_df
+
+
+class DataApi(BaseDataApi):
+    def __init__(self, token: str = '', timeout: int = 10, http_url: str = 'https://api.zizizaizai.com'):
+        super().__init__(token, timeout, http_url)
+
+    SHORTCUTS = {
+        # Daily
+        "uplimit_hot": (
+            "open/review/uplimit/hot",
+            ["date1", "board"],
+            None
+        ),
+        "uplimit_stocks": (
+            "open/review/uplimit/stocks/{date1}",
+            ["date1"],
+            None
+        ),
+        # Sentiment Data
+        "market_plate_stocks": (
+            "market/plates/17/{plate_code}/stocks/rank",
+            ["plate_code", "date1", "is_real", "limit"],
+            None
+        ),
+        "market_plate": (
+            "market/plates/17/rank",
+            ["date1", "limit"],
+            None
+        ),
+        "market_sentiment": (
+            "v2/api/sentiment/kline/day/0",
+            ["date1", "date2"],
+            None
+        ),
+        "market_hot_sentiment": (
+            "v2/api/sentiment/kline/day/20",
+            ["date1", "date2"],
+            None
+        ),
+        "market_style": (
+            "v2/api/timing/market/style",
+            ["date1"],
+            None
+        ),
+        "open_sentiment_data": (
+            "open/sentiment/data",
+            ["date1", "date2"],
+            None
+        ),
+        # Kline
+        "daily": (
+            "open/kline/d/{code}",
+            ["code", "date1", "date2"],
+            kline_data_to_df
+        ),
+        # Base Data
+        "trade_days": (
+            "market/trade/days",
+            ["day_start", "day_end", "days"],
+            None
+        ),
+        # Third Party
+        "ths_hot_top": (
+            "open/sentiment/media/ths2/top",
+            ["date1", "top_n"],
+            None
+        ),
+        "stock_ths_hot": (
+            "v2/api/sentiment/media/ths/symbol/{code}",
+            ["code", "date1"],
+            None
+        ),
+        "sentiment_market_hot_day": (
+            "v3/api/sentiment/market/hot/day",
+            ["date"],
+            None
+        ),
+        "sentiment_trend": (
+            "v3/api/sentiment/trend/{model}",
+            ["model", "date1"],
+            None
+        ),
+        "sentiment_trend_range": (
+            "v3/api/sentiment/trend/{model}/range",
+            ["model", "date1", "date2"],
+            None
+        ),
+        "review_uplimit_reason": (
+            "v3/api/review/uplimit/reason",
+            ["date1", "group", "page", "page_size"],
+            None
+        ),
+        "review_uplimit_hot_open": (
+            "v3/open/review/uplimit/hot",
+            ["date1", "date2", "board", "limit"],
+            None
+        ),
+        "stock_uplimit_reason": (
+            "v3/open/stock/uplimit/reason/{stock_code}",
+            ["stock_code", "date"],
+            None
+        ),
+        "stock_uplimit_reason_history": (
+            "v3/open/stock/uplimit/reason/history/{stock_code}", ["stock_code", "page", "pageSize"], None),
+        "review_uplimit_reason_open": (
+            "v3/open/review/uplimit/reason",
+            ["date1"],
+            None
+        ),
+        "stock_info": (
+            "v3/open/stock/info",
+            ["stock_id", "info_type"],
+            None
+        ),
+        # ================== 新增接口 ==================
+        # 龙虎榜数据
+        "lhb_list": (
+            "market/lhb/list",
+            ["date1"],
+            None
+        ),
+        "lhb_detail": (
+            "market/lhb/detail",
+            ["date1", "stock_code"],
+            None
+        ),
+        "lhb_stock_history": (
+            "market/lhb/stock/history",
+            ["stock_code", "trader_name"],
+            None
+        ),
+        "lhb_trader_history": (
+            "market/lhb/trader/history",
+            ["trader_name", "trader_id", "stock_code", "page", "per_page"],
+            None
+        ),
+        # 板块数据
+        "plates_list": (
+            "market/plates/{plate_type}",
+            ["plate_type"],
+            None
+        ),
+        "plates_rank": (
+            "market/plates/{plate_type}/rank",
+            ["plate_type", "date1", "limit"],
+            None
+        ),
+        "plates_trend": (
+            "market/plates/{plate_type}/trend",
+            ["plate_type", "plate_code", "day_start", "day_end"],
+            None
+        ),
+        "plates_stocks": (
+            "market/plates/{plate_type}/{plate_code}/stocks",
+            ["plate_type", "plate_code", "date"],
+            None
+        ),
+        # 涨跌分布与情绪
+        "updown_distribution": (
+            "open/sentiment/updown/disctribution",
+            ["date1"],
+            None
+        ),
+        "uplimit_trend": (
+            "open/sentiment/uplimit/trend",
+            ["date1"],
+            None
+        ),
+        "sentiment_hot_day": (
+            "open/sentiment/hot/day",
+            ["index", "st"],
+            None
+        ),
+        "sentiment_level": (
+            "open/sentiment/level",
+            ["date"],
+            None
+        ),
+        "sentiment_bull_data": (
+            "open/sentiment/bull/data",
+            ["date1", "date2"],
+            None
+        ),
+        # 行情实时数据
+        "market_real": (
+            "open/market/real",
+            ["symbols"],
+            None
+        ),
+        "stock_moneyflow": (
+            "open/stock/{stock_id}/moneyflow",
+            ["stock_id", "m_type"],
+            None
+        ),
+        "market_mf": (
+            "open/market/mf",
+            ["stock", "date", "wm", "default_v"],
+            None
+        ),
+        # 涨停市值统计
+        "uplimit_market_value": (
+            "v2/api/uplimit/market/value",
+            ["date1", "date2"],
+            None
+        ),
+        # 市场TopN情绪
+        "sentiment_market_top_n": (
+            "v2/api/sentiment/market/top/n",
+            ["modal_id", "date1", "date2"],
+            None
+        ),
+        # 异动数据
+        "movement_alerts": (
+            "market/movement/alerts",
+            ["date1", "type", "limit", "is_real"],
+            None
+        ),
+        # 监控数据
+        "zdjk_get": (
+            "open/zdjk/get",
+            ["date1", "date2"],
+            None
+        ),
+    }
+
+    def _register_shortcuts(self):
+        """根据 SHORTCUTS 表动态生成方法"""
+        for name, (path_template, param_names, post_process) in self.SHORTCUTS.items():
+            if name == "daily":
+                continue
+            def make_method(
+                    template: str = path_template,
+                    params_list: List[str] = param_names,
+                    processor: Optional[Callable[[Optional[Dict]], Any]] = post_process
+            ):
+                def shortcut_method(**kwargs) -> Any:
+                    path = template
+                    # 先处理路径参数：从 kwargs 中 pop 并替换 {xxx}
+                    for param in params_list:
+                        placeholder = f"{{{param}}}"
+                        if placeholder in path:
+                            if param not in kwargs:
+                                raise ValueError(f"缺少路径参数 '{param}' for {name}")
+                            value = kwargs.pop(param)
+                            path = path.replace(placeholder, str(value))
+
+                    # 剩下的 kwargs 作为 query 参数
+                    data = self._query(path.lstrip('/'), params=kwargs)
+
+                    # 后处理
+                    if processor:
+                        return processor(data)
+                    return data
+
+                # 绑定方法名和文档
+                shortcut_method.__name__ = name
+                shortcut_method.__doc__ = (
+                    f"快捷调用：{template}\n"
+                    f"参数：{', '.join(params_list)}（路径参数会自动替换）\n"
+                    f"后处理：{processor.__name__ if processor else '无'}"
+                )
+                setattr(self, name, shortcut_method)
+
+            make_method()
+
+    @staticmethod
+    def _normalize_symbol(symbol: str) -> str:
+        return symbol.split(".")[0] if "." in symbol else symbol
+
+    @staticmethod
+    def _to_tushare_ts_code(symbol: str) -> str:
+        normalized = symbol.strip().upper()
+        if "." in normalized:
+            code, suffix = normalized.split(".", 1)
+            suffix_map = {
+                "SS": "SH",
+                "SH": "SH",
+                "XSHG": "SH",
+                "SZ": "SZ",
+                "XSHE": "SZ",
+                "BJ": "BJ",
+                "BSE": "BJ",
+            }
+            return f"{code}.{suffix_map.get(suffix, suffix)}"
+        if normalized.startswith(("6", "5")):
+            return f"{normalized}.SH"
+        if normalized.startswith(("0", "3")):
+            return f"{normalized}.SZ"
+        if normalized.startswith(("8", "4", "2", "9")):
+            return f"{normalized}.BJ"
+        return normalized
+
+    @staticmethod
+    def _to_tushare_exchange(symbol: str) -> str:
+        code = symbol.split(".")[0] if "." in symbol else symbol
+        if code.startswith(("6", "5")):
+            return "SSE"
+        if code.startswith(("0", "3")):
+            return "SZSE"
+        if code.startswith(("8", "4", "2", "9")):
+            return "BSE"
+        return ""
+
+    @staticmethod
+    def _to_backend_exchange(exchange: Optional[str]) -> Optional[str]:
+        if not exchange:
+            return None
+        mapping = {
+            "SSE": "SS",
+            "SZSE": "SZ",
+            "BSE": "BJ",
+            "SH": "SS",
+            "SZ": "SZ",
+            "BJ": "BJ",
+            "GEM": "GEM",
+            "KSH": "KSH",
+            "STAR": "KSH",
+            "SS": "SS",
+            "ALL": "ALL",
+        }
+        return mapping.get(exchange.upper())
+
+    def daily(
+        self,
+        ts_code: Optional[str] = None,
+        trade_date: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+        fields: Optional[str] = None,
+        **kwargs: Any
+    ):
+        use_ts_code = self._to_tushare_ts_code(ts_code) if ts_code else None
+        normalized_trade_date = trade_date.replace("-", "") if trade_date else None
+        normalized_start = start_date.replace("-", "") if start_date else None
+        normalized_end = end_date.replace("-", "") if end_date else None
+        params: Dict[str, Any] = {}
+        adj = str(kwargs.pop("adj", "")).lower()
+        candle_mode = kwargs.pop("candle_mode", None)
+        if candle_mode is None:
+            if adj == "qfq":
+                candle_mode = 1
+            elif adj == "hfq":
+                candle_mode = 2
+            else:
+                candle_mode = 0
+        params["candle_mode"] = candle_mode
+
+        if not use_ts_code:
+            if not normalized_trade_date:
+                raise ValueError("当 ts_code 为空时，trade_date 不能为空")
+            params["trade_date"] = normalized_trade_date
+            if offset is not None:
+                params["offset"] = offset
+            if limit is not None:
+                params["limit"] = limit
+            url = f"{self.http_url}/v3/market/kline/day"
+        else:
+            if normalized_trade_date:
+                params["get_type"] = "range"
+                params["start_date"] = normalized_trade_date
+                params["end_date"] = normalized_trade_date
+            else:
+                params["get_type"] = "range"
+                if normalized_start:
+                    params["start_date"] = normalized_start
+                if normalized_end:
+                    params["end_date"] = normalized_end
+            url = f"{self.http_url}/v3/market/kline/day/{use_ts_code}"
+
+        params.update(kwargs)
+        data: Optional[Union[Dict[str, Any], List[Any]]] = None
+        try:
+            res = requests.get(url, params=params, headers=self.headers, timeout=self.timeout)
+            if res.status_code == 200:
+                body = res.json()
+                if isinstance(body, dict):
+                    if body.get("code") == 200:
+                        data = body.get("data")
+                    elif "data" in body:
+                        data = body.get("data")
+                    else:
+                        data = body
+        except Exception:
+            data = None
+        records: List[Dict[str, Any]] = []
+        data_ts_code: Optional[str] = None
+        if isinstance(data, list):
+            records = [item for item in data if isinstance(item, dict)]
+        elif isinstance(data, dict):
+            data_ts_code = data.get("ts_code")
+            list_data = data.get("list")
+            if isinstance(list_data, list):
+                records = [item for item in list_data if isinstance(item, dict)]
+
+        if records:
+            normalized_rows: List[Dict[str, Any]] = []
+            for row in records:
+                row_ts_code = row.get("ts_code") or row.get("symbol") or row.get("code") or data_ts_code or use_ts_code
+                normalized_rows.append({
+                    "ts_code": self._to_tushare_ts_code(str(row_ts_code)) if row_ts_code else None,
+                    "trade_date": str(row.get("trade_date") or row.get("date") or row.get("day") or "").replace("-", ""),
+                    "open": row.get("open", row.get("o")),
+                    "high": row.get("high", row.get("h")),
+                    "low": row.get("low", row.get("l")),
+                    "close": row.get("close", row.get("c")),
+                    "pre_close": row.get("pre_close", row.get("prev_close")),
+                    "change": row.get("change"),
+                    "pct_chg": row.get("pct_chg", row.get("pct_change", row.get("quote_rate"))),
+                    "vol": row.get("vol", row.get("volume")),
+                    "amount": row.get("amount", row.get("turnover")),
+                })
+            df = pd.DataFrame(normalized_rows)
+        else:
+            df = pd.DataFrame()
+
+        if df.empty:
+            default_columns = [
+                "ts_code", "trade_date", "open", "high", "low", "close",
+                "pre_close", "change", "pct_chg", "vol", "amount"
+            ]
+            return df.reindex(columns=default_columns)
+
+        if "ts_code" not in df.columns:
+            df["ts_code"] = use_ts_code
+        else:
+            df["ts_code"] = df["ts_code"].apply(lambda x: self._to_tushare_ts_code(str(x)) if pd.notna(x) and str(x) else "")
+        if "trade_date" in df.columns:
+            df["trade_date"] = df["trade_date"].astype(str).str.replace("-", "", regex=False)
+        numeric_columns = ["open", "high", "low", "close", "pre_close", "change", "pct_chg", "vol", "amount"]
+        for col in numeric_columns:
+            if col in df.columns:
+                df[col] = pd.to_numeric(df[col], errors="coerce")
+        if "change" in df.columns and "pre_close" in df.columns and "close" in df.columns:
+            missing_change = df["change"].isna()
+            df.loc[missing_change, "change"] = df.loc[missing_change, "close"] - df.loc[missing_change, "pre_close"]
+        if "pct_chg" in df.columns and "change" in df.columns and "pre_close" in df.columns:
+            missing_pct = df["pct_chg"].isna()
+            valid_pre_close = df["pre_close"] != 0
+            fill_mask = missing_pct & valid_pre_close
+            df.loc[fill_mask, "pct_chg"] = (df.loc[fill_mask, "change"] / df.loc[fill_mask, "pre_close"]) * 100
+
+        ordered_columns = [
+            "ts_code", "trade_date", "open", "high", "low", "close",
+            "pre_close", "change", "pct_chg", "vol", "amount"
+        ]
+        df = df.reindex(columns=ordered_columns)
+        df = df.sort_values(by="trade_date", ascending=False).reset_index(drop=True)
+        if use_ts_code:
+            if offset is not None:
+                df = df.iloc[offset:]
+            if limit is not None:
+                df = df.head(limit)
+
+        if fields:
+            requested_fields = [field.strip() for field in fields.split(",") if field.strip()]
+            selected_fields = [field for field in requested_fields if field in df.columns]
+            if selected_fields:
+                return df[selected_fields]
+            return df.iloc[:, 0:0]
+
+        return df
+
+    def stock_basic(
+        self,
+        ts_code: Optional[str] = None,
+        exchange: Optional[str] = None,
+        list_status: str = "L",
+        is_hs: Optional[str] = None,
+        fields: Optional[str] = None,
+        name: Optional[str] = None,
+        **kwargs: Any
+    ):
+        requested_status = (list_status or "L").upper()
+        if requested_status not in {"L", "D", "P"}:
+            raise ValueError("list_status 仅支持 L/D/P")
+
+        backend_exchange = self._to_backend_exchange(exchange)
+        if exchange and backend_exchange is None:
+            raise ValueError("exchange 仅支持 SSE/SZSE/BSE/SH/SZ/BJ/GEM/KSH/STAR/SS/ALL")
+
+        if requested_status == "P":
+            df_empty = pd.DataFrame(columns=[
+                "ts_code", "symbol", "name", "area", "industry", "fullname", "enname",
+                "cnspell", "market", "exchange", "curr_type", "list_status",
+                "list_date", "delist_date", "is_hs"
+            ])
+            if fields:
+                requested_fields = [field.strip() for field in fields.split(",") if field.strip()]
+                selected_fields = [field for field in requested_fields if field in df_empty.columns]
+                if selected_fields:
+                    return df_empty[selected_fields]
+                return df_empty.iloc[:, 0:0]
+            return df_empty
+
+        query_status = requested_status if requested_status in {"L", "D"} else "ALL"
+        exchange_list = [backend_exchange] if backend_exchange else ["SS", "KSH", "SZ", "GEM", "BJ"]
+        rows: List[Dict[str, Any]] = []
+        for ex in exchange_list:
+            data = self._query(
+                "v3/open/stocks/list",
+                params={
+                    "exchange": ex,
+                    "list_status": query_status,
+                    "format": "records"
+                }
+            )
+            if isinstance(data, dict):
+                batch = data.get("list") or []
+                if isinstance(batch, list):
+                    rows.extend(batch)
+
+        normalized_codes: Optional[List[str]] = None
+        if ts_code:
+            normalized_codes = [self._normalize_symbol(item.strip()) for item in ts_code.split(",") if item.strip()]
+
+        result_rows: List[Dict[str, Any]] = []
+        for row in rows:
+            code = str(row.get("code", "")).strip()
+            if not code:
+                continue
+            if normalized_codes is not None and code not in normalized_codes:
+                continue
+            row_name = str(row.get("name", "")).strip()
+            if name and name not in row_name:
+                continue
+
+            ex_name = self._to_tushare_exchange(code)
+            type_code = str(row.get("type_code", "")).upper()
+            market_name = "创业板" if type_code == "GEM" else "科创板" if "KSH" in type_code else ""
+            result_rows.append({
+                "ts_code": self._to_tushare_ts_code(code),
+                "symbol": code,
+                "name": row_name,
+                "area": "",
+                "industry": "",
+                "fullname": row_name,
+                "enname": "",
+                "cnspell": "",
+                "market": market_name,
+                "exchange": ex_name,
+                "curr_type": "CNY",
+                "list_status": str(row.get("list_status", query_status)).upper(),
+                "list_date": "",
+                "delist_date": "",
+                "is_hs": "",
+            })
+
+        df = pd.DataFrame(result_rows)
+        ordered_columns = [
+            "ts_code", "symbol", "name", "area", "industry", "fullname", "enname",
+            "cnspell", "market", "exchange", "curr_type", "list_status",
+            "list_date", "delist_date", "is_hs"
+        ]
+        if df.empty:
+            df = pd.DataFrame(columns=ordered_columns)
+        else:
+            df = df[ordered_columns].drop_duplicates(subset=["ts_code"]).reset_index(drop=True)
+
+        if is_hs:
+            flag = is_hs.upper()
+            if flag in {"H", "S"}:
+                df = df.iloc[0:0]
+
+        if fields:
+            requested_fields = [field.strip() for field in fields.split(",") if field.strip()]
+            selected_fields = [field for field in requested_fields if field in df.columns]
+            if selected_fields:
+                return df[selected_fields]
+            return df.iloc[:, 0:0]
+
+        return df