ashareapi 0.1.0__py3-none-any.whl

ashareapi/__init__.py

@@ -0,0 +1,18 @@
+"""A股数据 API 官方 Python SDK
+
+>>> from ashareapi import AShareAPI
+>>> cli = AShareAPI()                 # 免费端点（quote/kline/hot/market-overview/changedist）无需 Key
+>>> cli.quote("sh600667")
+
+>>> cli = AShareAPI("ct-你的Key")      # 付费端点需 Key（也读环境变量 ASHARE_API_KEY）
+>>> cli.screen(preset="low_pe", limit=10)
+
+文档：https://ashareapi.com/docs  ·  端点清单：https://ashareapi.com/endpoints
+"""
+from .client import AShareAPI
+from .errors import (AShareError, APIError, AuthError, EmptyResultError, RateLimitError,
+                     UpstreamError)
+
+__version__ = "0.1.0"
+__all__ = ["AShareAPI", "AShareError", "AuthError", "RateLimitError", "EmptyResultError",
+           "UpstreamError", "APIError", "__version__"]

ashareapi/_code.py

@@ -0,0 +1,41 @@
+"""股票代码格式归一化 —— 兼容多种写法，统一成 API 原生格式（sh600667）
+
+支持：
+    sh600667      原生（沪）
+    sz000001      原生（深）
+    600667.SH     通用后缀风格（市场后缀）
+    000001.SZ     通用后缀风格
+    600667        纯 6 位（按首位推断：5/6→沪 0/3→深 4/8→北）
+    hk00700 / usAAPL  原样返回（前缀小写化）
+"""
+from __future__ import annotations
+
+import re
+
+_SUFFIX = re.compile(r"^(\d{6})\.(SH|SZ|BJ)$", re.I)
+_PREFIX = re.compile(r"^(SH|SZ|BJ|HK|US)(.+)$", re.I)
+_BARE = re.compile(r"^\d{6}$")
+
+
+def normalize_code(code: str) -> str:
+    """把各种代码写法统一成 API 原生格式；认不出来就原样返回（让 API 报错，不猜）"""
+    c = (code or "").strip()
+    if not c:
+        return c
+
+    m = _SUFFIX.match(c)                       # 600667.SH → sh600667
+    if m:
+        return m.group(2).lower() + m.group(1)
+
+    m = _PREFIX.match(c)                       # SH600667 → sh600667（前缀小写，后缀原样）
+    if m:
+        return m.group(1).lower() + m.group(2)
+
+    if _BARE.match(c):                         # 纯 6 位 → 按首位推断市场
+        if c[0] in "56":
+            return "sh" + c
+        if c[0] in "03":
+            return "sz" + c
+        if c[0] in "48":
+            return "bj" + c
+    return c

ashareapi/client.py

