mairui — 麦蕊智数 Python SDK

完整接口字段说明见 API.md（含沪深数据中心 / 基金 / 量化因子）。方法对照见 API_METHOD_MAP.md。

面向 https://api.mairuiapi.com，覆盖官网 API 文档（如 https://mairuiapi.com/hsdata）中对外公开的全部接口。

源码仓库：https://github.com/MaiRuiApi/mairui

安装

pip install mairui

PyPI：https://pypi.org/project/mairui/

30 秒上手

from mairui import Client

with Client(licence="YOUR-LICENCE-UUID") as api:
    # 股票列表
    stocks = api.stock_list()

    # 日线历史（可选 st/et/lt）
    bars = api.stock_history("000001.SZ", "d", "n", st="20240101", et="20241231")

    # 实时
    tick = api.stock_real_time("000001")

    # 财务
    bal = api.stock_balance("000001.SZ")

    # 批量并发（复用连接池）
    batch = api.map(
        api.stock_history,
        ["000001.SZ", "600519.SH", "000002.SZ"],
        period="d",
        dividend="n",
        lt=5,
        max_workers=8,
    )

只需绑定一次 licence，之后所有方法自动拼到 URL 末段。

设计要点（效率与工程）

接口 ↔ 方法对照（摘要）

完整对照见 API_METHOD_MAP.md。常用：

查询参数与文档一致：

• st / et：开始 / 结束时间（如 20240101 或 20240101153000）
• lt：最新条数（从尾部截取）

不传则返回服务端完整可用数据（由证书权限与数据存量决定）。

构造参数

Client(
    licence="...",
    base_url="https://api.mairuiapi.com",  # 一般无需改
    timeout=(5, 60),
    max_retries=3,
    pool_connections=32,
    pool_maxsize=64,
)

异常处理

from mairui import Client, MairuiAuthError, MairuiHTTPError, MairuiTimeoutError

try:
    with Client(licence="...") as api:
        print(api.stock_history("000001.SZ", "d", "n", lt=3))
except MairuiAuthError as e:
    print("证书问题", e)
except MairuiTimeoutError as e:
    print("超时", e)
except MairuiHTTPError as e:
    print("HTTP", e.status_code, e.payload)

目录

mairui/
  __init__.py
  client.py      # 全部接口方法
  _http.py       # Session / 重试 / 编码
  exceptions.py
examples/
  quickstart.py
pyproject.toml
README.md
API_METHOD_MAP.md
LICENSE

说明

• 接口清单与官网文档页一致，例如沪深 A 股：https://mairuiapi.com/hsdata（同站还有指数、基金等文档入口）。
• SDK 默认请求主站 https://api.mairuiapi.com；证书可在官网获取。
• 本包为同步 SDK；若需 asyncio，可在外层用 asyncio.to_thread 包一层，或后续再发 async 版。