databull 0.1.2__tar.gz → 0.1.4__tar.gz

{databull-0.1.2 → databull-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databull
-Version: 0.1.2
+Version: 0.1.4
 Summary: DataBull 中国 A 股市场数据 API 的 Python SDK（行情、财务、ETF、指数、板块、快讯）
 Author-email: Yc <yccheni@163.com>
 Project-URL: Homepage, https://www.databull.cn
@@ -42,7 +42,7 @@ pip install "databull[pandas]"    # 需要 *_history / fear_greed 返回 DataFra
 国内直连 PyPI 慢时，可从官网下载 wheel 安装：
 
 ```bash
-pip install https://www.databull.cn/sdk/files/databull-0.1.2-py3-none-any.whl
+pip install https://www.databull.cn/sdk/files/databull-0.1.4-py3-none-any.whl
 ```
 
 ## 快速开始
@@ -125,6 +125,9 @@ if not data["data"]["items"]:
 | 指数清单（分页/过滤） | `get_index_list` | `GET /cn/index/list` |
 | 指数搜索（相关度排序） | `search_index` | `GET /cn/index/search` |
 | 指数成分股与权重 | `get_index_constituents` | `GET /cn/index/constituents` |
+| 美股指数历史行情（日/周/月线） | `get_us_index_history` | `GET /us/index/history` |
+| 美股指数清单（分页/过滤） | `get_us_index_list` | `GET /us/index/list` |
+| 美股指数搜索（相关度排序） | `search_us_index` | `GET /us/index/search` |
 | A股/ETF/指数标的清单 | `get_stock_list` | `GET /cn/stocks` |
 | 个股基本信息 | `get_stock_info` | `GET /cn/stock/info` |
 | 公司简介 | `get_company_profile` | `GET /cn/stock/profile` |
@@ -144,7 +147,6 @@ if not data["data"]["items"]:
 | 申万板块涨跌幅 | `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` |
 

{databull-0.1.2 → databull-0.1.4}/README.md

@@ -17,7 +17,7 @@ pip install "databull[pandas]"    # 需要 *_history / fear_greed 返回 DataFra
 国内直连 PyPI 慢时，可从官网下载 wheel 安装：
 
 ```bash
-pip install https://www.databull.cn/sdk/files/databull-0.1.2-py3-none-any.whl
+pip install https://www.databull.cn/sdk/files/databull-0.1.4-py3-none-any.whl
 ```
 
 ## 快速开始
@@ -100,6 +100,9 @@ if not data["data"]["items"]:
 | 指数清单（分页/过滤） | `get_index_list` | `GET /cn/index/list` |
 | 指数搜索（相关度排序） | `search_index` | `GET /cn/index/search` |
 | 指数成分股与权重 | `get_index_constituents` | `GET /cn/index/constituents` |
+| 美股指数历史行情（日/周/月线） | `get_us_index_history` | `GET /us/index/history` |
+| 美股指数清单（分页/过滤） | `get_us_index_list` | `GET /us/index/list` |
+| 美股指数搜索（相关度排序） | `search_us_index` | `GET /us/index/search` |
 | A股/ETF/指数标的清单 | `get_stock_list` | `GET /cn/stocks` |
 | 个股基本信息 | `get_stock_info` | `GET /cn/stock/info` |
 | 公司简介 | `get_company_profile` | `GET /cn/stock/profile` |
@@ -119,7 +122,6 @@ if not data["data"]["items"]:
 | 申万板块涨跌幅 | `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` |
 

{databull-0.1.2 → databull-0.1.4}/client.py

@@ -44,7 +44,7 @@ from urllib3.util.retry import Retry
 
 #: SDK 版本。**唯一源**：pyproject.toml 通过 dynamic 从本属性读取，
 #: 不要再在别处硬编码版本号（testcase/test_databull_sdk.py 会校验一致性）。
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = ["DataBull", "DataBullError", "__version__"]
 
@@ -490,7 +490,11 @@ class DataBull:
         end_date: str,
         report_type: str = "Balance",
     ):
