finclaw-data-sdk 0.1.3__tar.gz

finclaw_data_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: finclaw-data-sdk
+Version: 0.1.3
+Summary: A 股量化数据 HTTP 客户端（QuantClient），只依赖 pandas
+Author-email: dekeky <dekeky@163.com>
+Project-URL: Homepage, https://github.com/chocochato0713/finclaw-data
+Project-URL: Repository, https://github.com/chocochato0713/finclaw-data
+Keywords: finclaw,ashare,quant,kline,clickhouse
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+
+# finclaw-data-sdk
+
+A 股量化数据 HTTP 客户端。安装后 `from finclaw_data_sdk import QuantClient`，只依赖 pandas，不含拉取与 ClickHouse 业务代码。
+
+```bash
+pip install finclaw-data-sdk
+```
+
+```python
+from finclaw_data_sdk import QuantClient, cols
+
+c = QuantClient("http://127.0.0.1:8000")
+bars = c.kline(symbol="600519", start="20240801", end="20240805", adj="qfq")
+snap = c.snapshot(trade_date="20240819", symbols=["600519", "000001"], adj="qfq")
+df = c.fina(symbol="600519", start="20240101", end="20241231", fields=cols.fina.EPS_BASIC)
+idx = c.index_list()
+idx_bars = c.index_kline(index="000300", start="20240801", end="20240805", fields=cols.index_kline.CLOSE)
+cons = c.index_constituents(index="000300", fields=cols.index_constituents.SYMBOL)
+```
+
+日期参数为 `YYYYMMDD`，区间两端包含。需先启动本仓库的 `finclaw-data serve`。直连 ClickHouse 请安装服务包 `finclaw-data`，使用 `QuantClient.from_clickhouse()`。

finclaw_data_sdk-0.1.3/README.md

@@ -0,0 +1,21 @@
+# finclaw-data-sdk
+
+A 股量化数据 HTTP 客户端。安装后 `from finclaw_data_sdk import QuantClient`，只依赖 pandas，不含拉取与 ClickHouse 业务代码。
+
+```bash
+pip install finclaw-data-sdk
+```
+
+```python
+from finclaw_data_sdk import QuantClient, cols
+
+c = QuantClient("http://127.0.0.1:8000")
+bars = c.kline(symbol="600519", start="20240801", end="20240805", adj="qfq")
+snap = c.snapshot(trade_date="20240819", symbols=["600519", "000001"], adj="qfq")
+df = c.fina(symbol="600519", start="20240101", end="20241231", fields=cols.fina.EPS_BASIC)
+idx = c.index_list()
+idx_bars = c.index_kline(index="000300", start="20240801", end="20240805", fields=cols.index_kline.CLOSE)
+cons = c.index_constituents(index="000300", fields=cols.index_constituents.SYMBOL)
+```
+
+日期参数为 `YYYYMMDD`，区间两端包含。需先启动本仓库的 `finclaw-data serve`。直连 ClickHouse 请安装服务包 `finclaw-data`，使用 `QuantClient.from_clickhouse()`。

