wmshare

English TL;DR — wmshare is a BSD-3-Clause open-source Python SDK covering China A-share, Hong Kong and US markets (per-capability matrix in「市场覆盖」): k-line (3 adjustment modes), intraday snapshots, money flow, the three financial statements, 2,197 metric codes (TTM, historical & industry percentiles, dividend analytics), a screener facade (single-stock screens & server-side market breadth), announcements and company profiles. Ships a machine-readable offline catalog, unified base units with per-response data guards (ratios as decimals, money in CNY, volume in shares), a typed facade, and an AI-agent skill. Credentials required (free registration at open.winmale.com; error messages guide you through setup). Install: pip install wmshare.

覆盖 A股、港股、美股 的 Python 财经数据 SDK——各市场逐能力明细见下方 「市场覆盖」矩阵。 注册开放平台领取凭证（免费、注册即得）后即可取数，见下方「配置凭证」。 许可与数据服务说明见文末「许可与数据服务」与 LICENSE。

目录

特性 · 快速上手 · 能力一览 · 市场覆盖 · 单位与数据守护 · 我想做 X → 用哪一行 · 许可与数据服务 · 更多

特性

• 数据要全——16 个数据域、113 个核心接口一站取全：K 线（三种复权、1 分钟分时、 盘中快照、ETF/指数）、分红、三大报表、资金流、公告、业绩预告、股东治理（十大股东/ 质押五族/限售解禁/机构持仓/沪港通/国家队/高管增减持/股本结构）、回购（方案+执行）、 并购重组、担保与诉讼、融资融券、可转债、盈利预测与研报、指数成分与估值、港美股披露。
• 数据要准——财报按最新会计准则归一，跨年跨公司直接比较；全库基础单位 （比率/涨跌幅=小数、金额=元、量=股）；每次返回做量级守护与关系不变量校验， 错误的量级到不了你的代码（见下方「单位与数据守护」）。
• 特色数据——免费且含实时（盘中快照、当日 1 分钟分时不另收费）； cli.screener 涨停/均线筛选一行直出，全市场涨跌全景/分桶/行业分布/涨跌榜走 服务端预计算索引，毫秒级响应，你不拉全市场数据、不算均线；2,197 个指标码 （TTM、3/5/10 年历史分位、192 个行业内分位、TTM 股息率/派息率 + 11 个质量筛选器） 服务端算好直出，不关心指标算法。
• 凭证即用——注册开放平台免费领取 client_id/api-key（注册即得），环境变量、 凭证文件、构造参数任选其一配置；遇到 401/403/429 错误消息即完整指引。
• 目录随包 + AI 原生——249 个底层函数、113 个核心接口、2,197 个指标码离线可查； 附 Agent Skills 格式 skill（wmshare.skill_dir()），复制进 AI agent 即可正确使用。

快速上手

安装

pip install wmshare                  # 基础安装
pip install "wmshare[dataframe]"     # 可选：pandas 支持（_df=True）
python3 -c "import wmshare; print(wmshare.__version__)"   # 验证安装

国内直连 pypi.org 不稳时用国内镜像（清华等镜像源随 PyPI 自动同步，通常当天可得，阿里云偶有滞后）：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple wmshare   # 清华源

镜像装不到最新版时回官方源 pip install -i https://pypi.org/simple wmshare；开发/贡献者安装见 CONTRIBUTING.md。

配置凭证

注册 赢麻了开放平台（微信扫码，免费、注册即得）， 在「我的 → 开放平台 → 我的应用」查看 client_id 与 api-key，然后任选其一：

export WMSHARE_CLIENT_ID=... WMSHARE_CLIENT_SECRET=...  # 方式一：环境变量
# 方式二：写入 ~/.wmshare/credentials.env（KEY=VALUE 每行一条）：
#   WMSHARE_CLIENT_ID=你的client_id
#   WMSHARE_CLIENT_SECRET=你的api-key
# 方式三：构造参数直接传：
#   cli = wmshare.Client(client_id="...", client_secret="...")

三行上手

import wmshare

cli = wmshare.Client.from_env()                   # 读上面配置的凭证
print(cli.dividend.yield_ttm("600519"))           # 0.0396（TTM 股息率，小数）
print(cli.screener.index_breadth_summary())       # 全市场涨跌全景（服务端直出）

更多调用见下方「我想做 X → 用哪一行」。遇到 401/403/429：错误消息里附有申请与配置 凭证的完整步骤。

能力一览

随包离线目录：16 个数据域 · 249 个底层函数 · 2197 个指标代码（11 个指标组、 75 个精选常用指标代码，cat.search("中文") 可编程检索）；友好层 113 个核心接口， 按使用视角组织为：

市场覆盖

市场切换：Client(market="cn" / "hk" / "us")，缺省 cn；代码与市场不匹配会被服务端直接拒绝 （如 cn 市场查 00700 报 market mismatch）。cli.intl 的港美股披露同样要用对应市场的 客户端调用（函数内部再按标的代码路由到港美数据族）。

