databull 0.1.0__py3-none-any.whl

databull/__init__.py

@@ -0,0 +1,21 @@
+"""databull —— DataBull 中国 A 股市场数据 API 的 Python SDK。
+
+快速开始::
+
+    pip install databull
+
+    from databull import DataBull
+
+    client = DataBull("dbt_xxx")            # 也可用环境变量 DATABULL_API_KEY
+    df = client.get_stock_history("600519", "2026-01-01", "2026-09-01")
+    print(df.head())
+
+出错统一抛 :class:`DataBullError`（不静默返回 None）；空结果的原因挂在
+``client.last_empty_reason``。全部可用端点见 README 的端点表。
+"""
+
+from __future__ import annotations
+
+from .client import DataBull, DataBullError, __version__
+
+__all__ = ["DataBull", "DataBullError", "__version__"]

databull/__main__.py

@@ -0,0 +1,15 @@
+"""``python -m databull <endpoint> [--params JSON]`` —— 不写代码时快速探一个接口。
+
+示例::
+
+    python -m databull cn/stocks --params '{"q": "茅台"}'
+    python -m databull cn/index/search --params '{"keyword": "沪深300"}'
+    python -m databull --version
+"""
+
+from __future__ import annotations
+
+from .client import _cli
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())

databull/client.py