finclaw_data_sdk-0.1.3/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "finclaw-data-sdk"
+version = "0.1.3"
+description = "A 股量化数据 HTTP 客户端（QuantClient），只依赖 pandas"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "dekeky", email = "dekeky@163.com" },
+]
+dependencies = [
+    "pandas>=2.0",
+]
+keywords = ["finclaw", "ashare", "quant", "kline", "clickhouse"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+]
+[project.urls]
+Homepage = "https://github.com/chocochato0713/finclaw-data"
+Repository = "https://github.com/chocochato0713/finclaw-data"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["python"]
+include = ["finclaw_data_sdk*"]

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""A 股量化数据 HTTP SDK（不含拉取、存储等服务端业务）。"""
+
+from . import cols
+from .client import QuantClient, QuantClientError
+
+__version__ = "0.1.3"
+__all__ = ["QuantClient", "QuantClientError", "cols", "__version__"]

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk/client.py

@@ -0,0 +1,267 @@
+"""量化数据 HTTP 客户端。"""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+import pandas as pd
+
+
+def _to_ymd(value: str | date | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, date):
+        return value.strftime("%Y%m%d")
+    return str(value).replace("-", "")[:8]
+
+
+def _join_symbols(symbols: list[str] | str | None, symbol: str | None = None) -> str | None:
+    codes = symbols if symbols is not None else symbol
+    if codes is None:
+        return None
+    if isinstance(codes, list):
+        return ",".join(str(s).zfill(6) for s in codes)
+    return str(codes)
+
+
+class QuantClientError(RuntimeError):
+    pass
+
+
+class QuantClient:
+    """远程 HTTP 客户端。依赖仅 pandas，不导入服务端业务代码。"""
+
+    def __init__(self, base_url: str = "http://127.0.0.1:8000", timeout: float = 1800.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _get(self, path: str, **params: Any) -> dict[str, Any]:
+        query = {k: v for k, v in params.items() if v is not None and v != ""}
+        url = f"{self.base_url}{path}"
+        if query:
+            url = f"{url}?{urlencode(query)}"
+        req = Request(url, headers={"Accept": "application/json"})
+        try:
+            with urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise QuantClientError(f"HTTP {exc.code}: {body}") from exc
+        except URLError as exc:
+            raise QuantClientError(f"request failed: {exc}") from exc
+
+    @staticmethod
+    def _to_frame(body: dict[str, Any]) -> pd.DataFrame:
+        rows = body.get("rows") or []
+        return pd.DataFrame(rows)
+
+    def catalog(self) -> dict[str, Any]:
+        """库存目录：各表行数、标的数、日期覆盖。"""
+        return self._get("/v1/catalog")
+
+    def catalog_preview(
+        self,
+        dataset: str,
+        symbol: str | None = None,
+        index: str | None = None,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> pd.DataFrame:
+        """数据集分页预览，不走详情查询接口。"""
+        return self._to_frame(
+            self._get(
+                f"/v1/catalog/{dataset}/preview",
+                symbol=symbol,
+                index=index,
+                start=_to_ymd(start),
+                end=_to_ymd(end),
+                limit=limit,
+                offset=offset,
+            )
+        )
+
+    def stocks(
+        self,
+        listed: int | None = None,
+        symbol: str | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        return self._to_frame(
+            self._get("/v1/stocks", listed=listed, symbol=symbol, fields=fields, limit=limit)
+        )
+
+    def calendar(
+        self,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        trading_only: int = 1,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        return self._to_frame(
+            self._get(
+                "/v1/calendar",
+                start=_to_ymd(start),
+                end=_to_ymd(end),
+                trading_only=trading_only,
+                fields=fields,
+                limit=limit,
+            )
+        )
+
+    def kline(
+        self,
+        symbol: str | None = None,
+        symbols: list[str] | str | None = None,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        adj: str = "none",
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """时序日 K：单股或多股 + 日期区间。adj=none|qfq|hfq。不传 limit 则不限制行数。"""
+        params: dict[str, Any] = {
+            "start": _to_ymd(start),
+            "end": _to_ymd(end),
+            "adj": adj,
+            "fields": fields,
+        }
+        if limit is not None:
+            params["limit"] = limit
+        if symbols is not None:
+            params["symbols"] = _join_symbols(symbols)
+        else:
+            params["symbol"] = symbol
+        return self._to_frame(self._get("/v1/kline", **params))
+
+    def snapshot(
+        self,
+        trade_date: str | date,
+        symbols: list[str] | str | None = None,
+        adj: str = "none",
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """单日截面：不传 symbols 则全市场当日。"""
+        return self._to_frame(
+            self._get(
+                "/v1/snapshot",
+                trade_date=_to_ymd(trade_date),
+                symbols=_join_symbols(symbols),
+                adj=adj,
+                fields=fields,
+                limit=limit,
+            )
+        )
+
+    def fina(
+        self,
+        symbol: str | None = None,
+        symbols: list[str] | str | None = None,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        return self._to_frame(
+            self._get(
+                "/v1/fina",
+                symbol=symbol if symbols is None else None,
+                symbols=_join_symbols(symbols),
+                start=_to_ymd(start),
+                end=_to_ymd(end),
+                fields=fields,
+                limit=limit,
+            )
+        )
+
+    def adj_factor(
+        self,
+        symbol: str | None = None,
+        symbols: list[str] | str | None = None,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """除权/复权因子（ex_date, fore/back/adjust_factor）。"""
+        return self._to_frame(
+            self._get(
+                "/v1/adj-factor",
+                symbol=symbol if symbols is None else None,
+                symbols=_join_symbols(symbols),
+                start=_to_ymd(start),
+                end=_to_ymd(end),
+                fields=fields,
+                limit=limit,
+            )
+        )
+
+    def index_list(
+        self,
+        index: str | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """指数目录（index_meta）。"""
+        return self._to_frame(
+            self._get("/v1/index", index=index, fields=fields, limit=limit)
+        )
+
+    def index_kline(
+        self,
+        index: str | None = None,
+        indices: list[str] | str | None = None,
+        start: str | date | None = None,
+        end: str | date | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """指数日 K 时序。不传 limit 则不限制行数。"""
+        params: dict[str, Any] = {
+            "start": _to_ymd(start),
+            "end": _to_ymd(end),
+            "fields": fields,
+        }
+        if limit is not None:
+            params["limit"] = limit
+        if indices is not None:
+            params["indices"] = _join_symbols(indices)
+        else:
+            params["index"] = index
+        return self._to_frame(self._get("/v1/index/kline", **params))
+
+    def index_constituents(
+        self,
+        index: str,
+        date: str | date | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """指数成分股（asof 快照）。"""
+        return self._to_frame(
+            self._get(
+                "/v1/index/constituents",
+                index=index,
+                date=_to_ymd(date),
+                fields=fields,
+                limit=limit,
+            )
+        )
+
+    def indices(
+        self,
+        index: str | None = None,
+        fields: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """指数目录（`index_list` 别名）。"""
+        return self.index_list(index=index, fields=fields, limit=limit)

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk/cols.py

@@ -0,0 +1,116 @@
+"""各 `QuantClient` 方法返回的列名。
+
+用法::
+
+    from finclaw_data_sdk import QuantClient, cols
+
+    c.kline(..., fields=cols.kline.CLOSE)
+    c.fina(..., fields=cols.fina.EPS_BASIC)
+    c.index_kline(..., fields=cols.index_kline.CLOSE)
+    c.index_constituents(..., fields=cols.index_constituents.SYMBOL)
+"""
+
+
+class stocks:
+    """`stocks()` 股池。"""
+
+    SYMBOL = "symbol"  # 股票代码
+    EXCHANGE = "exchange"  # 交易所
+    NAME = "name"  # 简称
+    CODE = "code"  # Baostock 代码，如 sh.600519
+    IPO_DATE = "ipoDate"  # 上市日
+    OUT_DATE = "outDate"  # 退市日，在市为 None
+    TYPE = "type"  # 证券类型，1=股票
+    STATUS = "status"  # 上市状态，1=在市 0=退市
+
+
+class calendar:
+    """`calendar()` 交易日历。"""
+
+    TRADE_DATE = "trade_date"  # 日历日
+    IS_TRADING = "is_trading"  # 1=交易日 0=非交易日
+
+
+class kline:
+    """`kline()` 日 K 时序。`snapshot()` 列相同。"""
+
+    SYMBOL = "symbol"  # 股票代码
+    DATE = "date"  # 交易日
+    OPEN = "open"  # 开盘价
+    HIGH = "high"  # 最高价
+    LOW = "low"  # 最低价
+    CLOSE = "close"  # 收盘价
+    PRECLOSE = "preclose"  # 昨收
+    VOLUME = "volume"  # 成交量
+    AMOUNT = "amount"  # 成交额
+    TURN = "turn"  # 换手率（表字段 turnover）
+    PCT_CHG = "pct_chg"  # 涨跌幅
+    PE_TTM = "pe_ttm"  # 市盈率 TTM
+    PB_MRQ = "pb_mrq"  # 市净率 MRQ
+    PS_TTM = "ps_ttm"  # 市销率 TTM
+    PCF_NCF_TTM = "pcf_ncf_ttm"  # 市现率 TTM
+    TRADE_STATUS = "trade_status"  # 交易状态，1=正常
+    IS_ST = "is_st"  # 是否 ST
+    ADJ_TYPE = "adj_type"  # 复权类型 none|qfq|hfq
+
+
+class snapshot(kline):
+    """`snapshot()` 单日截面，列与 `kline` 相同。"""
+
+
+class fina:
+    """`fina()` 报告期累计财务指标。另有维度列 symbol / exchange / report_date / notice_date / season_label。"""
+
+    NOTICE_DATE = "notice_date"  # 公告日；回测应用 notice_date ≤ 交易日
+    EPS_BASIC = "eps_basic"  # 基本每股收益
+    BPS = "bps"  # 每股净资产
+    ROE_DILUTED = "roe_diluted"  # 加权净资产收益率（东财 ROEJQ；列名沿用）
+    ROA = "roa"  # 总资产净利率
+    GROSS_PROFIT_RATIO = "gross_profit_ratio"  # 销售毛利率
+    NET_PROFIT_RATIO = "net_profit_ratio"  # 销售净利率
+    TOTAL_OPERATE_REVENUE = "total_operate_revenue"  # 营业总收入
+    PARENT_NET_PROFIT = "parent_net_profit"  # 归母净利润
+    DEDU_PARENT_PROFIT = "dedu_parent_profit"  # 扣非归母净利润
+    REVENUE_YOY = "revenue_yoy"  # 营业总收入同比
+    PARENT_NET_PROFIT_YOY = "parent_net_profit_yoy"  # 归母净利润同比
+    REVENUE_QOQ = "revenue_qoq"  # 营业总收入环比
+    NET_PROFIT_QOQ = "net_profit_qoq"  # 净利润环比
+
+
+class adj_factor:
+    """`adj_factor()` 除权 / 复权因子。"""
+
+    SYMBOL = "symbol"  # 股票代码
+    EXCHANGE = "exchange"  # 交易所
+    EX_DATE = "ex_date"  # 除权除息日
+    FORE_ADJUST_FACTOR = "fore_adjust_factor"  # 前复权因子
+    BACK_ADJUST_FACTOR = "back_adjust_factor"  # 后复权因子
+    ADJUST_FACTOR = "adjust_factor"  # Baostock 原始调整因子
+
+
+class index_kline:
+    """`index_kline()` 指数日 K。无估值列、无复权。"""
+
+    INDEX_CODE = "index_code"  # 指数代码
+    EXCHANGE = "exchange"  # 交易所
+    DATE = "date"  # 交易日
+    OPEN = "open"  # 开盘
+    HIGH = "high"  # 最高
+    LOW = "low"  # 最低
+    CLOSE = "close"  # 收盘
+    PRECLOSE = "preclose"  # 昨收
+    VOLUME = "volume"  # 成交量
+    AMOUNT = "amount"  # 成交额
+    TURN = "turn"  # 换手率（表字段 turnover）
+    PCT_CHG = "pct_chg"  # 涨跌幅
+
+
+class index_constituents:
+    """`index_constituents()` 指数成分股 asof 快照。不含权重。"""
+
+    INDEX_CODE = "index_code"  # 指数代码
+    SNAPSHOT_DATE = "snapshot_date"  # 成分快照日
+    SYMBOL = "symbol"  # 成分股代码
+    EXCHANGE = "exchange"  # 交易所
+    NAME = "name"  # 成分股简称
+    SOURCE = "source"  # baostock 或 csindex

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: finclaw-data-sdk
+Version: 0.1.3
+Summary: A 股量化数据 HTTP 客户端（QuantClient），只依赖 pandas
+Author-email: dekeky <dekeky@163.com>
+Project-URL: Homepage, https://github.com/chocochato0713/finclaw-data
+Project-URL: Repository, https://github.com/chocochato0713/finclaw-data
+Keywords: finclaw,ashare,quant,kline,clickhouse
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+
+# finclaw-data-sdk
+
+A 股量化数据 HTTP 客户端。安装后 `from finclaw_data_sdk import QuantClient`，只依赖 pandas，不含拉取与 ClickHouse 业务代码。
+
+```bash
+pip install finclaw-data-sdk
+```
+
+```python
+from finclaw_data_sdk import QuantClient, cols
+
+c = QuantClient("http://127.0.0.1:8000")
+bars = c.kline(symbol="600519", start="20240801", end="20240805", adj="qfq")
+snap = c.snapshot(trade_date="20240819", symbols=["600519", "000001"], adj="qfq")
+df = c.fina(symbol="600519", start="20240101", end="20241231", fields=cols.fina.EPS_BASIC)
+idx = c.index_list()
+idx_bars = c.index_kline(index="000300", start="20240801", end="20240805", fields=cols.index_kline.CLOSE)
+cons = c.index_constituents(index="000300", fields=cols.index_constituents.SYMBOL)
+```
+
+日期参数为 `YYYYMMDD`，区间两端包含。需先启动本仓库的 `finclaw-data serve`。直连 ClickHouse 请安装服务包 `finclaw-data`，使用 `QuantClient.from_clickhouse()`。

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+python/finclaw_data_sdk/__init__.py
+python/finclaw_data_sdk/client.py
+python/finclaw_data_sdk/cols.py
+python/finclaw_data_sdk.egg-info/PKG-INFO
+python/finclaw_data_sdk.egg-info/SOURCES.txt
+python/finclaw_data_sdk.egg-info/dependency_links.txt
+python/finclaw_data_sdk.egg-info/requires.txt
+python/finclaw_data_sdk.egg-info/top_level.txt

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+pandas>=2.0

finclaw_data_sdk-0.1.3/python/finclaw_data_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+finclaw_data_sdk

finclaw_data_sdk-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+