@@ -0,0 +1,238 @@
+"""核心客户端（M1 MVP）—— 认证 / 请求 / 重试 / 信封解析 / 端点方法"""
+from __future__ import annotations
+
+import os
+import time
+
+import requests
+
+from ._code import normalize_code
+from .errors import APIError, AuthError, EmptyResultError, RateLimitError, UpstreamError
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE = "https://api.ashareapi.com"
+FREE_ENDPOINTS = (
+    "/v1/quote", "/v1/kline", "/v1/hot", "/v1/market-overview", "/v1/changedist",  # 5 个数据端点
+    "/v1/health", "/v1/challenge",                                                # 2 个工具端点（实测匿名 200）
+)
+
+
+class AShareAPI:
+    """A股数据 API 客户端
+
+    :param api_key: API Key（默认读环境变量 ``ASHARE_API_KEY``；**免费端点可不传**）
+    :param base_url: 服务地址（默认官方 ``https://api.ashareapi.com``）
+    :param timeout: 单请求超时（秒）
+    :param retries: ``429``/``5xx``/网络错误的**重试次数**（指数退避 0.5s/1.5s/4s）
+    :param raw: ``True`` → 返回**原始信封** dict（含 ``endpoint/tier/elapsed_ms/source``），不转 DataFrame
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str = DEFAULT_BASE,
+                 timeout: int = 30, retries: int = 3, raw: bool = False):
+        self.api_key = (api_key or os.environ.get("ASHARE_API_KEY", "") or "").strip()
+        self.base_url = (base_url or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+        self.retries = max(1, int(retries))
+        self.raw = raw
+
+    # ── 内部 ──────────────────────────────────────────────
+    def _request(self, path: str, **params) -> dict:
+        params = {k: v for k, v in params.items() if v not in (None, "")}
+        headers = {"User-Agent": "ashareapi-python/%s" % __version__}
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+        elif path not in FREE_ENDPOINTS:
+            raise AuthError(
+                "端点 %s 需要 API Key（免 Key 端点：%s）。获取：https://ashareapi.com/pricing"
+                % (path, " / ".join(FREE_ENDPOINTS)))
+        last_err = None
+        for i in range(self.retries):
+            try:
+                r = requests.get(self.base_url + path, params=params, headers=headers,
+                                 timeout=self.timeout)
+            except requests.RequestException as e:
+                last_err = APIError("网络错误：%r" % (e,))
+                time.sleep(0.5 * (3 ** i))
+                continue
+            if r.status_code == 401:
+                raise AuthError("Key 无效或未携带（401）—— 检查 ASHARE_API_KEY")
+            if r.status_code == 429:
+                last_err = RateLimitError(
+                    "超频（429）：降频重试；或解一次 PoW 挑战提额到 60 次/分"
+                    "（GET /v1/challenge）；或升级档位")
+                time.sleep(0.5 * (3 ** i))
+                continue
+            if r.status_code >= 500:
+                last_err = APIError("服务端 %s" % r.status_code)
+                time.sleep(0.5 * (3 ** i))
+                continue
+            try:
+                body = r.json()
+            except ValueError:
+                raise APIError("响应不是 JSON（HTTP %s）：%s" % (r.status_code, r.text[:120]))
+            # 只有**显式** ok=false 才算上游失败（已自动换源且不扣次数）→ 重试无意义
+            # （health / challenge 等工具端点不走统一信封、没有 ok 字段 → 不能误判）
+            if body.get("ok") is False:
+                data = body.get("data")
+                # 空容器 = "当前无数据"（如当天无大宗交易）→ 与"取数失败"区分开
+                if data is None or data == [] or data == {}:
+                    raise EmptyResultError(
+                        "当前无数据（非失败）：%s —— 不计费，稍后重试或换条件"
+                        % body.get("endpoint", path))
+                raise UpstreamError(str(data or "上游取数失败（已自动换源，重试一次通常可好）"))
+            return body
+        raise last_err or APIError("重试 %d 次仍失败" % self.retries)
+
+    def _frame(self, body: dict):
+        """统一信封 → ``pandas.DataFrame``（未装 pandas 则退回 ``list[dict]``）
+
+        2026-09-23 实测：部分端点 ``data`` 直接是数组，部分是 Markdown 但都带 **``structured``**
+        结构化数组 → 这里**零 Markdown 解析** ✓
+        """
+        if self.raw:
+            return body
+        rows = body.get("structured")
+        if rows is None and isinstance(body.get("data"), list):
+            rows = body["data"]
+        if rows is None:
+            return body.get("data", body)      # 无表格字段（health / challenge / usage）→ 返回整个信封
+        try:
+            import pandas as pd
+            return pd.DataFrame(rows)
+        except ImportError:
+            return rows                        # 未装 pandas 同样可用
+
+    def _get(self, path: str, **params):
+        return self._frame(self._request(path, **params))
+
+    # ── 端点方法（30 个 —— 签名对齐 /openapi.json）─────────────────────
+    # 【基础 / 工具】
+    def health(self):
+        """服务健康检查（数据源就绪状态）"""
+        return self._get("/v1/health")
+
+    def usage(self):
+        """查询自身用量与额度"""
+        return self._get("/v1/usage")
+
+    def challenge(self, difficulty: int = 0):
+        """获取 PoW 挑战（**匿名提额**：解出后单次请求带 ``X-PoW`` 头，额度 5/分 → 60/分）"""
+        return self._get("/v1/challenge", difficulty=difficulty)
+
+    # 【行情】
+    def quote(self, code: str):
+        """实时行情快照。``code``: ``sh600667`` / ``000001.SZ`` / ``600667``"""
+        return self._get("/v1/quote", code=normalize_code(code))
+
+    def kline(self, code: str, period: str = "day", count: int = 30):
+        """K 线。``period``: ``day`` | ``week`` | ``month``"""
+        return self._get("/v1/kline", code=normalize_code(code), period=period, count=count)
+
+    def hot(self, limit: int = 30):
+        """全市场热搜榜"""
+        return self._get("/v1/hot", limit=limit)
+
+    def market_overview(self, type: str = "summary"):
+        """市场总览。``type``: ``summary`` | ``trade`` | ``interval`` | ``technical`` | ``valuation`` | ``rotation``"""
+        return self._get("/v1/market-overview", type=type)
+
+    def changedist(self):
+        """涨跌分布（市场广度）"""
+        return self._get("/v1/changedist")
+
+    # 【财务 / 公司】
+    def finance(self, code: str, num: int = 4):
+        """三大报表（利润表 / 资产负债表 / 现金流量表）"""
+        return self._get("/v1/finance", code=normalize_code(code), num=num)
+
+    def profile(self, code: str):
+        """公司简况（上市日期 / 主营业务 / 行业）"""
+        return self._get("/v1/profile", code=normalize_code(code))
+
+    def dividend(self, code: str, years: int = 3):
+        """分红送转历史"""
+        return self._get("/v1/dividend", code=normalize_code(code), years=years)
+
+    def shareholder(self, code: str):
+        """股东研究（十大股东 / 股东户数 / 机构持仓）"""
+        return self._get("/v1/shareholder", code=normalize_code(code))
+
+    def chip(self, code: str):
+        """筹码分布 / 成本"""
+        return self._get("/v1/chip", code=normalize_code(code))
+
+    def events(self, code: str):
+        """个股事件标签（42 类）"""
+        return self._get("/v1/events", code=normalize_code(code))
+
+    # 【资金 / 交易】
+    def fund(self, code: str):
+        """个股资金 + 龙虎榜 + 大宗 + 两融（综合，一接口全有）"""
+        return self._get("/v1/fund", code=normalize_code(code))
+
+    def lhb(self, type: str = "institution", date: str = ""):
+        """龙虎榜分榜。``type``: ``institution``（机构）| ``hotmoney``（游资）| ``activeseat``（活跃席位）"""
+        return self._get("/v1/lhb", type=type, date=date)
+
+    def margin_trade(self, code: str = "", date: str = ""):
+        """融资融券明细。``code`` 留空 = 全市场"""
+        return self._get("/v1/margin-trade", code=normalize_code(code), date=date)
+
+    def block_trade(self, code: str = "", date: str = ""):
+        """大宗交易。``code`` 留空 = 全市场"""
+        return self._get("/v1/block-trade", code=normalize_code(code), date=date)
+
+    # 【指标 / 选股】
+    def technical(self, code: str):
+        """技术指标：MA / MACD / KDJ / RSI / BOLL"""
+        return self._get("/v1/technical", code=normalize_code(code))
+
+    def screen(self, expr: str = "", preset: str = "", limit: int = 20, orderby: str = "",
+               desc: bool = True, market: str = ""):
+        """因子选股。``expr`` 如 ``"intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])"``；``preset`` 如 ``low_pe``"""
+        return self._get("/v1/screen", expr=expr, preset=preset, limit=limit, orderby=orderby,
+                         desc=str(bool(desc)).lower(), market=market)
+
+    # 【板块 / 产业链】
+    def sector(self):
+        """板块行情榜（行业 / 概念 / 地域 + 领涨股）"""
+        return self._get("/v1/sector")
+
+    def sector_valuation(self, code: str):
+        """板块估值（PE/PB/PS + 历史百分位）。``code`` 如 ``pt01801780``"""
+        return self._get("/v1/sector-valuation", code=normalize_code(code))
+
+    def industry_chain(self, mode: str = "graph", topic: str = "", code: str = ""):
+        """产业链。``mode``: ``list``（主题清单）| ``graph``（图谱，配 ``topic``）| ``stock``（个股定位，配 ``code``）"""
+        return self._get("/v1/industry-chain", mode=mode, topic=topic, code=normalize_code(code))
+
+    # 【宏观 / 固收 / ETF / 新股】
+    def macro(self, region: str = "cn", names: str = ""):
+        """宏观数据。``region``: ``cn`` | ``us`` | ``jp`` | ``eu`` | ``hk``"""
+        return self._get("/v1/macro", region=region, names=names)
+
+    def bond(self, code: str):
+        """可转债条款（溢价率 / 双低 / 强赎触发 / 评级）"""
+        return self._get("/v1/bond", code=normalize_code(code))
+
+    def etf(self, code: str):
+        """ETF 概览（行情 / 规模 / 折溢价 / 资金流）"""
+        return self._get("/v1/etf", code=normalize_code(code))
+
+    def ipo(self, days: int = 15):
+        """新股日历（发行 / 申购 / 中签 / 上市）"""
+        return self._get("/v1/ipo", days=days)
+
+    # 【日历 / 研报 / 搜索】
+    def calendar(self, date: str = "", limit: int = 20):
+        """投资日历（个股事件：分红派息 / 解禁 / 财报）"""
+        return self._get("/v1/calendar", date=date, limit=limit)
+
+    def dehydrated(self, mode: str = "list", symbol: str = "", limit: int = 10):
+        """脱水研报。``mode``: ``list`` | ``detail``（配 ``symbol``）"""
+        return self._get("/v1/dehydrated", mode=mode, symbol=symbol, limit=limit)
+
+    def search(self, q: str):
+        """搜索股票 / 基金 / 板块（消歧）"""
+        return self._get("/v1/search", q=q)

ashareapi/errors.py

@@ -0,0 +1,29 @@
+"""异常类型（按用户能采取的动作分类，不只按 HTTP 码）"""
+
+
+class AShareError(Exception):
+    """SDK 异常基类"""
+
+
+class AuthError(AShareError):
+    """401 / 缺 Key —— 动作：检查 ASHARE_API_KEY 或去 https://ashareapi.com/pricing 获取"""
+
+
+class RateLimitError(AShareError):
+    """429 超频 —— 动作：降频重试；或解一次 PoW 挑战提额到 60 次/分（GET /v1/challenge）；或升级档位"""
+
+
+class EmptyResultError(AShareError):
+    """当前**无数据**（≠ 取数失败）—— 如当天无大宗交易。
+
+    **不扣调用次数**；稍后重试或换条件即可。
+    区别于 :class:`UpstreamError`（上游取数失败、已自动换源）。
+    """
+
+
+class UpstreamError(AShareError):
+    """ok=false（上游取数失败）—— 我们已**自动换源且不扣次数**，动作：重试一次通常就好"""
+
+
+class APIError(AShareError):
+    """5xx / 其他非预期响应"""

ashareapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: ashareapi
+Version: 0.1.0
+Summary: A股数据 API 官方 Python SDK —— 行情 / K线 / 财务 / 资金 / 龙虎榜 / 板块 / 因子选股（含 MCP）
+Author: ashareapi
+License-Expression: MIT
+Project-URL: Homepage, https://ashareapi.com
+Project-URL: Documentation, https://ashareapi.com/docs
+Project-URL: Endpoint list, https://ashareapi.com/endpoints
+Keywords: a-share,ashare,stock,quant,finance,mcp,stock-data-api,financial-data-api
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ashareapi — A股数据 API 官方 Python SDK
+
+**行情 / K线 / 财务 / 资金 / 龙虎榜 / 板块 / 因子选股** —— 30 个端点，**免费端点无需注册**。
+
+```bash
+pip install ashareapi            # 基础（返回 list[dict]）
+pip install "ashareapi[pandas]"  # 加 DataFrame 支持（推荐）
+```
+
+## 30 秒上手
+
+```python
+from ashareapi import AShareAPI
+
+cli = AShareAPI()                     # 免费端点无需 Key
+df = cli.quote("sh600667")            # 实时行情 → DataFrame
+print(df[["date", "last", "exchange"]])
+
+print(cli.kline("600667.SH", count=5))  # 代码格式随便写（自动归一化）
+print(cli.hot(limit=10))                # 热搜榜
+```
+
+**付费端点**（财务 / 资金 / 龙虎榜 / 选股等）需要 Key（[获取](https://ashareapi.com/pricing)，¥9.9 起）：
+
+```python
+cli = AShareAPI("ct-你的Key")          # 或设环境变量 ASHARE_API_KEY
+df = cli.screen(preset="low_pe", orderby="ROETTM", limit=10)
+print(df.head())
+```
+
+## 为什么用它
+
+- **免费端点真的免 Key**：`quote / kline / hot / market-overview / changedist` 直接调，无需注册
+- **代码格式兼容**：`sh600667` / `600667.SH` / `600667` 都认（不同写法的项目都能直接用）
+- **多源自动切换**：后端 67 个数据源互为备份，取数失败会自动换源且**不扣调用次数**
+- **错误分类清楚**：`AuthError` / `RateLimitError` / `UpstreamError` / `EmptyResultError`（无数据 ≠ 失败）—— 每类都告诉你该做什么
+- **pandas 可选**：不想装 pandas 也能用（返回 `list[dict]`）
+
+## 端点一览
+
+| 方法 | 说明 | 免 Key |
+|---|---|---|
+| `quote(code)` | 实时行情快照 | ✅ |
+| `kline(code, period, count)` | K 线（日/周/月）| ✅ |
+| `hot(limit)` | 热搜榜 | ✅ |
+| `market_overview(type)` | 市场总览（画像/估值/风格轮动）| ✅ |
+| `changedist()` | 涨跌分布（市场广度）| ✅ |
+| `finance(code, num)` | 三大报表 | — |
+| `fund(code)` | 资金流 + 龙虎榜 + 大宗 + 两融 | — |
+| `technical(code)` | MA / MACD / KDJ / RSI / BOLL | — |
+| `lhb(type)` | 龙虎榜分榜（机构 / 游资 / 活跃席位）| — |
+| `screen(expr/preset, ...)` | 因子选股 | — |
+| `search(q)` | 搜索消歧 | — |
+
+（完整 30 端点见 [端点清单](https://ashareapi.com/endpoints)）
+
+## 错误处理
+
+```python
+from ashareapi import AShareAPI, AuthError, RateLimitError, UpstreamError, EmptyResultError
+
+cli = AShareAPI()
+try:
+    df = cli.fund("sh600667")
+except AuthError as e:          # 401 / 缺 Key → 去拿 Key
+    print(e)
+except RateLimitError as e:     # 429 → 降频 / 解 PoW 挑战提额 / 升级档位
+    print(e)
+except UpstreamError as e:      # 上游取数失败（已自动换源、不扣次数）→ 重试一次通常就好
+    print(e)
+except EmptyResultError as e:   # 当前无数据（如当天无大宗交易）→ 不计费，换条件或稍后再试
+    print(e)
+```
+
+## 也用 AI Agent（MCP）
+
+除了 Python，我们还提供 **MCP 服务器**（Streamable HTTP）—— 一条 URL 接进 Claude Code / Cursor / Codex 等 19 家客户端：
+**https://ashareapi.com/mcp**
+
+## License
+
+MIT · 数据仅供研究参考，不构成投资建议

ashareapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ashareapi/__init__.py,sha256=ssm6TeaBU9Op7O3uAFLI0cip8mJ3gc8p7fe68laOvuQ,771
+ashareapi/_code.py,sha256=InXKmeGvHa89vfk06vfvPywSId6rPrYHlcsPexxcG7w,1364
+ashareapi/client.py,sha256=mklSWxqJ7ezBKCcXSbqX2KOy-eSWt_lYkqKFEKPOUAM,11337
+ashareapi/errors.py,sha256=iydx9U0yZDJt0mki1e-Ac21wuniSuFlVkDPIvW4cPQI,957
+ashareapi-0.1.0.dist-info/licenses/LICENSE,sha256=qi5c9h_E3tE2cxK649EII19fKD-tNstMA1aTi-b1Gd0,1066
+ashareapi-0.1.0.dist-info/METADATA,sha256=DWueMVfW8h5eJGk8n1T1lGCo3nrvR0TvagkyFQ9Ijic,4314
+ashareapi-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ashareapi-0.1.0.dist-info/top_level.txt,sha256=MxVnDSBx3hJXu-xFdz3sMEumReus-_rlVHVT7nVEzo4,10
+ashareapi-0.1.0.dist-info/RECORD,,

ashareapi-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
+

ashareapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ashareapi
+
+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.

ashareapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ashareapi