stockroute 0.1.0__tar.gz

stockroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StockRoute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stockroute-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: stockroute
+Version: 0.1.0
+Summary: StockRoute 数据 API 官方 Python SDK(A 股行情/财务/资讯,DataFrame-first,PIT 点时财务)
+Author: StockRoute
+License: MIT
+Project-URL: Homepage, https://m-stock.600044.xyz
+Project-URL: Documentation, https://m-stock.600044.xyz
+Project-URL: Repository, https://github.com/Stock-Route/stockroute-sdk
+Keywords: A股,量化,数据,kline,financial,PIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# stockroute-sdk
+
+StockRoute 数据 API 官方 Python SDK(A 股行情 / 财务 / 资讯 / 元数据,统一 DataFrame-first 体验)。
+
+> ✅ v0.1.0 已发布(PyPI:`pip install stockroute`)
+
+```python
+from stockroute import StockRoute
+sr = StockRoute()                      # 读环境变量 STOCKROUTE_TOKEN
+df = sr.kline("600519")                # 日K:免费3年/基础5年/标准+全历史
+print(df.attrs["units"])               # 字段单位口径
+```
+
+## 计划特性
+- 覆盖 StockRoute 开放 API 全部端点:K线(多档历史深度)/ 点时财务(PIT 强制)/ 通用数据直查(60+ 数据集)/ 每日估值 / 全市场列表 / 快讯
+- **DataFrame-first**:返回 pandas DataFrame,单位口径(units)与档位信息自动挂载到 `attrs`
+- **类型化异常**:鉴权 / 档位不足 / 配额超限 / 服务限流分层清晰,报错即指引
+- 自动分页与限速友好(429 / Retry-After 自动处理)
+- 点时财务(PIT):`as_of` 参数强制显式,杜绝前视
+
+## 文档
+接口文档站:https://m-stock.600044.xyz
+
+## 许可
+MIT(见 LICENSE)
+
+---
+
+StockRoute · 面向量化研究者的 A 股数据质量层

stockroute-0.1.0/README.md

@@ -0,0 +1,29 @@
+# stockroute-sdk
+
+StockRoute 数据 API 官方 Python SDK(A 股行情 / 财务 / 资讯 / 元数据,统一 DataFrame-first 体验)。
+
+> ✅ v0.1.0 已发布(PyPI:`pip install stockroute`)
+
+```python
+from stockroute import StockRoute
+sr = StockRoute()                      # 读环境变量 STOCKROUTE_TOKEN
+df = sr.kline("600519")                # 日K:免费3年/基础5年/标准+全历史
+print(df.attrs["units"])               # 字段单位口径
+```
+
+## 计划特性
+- 覆盖 StockRoute 开放 API 全部端点:K线(多档历史深度)/ 点时财务(PIT 强制)/ 通用数据直查(60+ 数据集)/ 每日估值 / 全市场列表 / 快讯
+- **DataFrame-first**:返回 pandas DataFrame,单位口径(units)与档位信息自动挂载到 `attrs`
+- **类型化异常**:鉴权 / 档位不足 / 配额超限 / 服务限流分层清晰,报错即指引
+- 自动分页与限速友好(429 / Retry-After 自动处理)
+- 点时财务(PIT):`as_of` 参数强制显式,杜绝前视
+
+## 文档
+接口文档站:https://m-stock.600044.xyz
+
+## 许可
+MIT(见 LICENSE)
+
+---
+
+StockRoute · 面向量化研究者的 A 股数据质量层