-        """个股财报：report_type ∈ Balance/Income/CashFlow/Capital。"""
+        """个股财报：report_type ∈ Balance/Income/CashFlow/PershareIndex。
+
+        取值必须与库中完全一致（区分大小写）。传其他值会得到空数组 +
+        X-Empty-Reason: no_data_in_range（库里没有该类型的数据）。
+        """
         return self._request(
             "cn/stock/financial_data",
             params={
@@ -502,6 +506,54 @@ class DataBull:
         )
 
     # -------------------------- 美股 / 港股 --------------------------
+    def get_us_stock_list(
+        self,
+        q: Optional[str] = None,
+        exchange: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 100,
+    ):
+        """美股股票列表（分页，按代码稳定排序）。
+
+        :param q: 搜索关键词，模糊匹配代码或名称（英文）；留空返回全量
+        :param exchange: 交易所过滤 NYSE / NASDAQ / AMEX；留空不过滤
+        :param page: 页码，从 1 开始
+        :param page_size: 每页条数，1~500
+        :return: {'code': 0, 'data': {'items': [...], 'total': N, 'page': p, 'page_size': n, 'has_more': bool}}
+        """
+        params: Dict[str, Any] = {}
+        if q:
+            params["q"] = q
+        if exchange:
+            params["exchange"] = exchange
+        params["page"] = page
+        params["page_size"] = page_size
+        return self._request("us/stocks", params=params)
+
+    def get_hk_stock_list(
+        self,
+        q: Optional[str] = None,
+        exchange: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 100,
+    ):
+        """港股股票列表（分页，按代码稳定排序）。
+
+        :param q: 搜索关键词，模糊匹配代码或名称（英文）；留空返回全量
+        :param exchange: 交易所过滤 hkex；留空不过滤
+        :param page: 页码，从 1 开始
+        :param page_size: 每页条数，1~500
+        :return: {'code': 0, 'data': {'items': [...], 'total': N, 'page': p, 'page_size': n, 'has_more': bool}}
+        """
+        params: Dict[str, Any] = {}
+        if q:
+            params["q"] = q
+        if exchange:
+            params["exchange"] = exchange
+        params["page"] = page
+        params["page_size"] = page_size
+        return self._request("hk/stocks", params=params)
+
     def get_us_stock_info(self, symbol: str):
         """美股个股基本信息。"""
         return self._request("us/stock/info", params={"symbol": symbol})
@@ -542,6 +594,122 @@ class DataBull:
         )
         return self._to_dataframe(data.get("data") if isinstance(data, dict) else data)
 