@@ -0,0 +1,745 @@
+"""DataBull Python SDK —— 中国 A 股市场数据 API 官方客户端。
+
+覆盖 DataBull 已上线并经生产验证的 28 个 REST 端点与 5 个 MCP 工具。
+鉴权：``Authorization: Bearer <Key>``（也接受 ``X-API-Key``）；Key 在
+https://www.databull.cn/console/register 免费注册后于控制台创建。
+基址默认 https://api.databull.cn，可用 ``base_url`` 覆盖。
+
+快速开始::
+
+    from databull import DataBull
+
+    client = DataBull("dbt_xxx")          # 也可只设环境变量 DATABULL_API_KEY
+    df = client.get_stock_history("600519", "2026-01-01", "2026-09-01")
+
+设计上的三个要点：
+
+1. **出错显式抛 ``DataBullError``**，不静默返回 None —— 本项目反复出现「不报错但返回空」
+   这类缺陷，把「请求失败」与「这段区间没数据」混在一起会让调用方误判。
+2. **空结果带原因**：响应头 ``X-Empty-Reason`` / 体内 ``empty_reason`` 会挂到
+   ``client.last_empty_reason``，用来区分「数据还没采到」与「代码写错了」。
+3. **参数先规整再发**：代码一律用裸码（600519 而不是 600519.SH），日期常见写法都收。
+   服务端对这两件事都不严格一致——个股传后缀会 400、指数传后缀会**静默返回空数组**；
+   ``/cn/index/history`` 只认 ``YYYYMMDD`` 而其余端点两种都收。这些差异都在
+   ``_request`` 里统一抹平（``_normalize_symbol`` / ``_normalize_date``），
+   新增方法不必各自记得转换。
+
+本文件是 SDK 的**唯一源**。分发给 WorkBuddy skill 的单文件版本
+（``public/skill/databull_client.py``）由仓库根的 ``build_sdk.py`` 从本文件生成，
+请勿直接编辑那一份。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from typing import Any, Dict, Optional
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+#: SDK 版本。**唯一源**：pyproject.toml 通过 dynamic 从本属性读取，
+#: 不要再在别处硬编码版本号（testcase/test_databull_sdk.py 会校验一致性）。
+__version__ = "0.1.0"
+
+__all__ = ["DataBull", "DataBullError", "__version__"]
+
+
+class DataBullError(Exception):
+    """DataBull API 调用错误，携带 HTTP 状态码与响应体。
+
+    :ivar status: HTTP 状态码；本地校验失败（未发请求）时为 0
+    :ivar body: 服务端原始响应体，可能为 None
+    """
+
+    def __init__(self, status: int, message: str, body: Optional[str] = None) -> None:
+        self.status = status
+        self.body = body
+        super().__init__(f"[{status}] {message}")
+
+
+# 交易所后缀白名单：仅用于"剥离"，绝不能误伤美股代码里的点（如 BRK.B）。
+_EXCHANGE_SUFFIXES = {"SZ", "SH", "BJ", "SS", "XSHE", "XSHG"}
+
+# 指数清单的「市场」是发布方维度，取值与作为基址路径前缀的 market=cn/us/hk
+# 完全不同。两者名字都叫 market，混用**不会报错**，只会静默筛不到（空列表 +
+# empty_reason=no_match），所以这里显式拦一道并给出可读提示。
+_INDEX_MARKETS = frozenset({"SSE", "SZSE", "CSI", "SW"})
+_PATH_MARKETS = frozenset({"CN", "US", "HK"})
+
+# 常见日期写法：2026-08-01 / 2026/8/1 / 2026.8.1（见 _normalize_date）
+_DATE_RE = re.compile(r"^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})$")
+
+
+def _normalize_symbol(symbol: str) -> str:
+    """把带交易所后缀的代码规整为 DataBull 接受的裸代码。
+
+    DataBull 的个股/ETF/指数接口（symbol / index_code 参数）都只接受裸代码，
+    如 000001、600519、510300；市场由 URL 路径决定（/cn、/us、/hk），不在代码里标注。
+    传入 000001.SZ 会被 validate_stock_code 拒绝并返回 400（长度超限 + 格式不符）；
+    指数传 000001.SH 更隐蔽——不报错但静默查不到数据（返回空数组）。
+
+    本函数自动剥掉尾部 .SZ/.SH/.BJ/.SS 等后缀，但保留代码本身含有的点
+    （如美股 BRK.B），避免误伤。
+
+    :param symbol: 原始代码，可带后缀
+    :return: 裸代码；输入非字符串时原样返回
+    """
+    if not symbol or not isinstance(symbol, str):
+        return symbol
+    s = symbol.strip().upper()
+    if "." in s:
+        head, _, tail = s.rpartition(".")
+        if tail in _EXCHANGE_SUFFIXES:
+            return head
+    return s
+
+
+def _normalize_date(value: Optional[str]) -> Optional[str]:
+    """把常见日期写法（2026-08-01 / 2026/8/1 / 2026.8.1）规整成 YYYYMMDD。
+
+    服务端对日期的要求并不统一：实测只有 ``/cn/index/history`` 严格要求
+    ``YYYYMMDD``（传 2026-08-01 直接 400「日期格式错误，请使用YYYYMMDD格式」），
+    其余带日期的端点两种写法都收。同一个 SDK 里不同方法要求不同写法是纯粹的坑，
+    所以在这里统一收口：客户端一律接受常见写法，发请求时转成服务端要的格式。
+
+    识别不出来的写法原样透传，让服务端给出它自己的错误信息（比客户端瞎猜好）。
+
+    :param value: 调用方传入的日期，可为空
+    :return: YYYYMMDD 形式的字符串；空值或无法识别时原样返回
+    """
+    if not value or not isinstance(value, str):
+        return value
+    m = _DATE_RE.match(value.strip())
+    if not m:
+        return value
+    year, month, day = m.groups()
+    return f"{year}{int(month):02d}{int(day):02d}"
+
+
+def _normalize_index_market(value: Optional[str]) -> str:
+    """校验指数清单的市场过滤值，把「传了行情市场」这种常见误用显式拦下。
+
+    服务端把这个参数叫 `market`，但它的取值是发布方（SSE/SZSE/CSI/SW），
+    而不是行情基址里的 cn/us/hk。传错时服务端**不报错**，只返回空列表并带
+    empty_reason=no_match，很容易被当成「这个市场没有指数」。
+
+    :param value: 调用方传入的市场过滤值，可为空
+    :return: 规整后的过滤值（空串表示不过滤）
+    :raises DataBullError: 传了 cn/us/hk 等行情市场值，或不在允许取值内
+    """
+    v = (value or "").strip()
+    if not v:
+        return ""
+    if v.upper() in _PATH_MARKETS:
+        raise DataBullError(
+            0,
+            f"index_market={value!r} 是行情市场（cn/us/hk），指数清单的市场过滤只接受 "
+            f"{'/'.join(sorted(_INDEX_MARKETS))}；两者含义不同，留空表示不限。",
+        )
+    if v.upper() not in _INDEX_MARKETS:
+        raise DataBullError(
+            0,
+            f"index_market={value!r} 不是合法的指数市场，可选："
+            f"{'/'.join(sorted(_INDEX_MARKETS))}；留空表示不限。",
+        )
+    return v.upper()
+
+
+class DataBull:
+    """DataBull 数据 API 客户端。
+
+    :param api_key: API Key；留空则读环境变量 ``DATABULL_API_KEY``
+    :param base_url: 覆盖服务基址，默认 https://api.databull.cn
+    :param timeout: 单次请求超时秒数，默认 15
+    :raises DataBullError: 未提供任何 API Key 时立即抛出（不等到第一次请求才失败）
+    """
+
+    DEFAULT_BASE_URL = "https://api.databull.cn"
+
+    # 合法的 HTTP 方法，用于区分 _request 的两种调用风格（见 _request 注释）
+    _HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"})
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 15,
+    ) -> None:
+        self.api_key = api_key or os.getenv("DATABULL_API_KEY")
+        if not self.api_key:
+            raise DataBullError(
+                0,
+                "缺少 API Key：请设置环境变量 DATABULL_API_KEY，或在构造时传入 api_key。",
+            )
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._last_empty_reason: Optional[str] = None
+        self.session = self._build_session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+    def __repr__(self) -> str:
+        # 不回显 api_key：__repr__ 常出现在日志与 traceback 里
+        return f"DataBull(base_url={self.base_url!r}, version={__version__!r})"
+
+    # -------------------------- 底层请求 --------------------------
+    def _build_session(self) -> requests.Session:
+        session = requests.Session()
+        adapter = HTTPAdapter(pool_connections=20, pool_maxsize=20)
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+        retry = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        session.mount("https://", HTTPAdapter(max_retries=retry))
+        return session
+
+    def _request(
+        self,
+        method: str,
+        endpoint: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """发一次请求并返回解析后的 JSON。
+
+        本类的方法有两种写法，两者都必须能跑（曾因删掉这段兜底，
+        导致分发出去的客户端除 get_index_history/call_mcp_tool 外**全部**在
+        第一行就 AttributeError: 'NoneType' object has no attribute 'lstrip'）：:
+
+            _request("cn/index/history", params=...)        # 只给路径，方法默认 GET
+            _request("POST", "/mcp/call", json_body=...)    # 显式给方法
+
+        判定方式：第二个参数为空、或首参不是合法 HTTP 方法，就把首参当路径。
+        另外兼容「旧客户端的 _request(endpoint, params)」写法，即第二个位置参数
+        直接是参数字典。
+
+        :param method: HTTP 方法，或（简写风格下）请求路径
+        :param endpoint: 请求路径；简写风格下留空
+        :param params: 查询参数
+        :param json_body: POST 体
+        :return: 响应 JSON（dict 或 list）
+        :raises DataBullError: 超时 / 连接失败 / 非 2xx / 响应非 JSON
+        """
+        if isinstance(endpoint, dict) and params is None:
+            # 旧签名 _request(endpoint, params)：第二个位置参数是查询参数
+            method, endpoint, params = "GET", method, endpoint
+        elif endpoint is None or str(method).upper() not in self._HTTP_METHODS:
+            method, endpoint = "GET", method
+        if not isinstance(endpoint, str) or not endpoint.strip():
+            raise DataBullError(0, "请求路径为空")
+
+        url = self.base_url.rstrip("/") + "/" + endpoint.lstrip("/")
+        if params:
+            params = dict(params)
+            # symbol 与 index_code 都只接受裸码：个股/ETF 传后缀会被拒 400，
+            # 指数传后缀不报错但静默返回空数组。统一在此剥离后缀。
+            for key in ("symbol", "index_code"):
+                if isinstance(params.get(key), str):
+                    params[key] = _normalize_symbol(params[key])
+            # 日期写法也在此统一：服务端只有 /cn/index/history 严格要求 YYYYMMDD，
+            # 其余端点两种都收。集中规整，新增方法不必各自记得转换。
+            for key in ("start_date", "end_date"):
+                if isinstance(params.get(key), str):
+                    params[key] = _normalize_date(params[key])
+        try:
+            resp = self.session.request(
+                method, url, params=params, json=json_body, timeout=self.timeout
+            )
+        except requests.exceptions.Timeout:
+            raise DataBullError(0, "请求超时")
+        except requests.exceptions.ConnectionError:
+            raise DataBullError(0, "网络连接失败")
+
+        if resp.status_code == 429:
+            retry_after = resp.headers.get("Retry-After")
+            msg = "调用频率超限（429）"
+            if retry_after:
+                msg += f"，建议 {retry_after}s 后重试"
+            raise DataBullError(429, msg, resp.text)
+        if not resp.ok:
+            raise DataBullError(resp.status_code, f"HTTP 错误：{resp.text[:300]}", resp.text)
+
+        try:
+            payload = resp.json()
+        except ValueError:
+            raise DataBullError(resp.status_code, "响应不是合法 JSON", resp.text)
+
+        # 服务端对「空结果」会在响应头 X-Empty-Reason（数组型响应）或体内
+        # empty_reason（对象型响应）里给出原因。把它挂到返回对象上，调用方
+        # 就不会把「数据还没采到 / 代码写错了」误当成「这个标的没行情」。
+        self._last_empty_reason = resp.headers.get("X-Empty-Reason")
+        if not self._last_empty_reason and isinstance(payload, dict):
+            self._last_empty_reason = payload.get("empty_reason")
+        return payload
+
+    @property
+    def last_empty_reason(self) -> Optional[str]:
+        """最近一次请求为空结果时的原因（None 表示最近一次请求非空/无标注）。"""
+        return getattr(self, "_last_empty_reason", None)
+
+    @staticmethod
+    def _to_dataframe(data: Any, date_col: str = "date"):
+        """把接口返回的 JSON 转成带日期索引的 DataFrame。
+
+        :param data: 接口 data 字段（list 或 dict）
+        :param date_col: 用作索引的日期列名
+        :return: DataFrame；数据为空或类型不符时返回 None
+        :raises ImportError: 未安装 pandas（它是可选依赖：``pip install databull[pandas]``）
+        """
+        try:
+            import pandas as pd  # 延迟导入：无 pandas 环境仍可用全部返回 JSON 的方法
+        except ImportError as e:  # 给出可直接照做的提示，而不是裸的 ModuleNotFoundError
+            raise ImportError(
+                "该方法返回 DataFrame，需要 pandas：pip install 'databull[pandas]'"
+            ) from e
+
+        if not data:
+            return None
+        if isinstance(data, (list, dict)):
+            df = pd.DataFrame(data)
+            if df.empty:
+                return None
+            if date_col in df.columns:
+                df[date_col] = pd.to_datetime(df[date_col])
+                df.set_index(date_col, inplace=True)
+            return df
+        return None
+
+    # -------------------------- 指数 --------------------------
+    def get_index_history(
+        self, index_code: str, start_date: str, end_date: str, market: str = "cn"
+    ):
+        """指数历史日线行情。
+
+        :param index_code: 指数代码（裸码，如 000300；传 000300.SH 也能自动剥离）
+        :param start_date: 起始日，YYYY-MM-DD / YYYYMMDD 都可以（本端点服务端只认
+            YYYYMMDD，客户端会自动转换；留空表示不限）
+        :param end_date: 结束日，同上
+        :param market: 基址路径前缀（cn/us/hk），默认 cn
+        :return: 带日期索引的 DataFrame
+        """
+        data = self._request(
+            "GET",
+            f"{market}/index/history",
+            params={"index_code": index_code, "start_date": start_date, "end_date": end_date},
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    def get_index_list(
+        self,
+        index_market: str = "",
+        category: str = "",
+        keyword: str = "",
+        page: int = 1,
+        page_size: int = 100,
+        market: str = "cn",
+    ):
+        """指数清单分页查询（平台收录了哪些指数）。
+
+        :param index_market: **指数市场过滤**，SSE 上交所 / SZSE 深交所 / CSI 中证 /
+            SW 申万；留空表示不限
+        :param category: 分类过滤，如 规模指数 / 行业指数 / 主题指数 / 策略指数；
+            须与库中取值完全一致，留空表示不限
+        :param keyword: 关键词，同时匹配名称、裸码与全码（沪深300 / 000300）
+        :param page: 页码，从 1 开始
+        :param page_size: 每页条数，1~500
+        :param market: 基址路径前缀（cn/us/hk），默认 cn —— 注意它**不是**市场过滤，
+            市场过滤请用 index_market
+        :return: {'code': 0, 'data': {'items': [...], 'total': int, 'page': int,
+                 'page_size': int, 'has_more': bool}}，空结果额外带 'empty_reason'
+                 （catalog_not_synced = 清单还没同步；no_match = 条件太窄没筛到）
+        """
+        params: Dict[str, Any] = {"page": page, "page_size": page_size}
+        checked = _normalize_index_market(index_market)
+        if checked:
+            params["market"] = checked
+        if category:
+            params["category"] = category
+        if keyword:
+            params["keyword"] = keyword
+        return self._request(f"{market}/index/list", params=params)
+
+    def search_index(
+        self, keyword: str, limit: int = 20, index_market: str = "", market: str = "cn"
+    ):
+        """按关键词搜索指数，按相关度排序（适合输入框联想）。
+
+        相关度：裸码/全码完全相等 > 裸码前缀 > 名称前缀 > 名称包含 > 代码包含。
+        与 get_index_list(keyword=...) 的区别：本方法 keyword 必填且按**相关度**排序，
+        列表接口则是按代码升序的严格过滤，两者互补。
+
+        :param keyword: 搜索关键词（必填）：名称、裸码或全码，如 沪深300 / 000300 / 000300.SH
+        :param limit: 返回条数上限，1~100
+        :param index_market: 指数市场过滤 SSE / SZSE / CSI / SW；留空不限
+        :param market: 基址路径前缀（cn/us/hk），默认 cn；市场过滤请用 index_market
+        :return: {'code': 0, 'data': [...]}，没搜到时 data 为空数组且 empty_reason=no_match
+        :raises DataBullError: keyword 为空时（本地拦下，不发请求）
+        """
+        if not keyword or not str(keyword).strip():
+            raise DataBullError(0, "keyword 必填：请传指数名称、裸码或全码")
+        params: Dict[str, Any] = {"keyword": keyword, "limit": limit}
+        checked = _normalize_index_market(index_market)
+        if checked:
+            params["market"] = checked
+        return self._request(f"{market}/index/search", params=params)
+
+    def get_index_constituents(
+        self,
+        index_code: str = "000300",
+        page: int = 1,
+        page_size: int = 100,
+        market: str = "cn",
+    ):
+        """指数成分股及权重（按权重降序，最新一期快照）。
+
+        注意成分股**每天只同步主流宽基与常用行业主题指数**，不在同步名单里的指数
+        返回空并带 empty_reason=constituents_not_synced。
+
+        :param index_code: 指数代码，裸码 000300 或全码 000300.SH 都可以
+        :param page: 页码，从 1 开始
+        :param page_size: 每页条数，1~5000
+        :param market: 基址路径前缀（cn/us/hk），默认 cn
+        :return: {'code': 0, 'data': {'items': [...], 'total': int, 'page': int,
+                 'page_size': int, 'has_more': bool, 'trade_date': str|None,
+                 'index': {命中的指数档案}}}；空结果带 empty_reason
+                 （constituents_not_synced = 该指数不在每日同步名单；
+                 index_not_found = 清单里没这只指数）
+        """
+        return self._request(
+            f"{market}/index/constituents",
+            params={"index_code": index_code, "page": page, "page_size": page_size},
+        )
+
+    # -------------------------- A股 个股 --------------------------
+    def get_stock_list(
+        self,
+        market: str = "cn",
+        q: Optional[str] = None,
+        exchange: Optional[str] = None,
+        search: Optional[str] = None,
+    ):
+        """A股/ETF/指数标的清单，支持关键词与交易所过滤。
+
+        :param market: 基址路径前缀，默认 cn
+        :param q: 关键词
+        :param exchange: 交易所 SH/SZ
+        :param search: 【deprecated】旧客户端的参数名，等价于 q，保留以兼容既有调用点
+        :return: {'code': 0, 'data': [...]}
+        """
+        params: Dict[str, Any] = {}
+        keyword = q or search
+        if keyword:
+            params["q"] = keyword
+        if exchange:
+            params["exchange"] = exchange
+        return self._request(f"{market}/stocks", params=params or None)
+
+    def get_stock_info(self, symbol: str, market: str = "cn"):
+        """个股基本信息（symbol/name/market/float_volume/total_volume）。"""
+        return self._request(f"{market}/stock/info", params={"symbol": symbol})
+
+    def get_company_profile(self, symbol: str, market: str = "cn"):
+        """公司简介。"""
+        return self._request(f"{market}/stock/profile", params={"symbol": symbol})
+
+    def get_stock_history(
+        self,
+        symbol: str,
+        start_date: str,
+        end_date: str,
+        period: str = "d",
+        market: str = "cn",
+    ):
+        """个股历史行情（日线/分钟线），返回带日期索引的 DataFrame。"""
+        data = self._request(
+            f"{market}/stock/history",
+            params={
+                "symbol": symbol,
+                "start_date": start_date,
+                "end_date": end_date,
+                "period": period,
+                "v": "1.0",
+            },
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    def get_stock_financial_data(
+        self,
+        symbol: str,
+        start_date: str,
+        end_date: str,
+        report_type: str = "Balance",
+    ):
+        """个股财报：report_type ∈ Balance/Income/CashFlow/Capital。"""
+        return self._request(
+            "cn/stock/financial_data",
+            params={
+                "symbol": symbol,
+                "start_date": start_date,
+                "end_date": end_date,
+                "report_type": report_type,
+            },
+        )
+
+    # -------------------------- 美股 / 港股 --------------------------
+    def get_us_stock_info(self, symbol: str):
+        """美股个股基本信息。"""
+        return self._request("us/stock/info", params={"symbol": symbol})
+
+    def get_us_stock_history(
+        self, symbol: str, start_date: str, end_date: str, period: str = "d"
+    ):
+        """美股历史行情，返回带日期索引的 DataFrame。"""
+        data = self._request(
+            "us/stock/history",
+            params={
+                "symbol": symbol,
+                "start_date": start_date,
+                "end_date": end_date,
+                "period": period,
+            },
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    def get_hk_stock_info(self, symbol: str):
+        """港股个股基本信息。"""
+        return self._request("hk/stock/info", params={"symbol": symbol})
+
+    def get_hk_stock_history(
+        self, symbol: str, start_date: str, end_date: str, period: str = "d"
+    ):
+        """港股历史行情，返回带日期索引的 DataFrame。"""
+        data = self._request(
+            "hk/stock/history",
+            params={
+                "symbol": symbol,
+                "start_date": start_date,
+                "end_date": end_date,
+                "period": period,
+            },
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    # -------------------------- ETF --------------------------
+    def get_etf_list(
+        self,
+        market: str = "cn",
+        q: Optional[str] = None,
+        exchange: Optional[str] = None,
+        search: Optional[str] = None,
+    ):
+        """ETF 清单，支持关键词与交易所过滤。
+
+        :param search: 【deprecated】旧客户端的参数名，等价于 q
+        """
+        params: Dict[str, Any] = {}
+        keyword = q or search
+        if keyword:
+            params["q"] = keyword
+        if exchange:
+            params["exchange"] = exchange
+        return self._request(f"{market}/etfs", params=params or None)
+
+    def get_etf_info(self, symbol: str, market: str = "cn"):
+        """ETF 基本信息。"""
+        res = self._request(f"{market}/etfs/info", params={"symbol": symbol})
+        return res.get("data") if isinstance(res, dict) else res
+
+    def get_etf_pcf(self, symbol: str, market: str = "cn"):
+        """ETF 申赎清单（PCF）。"""
+        return self._request(f"{market}/etfs/etf_pcf", params={"symbol": symbol})
+
+    def get_etf_composition(self, symbol: str, market: str = "cn"):
+        """ETF 成分股。
+
+        注意路径是 ``/{market}/etfs/etf_composition``：旧客户端的
+        ``/{market}/etf_composition`` 少一层 ``etfs``，线上是 404。
+        """
+        return self._request(f"{market}/etfs/etf_composition", params={"symbol": symbol})
+
+    def get_etf_history(self, symbol: str, start_date: str, end_date: str, market: str = "cn"):
+        """ETF 历史净值/行情，返回带日期索引的 DataFrame。"""
+        data = self._request(
+            f"{market}/etf/history",
+            params={"symbol": symbol, "start_date": start_date, "end_date": end_date},
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    # -------------------------- 新闻 --------------------------
+    def get_news_flash(self, sources: Optional[str] = None, limit: Optional[int] = None):
+        """财经快讯（财联社/金十/新浪三源）。sources 逗号分隔过滤来源。"""
+        params: Dict[str, Any] = {}
+        if sources:
+            params["sources"] = sources
+        if limit:
+            params["limit"] = limit
+        return self._request("v2/news/flash", params=params or None)
+
+    def get_news_flash_sources(self):
+        """财经快讯可用来源列表。"""
+        return self._request("v2/news/flash/sources")
+
+    def get_market_news(self, page: int = 1, page_size: int = 20, market: str = "cn"):
+        """市场新闻列表。"""
+        return self._request(
+            f"{market}/market/news", params={"page": page, "page_size": page_size}
+        )
+
+    def get_market_news_detail(self, news_id: str, market: str = "cn"):
+        """市场新闻详情。"""
+        return self._request(f"{market}/market/news/{news_id}")
+
+    # -------------------------- 市场 / 板块 --------------------------
+    def get_fear_greed(self, index_code: str, start_date: str, end_date: str, market: str = "cn"):
+        """恐惧与贪婪指数日线，返回带日期索引的 DataFrame。"""
+        data = self._request(
+            f"{market}/market/fear_greed",
+            params={"index_code": index_code, "start_date": start_date, "end_date": end_date},
+        )
+        return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
+
+    def get_sector_data(self, sector_type: str, market: str = "cn"):
+        """申万板块涨跌幅。sector_type 仅接受 sw1/sw2/sw3（小写，不区分大小写）。"""
+        return self._request(f"{market}/market/sector_data/{sector_type}")
+
+    def get_sector_catalog(self, sector_type: str, market: str = "cn"):
+        """申万行业板块清单（静态，每周从 Tushare SW2021 同步）。sector_type ∈ sw1/sw2/sw3。"""
+        return self._request(f"{market}/market/sector_catalog/{sector_type}")
+
+    # -------------------------- 实时 / Tick --------------------------
+    def get_realtime(self, symbol: str, tick_type: str = "stock", market: str = "cn"):
+        """个股实时 Tick / 日内分时。"""
+        return self._request(
+            f"{market}/stock/tick", params={"symbol": symbol, "tick_type": tick_type}
+        )
+
+    def get_tick_all(self, tick_type: str = "stock", market: str = "cn"):
+        """全量 Tick 数据包。
+
+        tick_type ∈ stock / etf / index —— 采集端按类型分别写入快照，
+        读取时必须带上类型，否则键不匹配会恒定拿到空对象。
+        """
+        return self._request(f"{market}/tick/tickall", params={"tick_type": tick_type})
+
+    def get_trading_calendar(
+        self,
+        market: str = "cn",
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        year: Optional[int] = None,
+    ):
+        """交易日历，返回 ISO 日期字符串数组。"""
+        params: Dict[str, Any] = {}
+        if market and market != "cn":
+            params["market"] = market
+        if start_date:
+            params["start_date"] = start_date
+        if end_date:
+            params["end_date"] = end_date
+        if year is not None:
+            params["year"] = year
+        return self._request(f"{market}/tick/trading_calendar", params=params or None)
+
+    # -------------------------- MCP 工具接口（托管 MCP 服务用）--------------------------
+    def call_mcp_tool(self, function_name: str, parameters: Optional[Dict[str, Any]] = None):
+        """调用托管 MCP 工具（/mcp/call）。已暴露工具见 references/endpoints.md。"""
+        params = dict(parameters or {})
+        # 同 _request：symbol / index_code 都规整为裸码
+        for key in ("symbol", "index_code"):
+            if isinstance(params.get(key), str):
+                params[key] = _normalize_symbol(params[key])
+        return self._request(
+            "POST", "/mcp/call", json_body={"function_name": function_name, "parameters": params}
+        )
+
+    # -------------------------- 兼容旧方法名（deprecated） --------------------------
+    # 仓库内旧客户端 service/databull_api.py 用的方法名与上面不同，为不打断既有
+    # 调用点（utils/beta_calculate.py 等），这里保留同名转发。新代码请直接用上面
+    # 的新名字；这几个别名将来会移除。
+    # 注意：旧客户端出错是「print 后返回 None」，这里是抛 DataBullError —— 迁移时
+    # 调用方若依赖 None 分支，要改成 except DataBullError。
+
+    def get_history(
+        self, symbol: str, start_date: str, end_date: str, period: str = "d", market: str = "cn"
+    ):
+        """【deprecated】旧名，请改用 :meth:`get_stock_history`。"""
+        return self.get_stock_history(
+            symbol, start_date, end_date, period=period, market=market
+        )
+
+    def get_market_sector(self, sector_type: str = "sw1", market: str = "cn"):
+        """【deprecated】旧名，请改用 :meth:`get_sector_data`。"""
+        return self.get_sector_data(sector_type, market=market)
+
+    def get_company(self, symbol: str, market: str = "cn"):
+        """【deprecated】旧名，请改用 :meth:`get_company_profile`。
+
+        与旧实现的差异：旧版把响应里的 ``data`` 取出来再返回，本别名与其他方法
+        一致返回完整响应体（``{'code': 0, 'data': {...}}``）。
+        """
+        return self.get_company_profile(symbol, market=market)
+
+    def get_last_tick(self, symbol: str, tick_type: str = "stock", market: str = "cn"):
+        """【deprecated】旧名，请改用 :meth:`get_realtime`。"""
+        return self.get_realtime(symbol, tick_type=tick_type, market=market)
+
+    def get_market_fear_greed(
+        self, index_code: str, start_date: str, end_date: str, market: str = "cn"
+    ):
+        """【deprecated】旧名，请改用 :meth:`get_fear_greed`。"""
+        return self.get_fear_greed(index_code, start_date, end_date, market=market)
+
+
+def _cli() -> int:
+    """``python -m databull`` / 单文件版的命令行入口。"""
+    parser = argparse.ArgumentParser(
+        prog="databull", description="DataBull API 命令行客户端"
+    )
+    parser.add_argument("endpoint", nargs="?", help="端点路径，如 cn/stock/info")
+    parser.add_argument("--params", help="JSON 字符串，作为查询参数或 POST body")
+    parser.add_argument("--method", default="GET", help="HTTP 方法，默认 GET")
+    parser.add_argument("--base-url", default=None, help="覆盖基址")
+    parser.add_argument("--api-key", default=None, help="覆盖 DATABULL_API_KEY")
+    parser.add_argument("--version", action="store_true", help="打印 SDK 版本后退出")
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"databull {__version__}")
+        return 0
+    if not args.endpoint:
+        parser.print_help()
+        return 2
+
+    try:
+        client = DataBull(api_key=args.api_key, base_url=args.base_url)
+        params = json.loads(args.params) if args.params else None
+        if args.method.upper() == "GET":
+            result = client._request("GET", args.endpoint, params=params)
+        else:
+            result = client._request(args.method.upper(), args.endpoint, json_body=params)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except DataBullError as e:
+        print(f"DataBullError: {e}", file=sys.stderr)
+        if e.body:
+            print(e.body, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())

databull-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: databull
+Version: 0.1.0
+Summary: DataBull 中国 A 股市场数据 API 官方 Python SDK（行情、财务、ETF、指数、板块、快讯）
+Author-email: Yc <yccheni@163.com>
+Project-URL: Homepage, https://www.databull.cn
+Project-URL: Documentation, https://www.databull.cn/docs
+Project-URL: Source, https://www.databull.cn/sdk
+Project-URL: API Console, https://www.databull.cn/console
+Keywords: databull,stock,a-share,china,finance,market-data,api,etf,index
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: urllib3>=1.26
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+
+# databull — DataBull Python SDK
+
+DataBull 中国 A 股市场数据 API 的官方 Python 客户端。覆盖**沪深个股日线与实时行情、财务报表、
+ETF（含申赎清单与成分股）、指数清单/搜索/成分股权重、申万板块、市场情绪、财经快讯**，
+共 28 个 REST 端点与 5 个 MCP 工具。
+
+- 官网与文档：https://www.databull.cn/docs
+- 免费注册并创建 API Key：https://www.databull.cn/console/register
+
+## 安装
+
+```bash
+pip install databull              # 仅 JSON 查询，依赖只有 requests
+pip install "databull[pandas]"    # 需要 *_history / fear_greed 返回 DataFrame 时
+```
+
+国内直连 PyPI 慢时，可从官网下载 wheel 安装：
+
+```bash
+pip install https://www.databull.cn/sdk/files/databull-0.1.0-py3-none-any.whl
+```
+
+## 快速开始
+
+```python
+from databull import DataBull, DataBullError
+
+client = DataBull("dbt_xxxxxxxx")          # 也可只设环境变量 DATABULL_API_KEY
+# 自建/代理时可指定基址：DataBull(api_key, base_url="https://api.example.com")
+
+# 个股日线（返回带日期索引的 DataFrame）
+df = client.get_stock_history("600519", "2026-01-01", "2026-09-01")
+print(df.tail())
+
+# 指数搜索与成分股权重
+hits = client.search_index("沪深300", limit=5)
+cons = client.get_index_constituents("000300", page_size=10)["data"]
+
+# 申万一级行业涨跌
+sectors = client.get_sector_data("sw1")
+```
+
+命令行也可以直接探接口（不用写代码）：
+
+```bash
+export DATABULL_API_KEY=dbt_xxxxxxxx
+python -m databull cn/index/search --params '{"keyword": "沪深300"}'
+databull cn/stocks --params '{"q": "茅台"}'      # 安装了就绪脚本
+python -m databull --version
+```
+
+## 出错与空结果
+
+**出错不静默**：所有失败都抛 `DataBullError`，带上 HTTP 状态码与原始响应体。
+不要用「返回 None」判断失败——本项目历史上就吃过这个亏。
+
+```python
+try:
+    client.get_stock_history("600519", "2026-01-01", "2026-09-01")
+except DataBullError as e:
+    print(e.status, e)          # 401=Key 无效 403=超出套餐额度 429=调用频率超限
+    print(e.body)
+```
+
+**空结果带原因**：接口在「没有数据」时返回空数组/空对象而不是报错，原因通过响应头
+`X-Empty-Reason`（数组型）或体内 `empty_reason`（对象型）给出，SDK 把它挂到
+`client.last_empty_reason`：
+
+```python
+data = client.get_index_constituents("801010")
+if not data["data"]["items"]:
+    print(client.last_empty_reason)   # constituents_not_synced = 该指数不在每日同步名单
+```
+
+常见取值：`index_not_found`、`no_data_in_range`、`calendar_not_loaded`、`no_match`、
+`sector_data_not_collected`、`tick_not_uploaded`、`catalog_not_synced`、
+`constituents_not_synced`。
+
+## 参数与返回约定（容易踩的两点）
+
+1. **代码一律用裸码**，不带交易所后缀：`600519` 而不是 `600519.SH`；市场由接口决定。
+   传后缀时个股会 400，指数**不报错但静默返回空数组**——SDK 已自动剥离后缀，
+   但你自己拼 URL 时要注意。
+2. **日期写法都收**：`2026-08-01`、`20260801`、`2026/8/1` 都可以。服务端并不统一——
+   实测只有 `/cn/index/history` 严格要求 `YYYYMMDD`（传 `2026-08-01` 直接 400），
+   其余端点两种都收；SDK 在发请求前统一转换，所以你不必记这件事。
+3. **`market` 有两种含义**：作为基址路径前缀时是 `cn` / `us` / `hk`；作为**指数清单的
+   过滤条件**时是 `SSE` / `SZSE` / `CSI` / `SW`。两者混用不会报错、只会筛不到。
+   SDK 把后者命名为 `index_market` 并会提前拦下错误取值。
+
+**返回形态不统一**：多数方法返回 `{"code": 0, "data": ...}`，但少数接口直接返回数组
+（例如 `get_sector_data` 返回 `[{...}, ...]`）。SDK 原样透传，不做包装——
+按方法逐个确认一次，比被一层"透明"包装误导更好。
+
+## 端点与方法对照
+
+| 能力 | 方法 | 路径 |
+| --- | --- | --- |
+| 指数历史日线 | `get_index_history` | `GET /cn/index/history` |
+| 指数清单（分页/过滤） | `get_index_list` | `GET /cn/index/list` |
+| 指数搜索（相关度排序） | `search_index` | `GET /cn/index/search` |
+| 指数成分股与权重 | `get_index_constituents` | `GET /cn/index/constituents` |
+| A股/ETF/指数标的清单 | `get_stock_list` | `GET /cn/stocks` |
+| 个股基本信息 | `get_stock_info` | `GET /cn/stock/info` |
+| 公司简介 | `get_company_profile` | `GET /cn/stock/profile` |
+| 个股历史行情 | `get_stock_history` | `GET /cn/stock/history` |
+| 个股财务报表 | `get_stock_financial_data` | `GET /cn/stock/financial_data` |
+| 美股基本信息 / 历史 | `get_us_stock_info` / `get_us_stock_history` | `GET /us/stock/info`, `/us/stock/history` |
+| 港股基本信息 / 历史 | `get_hk_stock_info` / `get_hk_stock_history` | `GET /hk/stock/info`, `/hk/stock/history` |
+| ETF 清单 | `get_etf_list` | `GET /cn/etfs/` |
+| ETF 基本信息 | `get_etf_info` | `GET /cn/etfs/info` |
+| ETF 申赎清单（PCF） | `get_etf_pcf` | `GET /cn/etfs/etf_pcf` |
+| ETF 成分股 | `get_etf_composition` | `GET /cn/etfs/etf_composition` |
+| ETF 历史净值/行情 | `get_etf_history` | `GET /cn/etf/history` |
+| 财经快讯 | `get_news_flash` | `GET /v2/news/flash` |
+| 快讯来源列表 | `get_news_flash_sources` | `GET /v2/news/flash/sources` |
+| 市场新闻列表 / 详情 | `get_market_news` / `get_market_news_detail` | `GET /cn/market/news`, `/cn/market/news/{id}` |
+| 恐惧与贪婪指数 | `get_fear_greed` | `GET /cn/market/fear_greed` |
+| 申万板块涨跌幅 | `get_sector_data` | `GET /cn/market/sector_data/{sw1,sw2,sw3}` |
+| 申万行业清单 | `get_sector_catalog` | `GET /cn/market/sector_catalog/{sw1,sw2,sw3}` |
+| 个股实时 Tick | `get_realtime` | `GET /cn/stock/tick` |
+| 全量 Tick 快照 | `get_tick_all` | `GET /cn/tick/tickall` |
+| 交易日历 | `get_trading_calendar` | `GET /cn/tick/trading_calendar` |
+| MCP 工具调用 | `call_mcp_tool` | `POST /mcp/call` |
+
+MCP 已暴露的工具：`get_stock_list`、`get_stock_detail`、`get_stock_history`、
+`get_index_history`、`get_financial_data`。
+
+### 旧方法名（已废弃，仍可用）
+
+从仓库内旧客户端迁移过来的方法名保留为别名，方便存量代码不改：
+`get_history` → `get_stock_history`、`get_market_sector` → `get_sector_data`、
+`get_company` → `get_company_profile`、`get_last_tick` → `get_realtime`、
+`get_market_fear_greed` → `get_fear_greed`。
+注意**出错语义已变**：旧版是「打印后返回 None」，现在是抛 `DataBullError`。
+
+## 版本
+
+版本号唯一源是 `databull/client.py` 的 `__version__`：
+
+```python
+import databull
+print(databull.__version__)
+```
+
+## 版权
+
+Copyright (c) 2025 yccheni@163.com. All rights reserved.

databull-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+databull/__init__.py,sha256=KNKY8qrMLKshuYel5ALMV4aT2jcgxj_Zylt_84NQO7s,654
+databull/__main__.py,sha256=8fA_BIfqseLEprmZXNQlABdO4a83qJDkvr5AYLmMwyQ,402
+databull/client.py,sha256=jkojNHO2nHZFoF5jngEBEhKQmTGGFguBsCX-iQysf2w,33257
+databull/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+databull-0.1.0.dist-info/METADATA,sha256=4cYhxxDE9RqRKOYLyCIB7qwjpZNXjxzrKvqw-Tqxnv4,8105
+databull-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+databull-0.1.0.dist-info/entry_points.txt,sha256=qdC5DqrA1Q_B2CPL770K__CrUfARex3jcuEhEqYkqfs,50
+databull-0.1.0.dist-info/top_level.txt,sha256=nmV0Xq_4UQq6kbG_O5B3LZ-cwXJNXjJXpKDK2XBv9lY,9
+databull-0.1.0.dist-info/RECORD,,

databull-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

databull-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+databull = databull.client:_cli

databull-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+databull