stockroute-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stockroute"
+version = "0.1.0"
+description = "StockRoute 数据 API 官方 Python SDK(A 股行情/财务/资讯,DataFrame-first,PIT 点时财务)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "StockRoute"}]
+keywords = ["A股", "量化", "数据", "kline", "financial", "PIT"]
+dependencies = ["pandas>=1.5", "requests>=2.28"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+
+[project.urls]
+Homepage = "https://m-stock.600044.xyz"
+Documentation = "https://m-stock.600044.xyz"
+Repository = "https://github.com/Stock-Route/stockroute-sdk"

stockroute-0.1.0/setup.cfg

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

stockroute-0.1.0/src/stockroute/__init__.py

@@ -0,0 +1,17 @@
+"""StockRoute Python SDK——A 股数据(行情/财务/资讯/元数据)统一访问。
+
+快速开始:
+    from stockroute import StockRoute
+    sr = StockRoute()                      # 读环境变量 STOCKROUTE_TOKEN
+    df = sr.kline("600519")                # 近3年日K(档位越高历史越长)
+    df = sr.query("board.zt_pools")        # 通用数据直查
+    df.attrs["units"]                      # 字段单位口径
+"""
+
+from .client import StockRoute
+from .exceptions import (AuthError, NotFoundError, QuotaError, RateLimited,
+                         ServerError, StockRouteError, TierError)
+
+__version__ = "0.1.0"
+__all__ = ["StockRoute", "StockRouteError", "AuthError", "TierError",
+           "QuotaError", "RateLimited", "NotFoundError", "ServerError"]

stockroute-0.1.0/src/stockroute/client.py

@@ -0,0 +1,170 @@
+"""StockRoute 客户端:统一鉴权/重试/类型化异常/DataFrame-first。"""
+import os
+import time
+
+import pandas as pd
+import requests
+
+from .exceptions import (AuthError, NotFoundError, QuotaError, RateLimited,
+                         ServerError, TierError)
+
+DEFAULT_BASE = "https://api-stock.600044.xyz"
+
+
+def _parse_detail(body) -> str:
+    if isinstance(body, dict):
+        for k in ("detail", "message"):
+            if body.get(k):
+                return str(body[k])
+    return str(body)[:300]
+
+
+class StockRoute:
+    """StockRoute 数据 API 客户端。
+
+    token: 访问令牌(门户「Token」页签发);缺省读环境变量 STOCKROUTE_TOKEN。
+    base:  API 地址,默认公网入口,一般无需修改。
+    """
+
+    def __init__(self, token: str = None, base: str = None, timeout: int = 30, retries: int = 2):
+        self.token = token or os.environ.get("STOCKROUTE_TOKEN")
+        if not self.token:
+            raise AuthError("缺少 token:构造传参,或设置环境变量 STOCKROUTE_TOKEN")
+        self.base = (base or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+        self.retries = retries
+        self._sess = requests.Session()
+        self._sess.headers.update({"Authorization": f"Bearer {self.token}",
+                                   "Accept": "application/json"})
+
+    # ── 底层 ──
+    def _get(self, path: str, params: dict = None) -> dict:
+        """GET + 自动重试(502/503/网络抖动)+ 类型化异常。200 → JSON dict。"""
+        url = self.base + path
+        r = None
+        for i in range(self.retries + 1):
+            try:
+                r = self._sess.get(url, params=params or {}, timeout=self.timeout)
+            except requests.RequestException as e:
+                if i < self.retries:
+                    time.sleep(0.5 * (i + 1))
+                    continue
+                raise ServerError(f"网络错误: {e}", status=0)
+            if r.status_code in (502, 503) and i < self.retries:
+                time.sleep(0.5 * (i + 1))
+                continue
+            break
+        if r.status_code == 200:
+            return r.json()
+        detail = _parse_detail_body(r)
+        if r.status_code == 401:
+            raise AuthError(detail)
+        if r.status_code == 403 and "tier below min_points" in detail:
+            have, need = _extract_have_need(detail)
+            raise TierError(f"档位不足:需 {need} 分,当前 {have} 分。到门户「充值」页升级",
+                            have=have, need=need)
+        if r.status_code == 403 and "exceeded" in detail:
+            raise QuotaError(detail)
+        if r.status_code == 429:
+            raise RateLimited(detail, retry_after=int(r.headers.get("Retry-After", "60")))
+        if r.status_code == 404:
+            raise NotFoundError(detail)
+        raise ServerError(f"HTTP {r.status_code}: {detail}", status=r.status_code)
+
+    @staticmethod
+    def _to_df(payload: dict) -> pd.DataFrame:
+        """rows → DataFrame;units/count/total 等挂 attrs(与数据一起自然传递)。"""
+        df = pd.DataFrame(payload.get("rows") or [])
+        df.attrs["units"] = payload.get("units") or {}
+        df.attrs["count"] = payload.get("count")
+        df.attrs["total"] = payload.get("total")
+        df.attrs["raw"] = {k: v for k, v in payload.items() if k != "rows"}
+        return df
+
+    # ── 数据端点 ──
+    def kline(self, code: str, start: str = None, end: str = None) -> pd.DataFrame:
+        """个股日 K(OHLCV/涨跌幅/复权/ST/估值尾列)。
+        历史深度按档位:免费3年 / 基础5年 / 标准及以上全历史。"""
+        p = self._get("/api/kline", _clean(code=code, start=start, end=end))
+        return self._to_df(p)
+
+    def financial(self, code: str, kind: str, as_of: str) -> pd.DataFrame:
+        """点时财务(PIT 强制):只返回公告日严格早于 as_of 的记录,杜绝前视。
+        kind: profit/growth/balance/cashflow/dividend/forecast/express/dupont"""
+        p = self._get("/api/financial", _clean(code=code, kind=kind, as_of=as_of))
+        df = self._to_df(p)
+        df.attrs["pit_rule"] = p.get("pit_rule")
+        return df
+
+    def daily_basic(self, code: str, date: str = None) -> pd.DataFrame:
+        """单股每日估值全套(PE/PB/股息率/换手/市值)。date 缺省=最新。"""
+        p = self._get("/api/daily_basic", _clean(code=code, date=date))
+        return self._to_df(p)
+
+    def query(self, dataset: str, code: str = None, start: str = None,
+              end: str = None, limit: int = None) -> pd.DataFrame:
+        """通用数据直查(60+ 数据集)。可选集见 self.datasets() 或接口文档。
+        无过滤参数时返回最新一个日期切片;行数按档位封顶。"""
+        p = self._get("/api/query", _clean(dataset=dataset, code=code,
+                                           start=start, end=end, limit=limit))
+        return self._to_df(p)
+
+    def stocks(self, status: str = "L", industry: str = None, keyword: str = None,
+               limit: int = 1000, offset: int = 0, paginate: bool = False) -> pd.DataFrame:
+        """全 A 股列表(代码/名称/行业分类/上市退市日)。
+        paginate=True 自动翻页拉全量(total≈3800)。"""
+        out = []
+        off = offset
+        while True:
+            p = self._get("/api/meta/stocks", _clean(status=status, industry=industry,
+                                                     keyword=keyword, limit=limit, offset=off))
+            rows = p.get("rows") or []
+            out.extend(rows)
+            total = p.get("total")
+            off += len(rows)
+            if not paginate or not rows or (total is not None and off >= total):
+                break
+        df = pd.DataFrame(out)
+        df.attrs["total"] = total
+        df.attrs["raw"] = {"offset": offset, "limit": limit, "paginate": paginate}
+        return df
+
+    def news(self, since: str = None, code: str = None, keyword: str = None,
+             cat: str = None, src: str = None, limit: int = None) -> pd.DataFrame:
+        """全市场快讯(增量游标 since=上次最新 ts;支持按股/关键词/类别)。"""
+        p = self._get("/api/news", _clean(since=since, code=code, keyword=keyword,
+                                          cat=cat, src=src, limit=limit))
+        df = self._to_df(p)
+        if len(df):
+            df.attrs["last_ts"] = df.iloc[0].get("ts")   # 增量游标:下次作 since
+        return df
+
+    # ── 元数据 ──
+    def datasets(self) -> dict:
+        """数据集契约字典(units/SLA/min_points/PIT 规则),按当前档位过滤。"""
+        return self._get("/api/datasets")
+
+
+def _clean(**kw) -> dict:
+    """去 None 参数。"""
+    return {k: v for k, v in kw.items() if v is not None}
+
+
+def _parse_detail_body(r) -> str:
+    try:
+        body = r.json()
+    except Exception:
+        return (r.text or "")[:300]
+    if isinstance(body, dict):
+        for k in ("detail", "message"):
+            if body.get(k):
+                return str(body[k])
+    return str(body)[:300]
+
+
+def _extract_have_need(detail: str):
+    import re
+    m_have = re.search(r"have (\d+)pts", detail)
+    m_need = re.search(r"need (\d+)", detail)
+    return (int(m_have.group(1)) if m_have else None,
+            int(m_need.group(1)) if m_need else None)

stockroute-0.1.0/src/stockroute/exceptions.py

@@ -0,0 +1,48 @@
+"""StockRoute SDK 异常类型——按错误语义分层,报错即指引。"""
+
+
+class StockRouteError(Exception):
+    """所有 StockRoute 异常的基类。"""
+
+
+class AuthError(StockRouteError):
+    """401:Token 缺失/无效/已吊销。到门户「Token」页重签。"""
+
+
+class TierError(StockRouteError):
+    """403:当前档位不足以访问该数据集。
+
+    属性:
+        have: 当前累计积分
+        need: 该数据集所需积分
+    """
+
+    def __init__(self, message: str, have=None, need=None):
+        super().__init__(message)
+        self.have = have
+        self.need = need
+
+
+class QuotaError(StockRouteError):
+    """403/429:配额超限(月点数/月行数/日点数/日行数/月次数)。
+    message 内含具体额度;日/月配额自然周期重置。"""
+
+
+class RateLimited(StockRouteError):
+    """429:触发档位限速。建议按 retry_after 秒后重试。"""
+
+    def __init__(self, message: str, retry_after: int = 60):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class NotFoundError(StockRouteError):
+    """404:无数据(代码/日期窗口无匹配)或数据集不可直查。"""
+
+
+class ServerError(StockRouteError):
+    """5xx:服务端错误/权限服务不可达(fail-closed)。SDK 已自动重试,建议稍后再试。"""
+
+    def __init__(self, message: str, status: int = 500):
+        super().__init__(message)
+        self.status = status

stockroute-0.1.0/src/stockroute.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: stockroute
+Version: 0.1.0
+Summary: StockRoute 数据 API 官方 Python SDK(A 股行情/财务/资讯,DataFrame-first,PIT 点时财务)
+Author: StockRoute
+License: MIT
+Project-URL: Homepage, https://m-stock.600044.xyz
+Project-URL: Documentation, https://m-stock.600044.xyz
+Project-URL: Repository, https://github.com/Stock-Route/stockroute-sdk
+Keywords: A股,量化,数据,kline,financial,PIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# stockroute-sdk
+
+StockRoute 数据 API 官方 Python SDK(A 股行情 / 财务 / 资讯 / 元数据,统一 DataFrame-first 体验)。
+
+> ✅ v0.1.0 已发布(PyPI:`pip install stockroute`)
+
+```python
+from stockroute import StockRoute
+sr = StockRoute()                      # 读环境变量 STOCKROUTE_TOKEN
+df = sr.kline("600519")                # 日K:免费3年/基础5年/标准+全历史
+print(df.attrs["units"])               # 字段单位口径
+```
+
+## 计划特性
+- 覆盖 StockRoute 开放 API 全部端点:K线(多档历史深度)/ 点时财务(PIT 强制)/ 通用数据直查(60+ 数据集)/ 每日估值 / 全市场列表 / 快讯
+- **DataFrame-first**:返回 pandas DataFrame,单位口径(units)与档位信息自动挂载到 `attrs`
+- **类型化异常**:鉴权 / 档位不足 / 配额超限 / 服务限流分层清晰,报错即指引
+- 自动分页与限速友好(429 / Retry-After 自动处理)
+- 点时财务(PIT):`as_of` 参数强制显式,杜绝前视
+
+## 文档
+接口文档站:https://m-stock.600044.xyz
+
+## 许可
+MIT(见 LICENSE)
+
+---
+
+StockRoute · 面向量化研究者的 A 股数据质量层

stockroute-0.1.0/src/stockroute.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/stockroute/__init__.py
+src/stockroute/client.py
+src/stockroute/exceptions.py
+src/stockroute.egg-info/PKG-INFO
+src/stockroute.egg-info/SOURCES.txt
+src/stockroute.egg-info/dependency_links.txt
+src/stockroute.egg-info/requires.txt
+src/stockroute.egg-info/top_level.txt
+tests/test_smoke.py

stockroute-0.1.0/src/stockroute.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stockroute-0.1.0/src/stockroute.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pandas>=1.5
+requests>=2.28

stockroute-0.1.0/src/stockroute.egg-info/top_level.txt

@@ -0,0 +1 @@
+stockroute

stockroute-0.1.0/tests/test_smoke.py

@@ -0,0 +1,19 @@
+"""冒烟:未联网部分(异常层级/参数清洗)。真实调用见 examples/。"""
+from stockroute import (AuthError, NotFoundError, QuotaError, RateLimited,
+                        ServerError, StockRoute, StockRouteError, TierError)
+from stockroute.client import _clean
+
+
+def test_exception_hierarchy():
+    assert issubclass(TierError, StockRouteError)
+    assert issubclass(QuotaError, StockRouteError)
+    assert issubclass(RateLimited, StockRouteError)
+
+
+def test_tier_error_attrs():
+    e = TierError("需 5000 分,当前 1000 分", have=1000, need=5000)
+    assert e.have == 1000 and e.need == 5000
+
+
+def test_clean_drops_none():
+    assert _clean(a=1, b=None) == {"a": 1}