如实注记（2026-10-28 实测）：港/美列的 ✅ 均经 live 探针逐族验证；美股日 K 为历史快照、 停更于 2026-03-13（上游对美股价量走 live-only 策略），美股最新价量用 cli.kline.live / snapshot（实测当日新鲜）；港美 K 线量额单位已随 1.x 修复（cn 手×100 仅在 cn 生效，港美上游即股直出）；三大报表的深研宽表（多期透视/合并对比/树视图） 暂仅 cn，港美报表科目级数据经指标码可查；hk 十大流通股东与回购上游已有数据管线、 SDK 接口待路由（见 ROADMAP）。

我想做 X → 用哪一行

常用示例（输出为预期量级；cli.kline.bars / statements.income 等其余接口同风格）：

import wmshare

cli = wmshare.Client.from_env()

# TTM 股息率：小数口径，0.0396 = 3.96%
print(cli.dividend.yield_ttm("600519"))                      # 0.0396

# 估值温度计：PE(TTM) 处于近 10 年 42% 分位（小数）
print(cli.indicator.get("600519", "$PCT_PE_TTM_10Y_LAST"))   # 0.42

# 行业定位：ROE 在同行业内的分位（1.0 = 行业最高；茅台 ROE 为行业之最）
print(cli.indicator.get("600519", "$CUR_IND_ROE_PCT_LAST"))  # 1.0

# 技术面一行布尔：是否站上 20 日均线
print(cli.screener.screen_above_ma20("600519"))              # True

# 全市场涨跌全景：服务端索引直出，免本地扫描（*_pct 百分数、median_pct 小数）
print(cli.screener.index_breadth_summary())
# {'total': 5685, 'up': 4567, 'down': 934, 'flat': 184, 'up_pct': 80.3, ...}

# 分红质量：高股息 + 派息可持续（默认精品窗口=派息率 30%–70%，可显式放宽）
print(cli.dividend.screen_quality("600519", min_yield=0.02, payout_max=1.5))  # True

# 公告信号：近 6 个月是否有回购公告
print(cli.notice.has_buyback("600519", "6m"))                # True

以上能力全部在离线目录可查：cat.search("分位")、cat.metrics_in_group("dividend")。

单位与数据守护

全库统一基础单位：比率 / 涨跌幅 = 小数（0.01 = 1%，ROE 0.332 = 33.2%）、 金额 / 价格 / 市值 = 元（报表原币）、成交量 = 股；各接口单位口径见「能力一览」表。 返回前做量级与关系不变量校验，违例抛 DataError——错误的量级到不了你的代码。 需要脚本原始口径时：_raw=True（store 原始行）、_units="native"（脚本输出单位）， 或 Client(validate=False) 关闭校验。

数据深度：个股/ETF 日 K 覆盖自上市首日以来的全部交易日（最早 1991 年）； 单次区间上限 5 年、默认单次 500 根（Client(max_limit=...) 可调）。全量深回溯 （1990 年代不复权老数据）可能触发不变量守护，需整段历史时 validate=False 取全。

许可与数据服务

• 代码采用 BSD-3-Clause：可自由使用、修改、再分发（含商业用途），保留版权声明即可。
• 云端数据服务需 开放平台 账号与额度，免费额度注册即得； 服务条款以开放平台为准。
• 数据仅供研究参考，不构成任何投资建议。

更多

• AI agent skill（随包分发）：把 skill 装进 agent 的发现目录，AI 即可正确使用 SDK（目录先行防臆造指标码、单位铁律、错误引导都在 skill 里）：

  cp -r "$(python3 -c 'import wmshare; print(wmshare.skill_dir())')" ~/.agents/skills/wmshare
  # 项目级按工具放入 .zcode/skills/ 或 .claude/skills/
  

  skill 源文件：src/wmshare/skills/wmshare/SKILL.md （LLM 可直接读取的结构化用法）。

• 生态工具 big-winner（基于本 SDK 构建的开源工具）： 收息佬——攒股收息驾驶舱（分红日历、A/H 持仓透视、派息稳定性看板）； 波段——估值买卖点参考：区间设置支持推荐区间（四条约束自动搜点，含成交次数） 与自定义区间两种来源，附安全边界（高位介入回撤统计）与「波段 vs 长持」历史回放。

• API 参考：四大类 113 个核心接口（参数 / 返回字段 / 单位口径 / 示例）+ 指标组

• OpenAPI / Swagger：docs/openapi.json（OpenAPI 3.1，可导入 Apifox / Postman 等工具）；docs/swagger.html（已内联 spec，浏览器直接打开； Swagger UI 资源来自 CDN，若浏览器限制 file:// 可在 docs 目录起 python -m http.server）

• 类型化门面：全部目录命名空间带类型签名与 docstring（py.typed），IDE 直接补全； 单次拉取上限 Client(max_limit=500) 可调

• 批量调用：cli.call_batch("kline.query_bars", ["600519", "000001"]) 单次 HTTP 返回 {symbol: 结果}；on_error="skip" 时逐标的隔离错误

• 示例脚本 examples/：quickstart（三行上手）、catalog_tour（离线目录漫游， 免凭证）、error_handling（离线错误分类）、dividend_screener、screener、pandas_analysis （各示例前提见文件 docstring）

• 贡献指南：提交门禁、内容规范、许可政策

• 运行测试：pytest（不联网）；WMSHARE_LIVE=1 pytest tests/test_live.py（真实冒烟）