+    # -------------------------- 美股指数 --------------------------
+    def get_us_index_history(
+        self,
+        index_code: str = "I:SPX",
+        start_date: str = "",
+        end_date: str = "",
+        period: str = "d",
+        as_dataframe: bool = True,
+    ):
+        """美股指数历史行情（标普500 / 纳斯达克100 / 道琼斯等），支持日线 / 周线 / 月线。
+
+        :param index_code: 指数代码，两种写法都接受——清单代码（``I:SPX``，与
+            :meth:`get_us_index_list` 返回的一致）或等价简称（``GSPC``）。
+            带 ``.INDX`` 后缀（``GSPC.INDX``）会被自动剥离
+        :param start_date: 起始日，YYYY-MM-DD / YYYYMMDD 都可以；留空默认近 1 年
+        :param end_date: 结束日，同上；留空默认当日
+        :param period: K 线周期，``d`` 日线 / ``w`` 周线 / ``m`` 月线
+        :param as_dataframe: True 返回 DataFrame，False 返回原始 dict
+        :return: 默认带日期索引的 DataFrame；``as_dataframe=False`` 时返回
+            ``{'code': 0, 'data': {'index': {...}, 'period': 'd', 'count': N,
+            'items': [...], 'data_scope': 'local'|'realtime'}}``
+
+        可用代码：``GSPC`` 标普500、``NDX`` 纳斯达克100、``IXIC`` 纳斯达克综合、
+        ``DJI`` 道琼斯工业、``NYA`` 纽交所综合、``XAX`` 美国交易所综合、
+        ``SP400`` 标普中盘400、``SPXTR`` 标普500全收益、``OEX`` 标普100、
+        ``VIX`` 波动率指数、``DJT`` 道琼斯运输。传入其他代码会返回 404。
+
+        .. note::
+            指数没有「成交额」概念，``amount`` 恒为 0；``change_amount`` /
+            ``chg_pct`` / ``amplitude`` 由相邻两根 K 线派生，区间第一根为 0。
+        """
+        payload = self._request(
+            "us/index/history",
+            params={
+                "index_code": index_code,
+                "start_date": start_date,
+                "end_date": end_date,
+                "period": period,
+            },
+        )
+        if not as_dataframe:
+            return payload
+        # data 可能是对象（正常）或列表/空（异常响应、空结果），
+        # 这里只认对象形态，取不到 items 就当空，绝不因结构不符而抛异常
+        data = payload.get("data") if isinstance(payload, dict) else None
+        items = data.get("items", []) if isinstance(data, dict) else []
+        return self._to_dataframe(items)
+
+    def get_us_index_list(
+        self,
+        q: Optional[str] = None,
+        category: Optional[str] = None,
+        quote_ready_only: bool = False,
+        page: int = 1,
+        page_size: int = 100,
+    ):
+        """美股指数清单（分页，按代码稳定排序）。
+
+        :param q: 关键词，模糊匹配代码或名称；留空返回全量
+        :param category: 分类过滤，``broad`` 宽基 / ``total_return`` 全收益 /
+            ``exchange`` 交易所 / ``volatility`` 波动率；留空不过滤
+        :param quote_ready_only: 只返回行情已验证可取的指数
+        :param page: 页码，从 1 开始
+        :param page_size: 每页条数，1~500
+        :return: ``{'code': 0, 'data': {'items': [...], 'total': N, 'page': p,
+            'page_size': n, 'pages': k}}``；空结果额外带 ``empty_reason``
+            （catalog_not_synced / no_match / page_out_of_range）
+
+        .. warning::
+            **清单收录 ≠ 行情可取**。清单有 1.3 万条指数，但只有十来个能真正取到
+            行情。每条的 ``quote_ready`` 字段标记行情是否可用（1 可用），
+            ``quote_symbol`` 是行情查询代码。用 :meth:`get_us_index_history`
+            前建议先看这两个字段，或直接传 ``quote_ready_only=True``。
+        """
+        params: Dict[str, Any] = {
+            "page": page,
+            "page_size": page_size,
+            "quote_ready_only": str(bool(quote_ready_only)).lower(),
+        }
+        if q:
+            params["q"] = q
+        if category:
+            params["category"] = category
+        return self._request("us/index/list", params=params)
+
+    def search_us_index(
+        self,
+        keyword: str,
+        limit: int = 20,
+        category: Optional[str] = None,
+        quote_ready_only: bool = False,
+    ):
+        """按关键词搜索美股指数，按匹配相关度排序（适合输入框实时联想）。
+
+        相关度：代码完全相等 > 代码后缀相等 > 代码前缀 > 名称完全相等 >
+        名称前缀 > 名称包含。同时匹配清单代码（``I:SPX``）、简称（``GSPC``）与名称。
+
+        :param keyword: 搜索关键词（必填）
+        :param limit: 返回条数上限，1~100
+        :param category: 分类过滤 broad / total_return / exchange / volatility
+        :param quote_ready_only: 只返回行情已验证可取的指数
+        :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,
+            "quote_ready_only": str(bool(quote_ready_only)).lower(),
+        }
+        if category:
+            params["category"] = category
+        return self._request("us/index/search", params=params)
+
     # -------------------------- ETF --------------------------
     def get_etf_list(
         self,
@@ -635,14 +803,6 @@ class DataBull:
             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",

{databull-0.1.2 → databull-0.1.4}/databull.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databull
-Version: 0.1.2
+Version: 0.1.4
 Summary: DataBull 中国 A 股市场数据 API 的 Python SDK（行情、财务、ETF、指数、板块、快讯）
 Author-email: Yc <yccheni@163.com>
 Project-URL: Homepage, https://www.databull.cn
@@ -42,7 +42,7 @@ pip install "databull[pandas]"    # 需要 *_history / fear_greed 返回 DataFra
 国内直连 PyPI 慢时，可从官网下载 wheel 安装：
 
 ```bash
-pip install https://www.databull.cn/sdk/files/databull-0.1.2-py3-none-any.whl
+pip install https://www.databull.cn/sdk/files/databull-0.1.4-py3-none-any.whl
 ```
 
 ## 快速开始
@@ -125,6 +125,9 @@ if not data["data"]["items"]:
 | 指数清单（分页/过滤） | `get_index_list` | `GET /cn/index/list` |
 | 指数搜索（相关度排序） | `search_index` | `GET /cn/index/search` |
 | 指数成分股与权重 | `get_index_constituents` | `GET /cn/index/constituents` |
+| 美股指数历史行情（日/周/月线） | `get_us_index_history` | `GET /us/index/history` |
+| 美股指数清单（分页/过滤） | `get_us_index_list` | `GET /us/index/list` |
+| 美股指数搜索（相关度排序） | `search_us_index` | `GET /us/index/search` |
 | A股/ETF/指数标的清单 | `get_stock_list` | `GET /cn/stocks` |
 | 个股基本信息 | `get_stock_info` | `GET /cn/stock/info` |
 | 公司简介 | `get_company_profile` | `GET /cn/stock/profile` |
@@ -144,7 +147,6 @@ if not data["data"]["items"]:
 | 申万板块涨跌幅 | `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` |