Skip to content

v2.2.0 — VIX 期限结构 / 做空余额 / Form 4 与 13F / 台股 / 能源

Choose a tag to compare

View all tags
@simonlin1212 simonlin1212 released this 12 Oct 00:07
· 3 commits to main since this release
v2.2.0
cc6afb5

十六层架构 · 50+ 个端点 · 17 个数据源（v2.1.0 为十四层 · 40+ · 14）。
新增 11 个入口、2 层（Layer 14 台股、Layer 15 能源）、3 家来源（台湾证交所、柜买中心、美国能源信息署 EIA）；
波动率指数、做空余额、Form 4 / 13F 解析分别并入原有的 CBOE、FINRA、SEC 层，不另计层、不另计来源。不新增依赖。
层数按「原有八层 + V2.0 五层（CBOE 期权链单算一层）+ V2.1 一层 + V2.2 两层」计，SKILL.md 与 README 已写明。

新增：§6.3 波动率指数历史 + VIX 期限结构（CBOE，C 级）

入口 内容
vol_index_history(index, start, end) VIX（1990 起）/ VIX1D / VIX9D / VIX3M / VIX6M / VIX1Y / VVIX / SKEW / OVX / GVZ 等指数日线
vix_term_structure() 最新一日各期限 VIX，判断 contango 还是倒挂，附长短端差

与 6.1 期权链同属 Cboe 内容，C 级，仅供个人研究。VVIX / SKEW / OVX / GVZ 的文件只有收盘价。

新增：§9.2 做空余额（FINRA，B 级）

入口 内容
short_interest_all(date) 某一期全美做空余额（交易所上市 + OTC），不传日期取最近已发布的一期
short_interest(symbol, periods) 单只股票最近 N 期（1–24）
short_interest_ranking(snapshot, by) 按回补天数 / 空头股数 / 较上期变化排行，默认去掉 OTC 和日均成交量不足 50 万股的小票

处理过的坑：

  • 结算日是每月 15 日和月末，遇假日提前：从锚点日往前试 3 个工作日（2024-01-15 马丁路德金日 → 01-12 的文件）
  • 最新一期要结算后约 8 个工作日才发布：没发布时自动往前找
  • FINRA 文件里的代码去掉了点和横线（BRK.B 写成 BRKB），按同样规则查；优先股写法不同（BAC-PL 在文件里是 BACPRL），要按 FINRA 的写法查；文件里查不到的代码返回 DataNotAvailable，不返回空列表
  • 排行默认去掉的场外股票包括早年文件里的 OTCBB（2017-12-29 的文件有 17 只）

新增：§10.3 Form 4 内部人交易、§10.4 13F 机构持仓（SEC EDGAR，S 级）

入口 内容
insider_trades(ticker / cik, days, max_filings, codes) 逐份读 Form 4 原文：内部人、身份、交易日、交易类型、股数、价格、金额、交易后持股、所在申报是否勾选 10b5-1 计划（filing_10b5_1）；附公开市场买入 / 卖出汇总
holdings_13f(cik, period, top) 机构某一季 13F 持仓，同一证券按 CUSIP 与认购 / 认沽合并，按市值排序含占比，带封面申报总额可对账

处理过的坑：

  • SEC 的申报列表主文件只放最近一年（或最近 1000 份，取多者），更早的在历史分页里。回看超出主文件时自动多读分页：
    高盛一年上万份申报，回看 730 天窗口内有 129 份 Form 4（只读主文件只看到 68 份）；查高盛 2024-12-31 季度 13F 同理。
    13F 不传报告期时，若最近一年没交过，往更早的分页翻到第一份为止
  • Form 4 的申报列表给的是渲染后的网页路径（xslF345X05/…），去掉前缀才能拿到原始 XML
  • 机构自己买别家股票时，它的 CIK 在那份 Form 4 里是「申报人」不是「发行人」，跳过
  • 10b5-1 是整份申报一个选框，不是逐笔标记：同一份申报里的行权、扣税、赠与也会带上 True，所以字段叫 filing_10b5_1。
    这一栏是 SEC 2023 年启用的新版表格才有，更早的申报返回 None，不是 False
  • 一份申报有多位申报人时，名字和身份合并成一条；form4_in_window / filings_scanned 也会数到这家公司（或机构）作为申报人的申报
  • 13F 在 2023-01-03 之前申报的金额单位是千美元，统一换成美元（伯克希尔 2022-09-30 季度合计 2,961 亿美元）
  • 13F 信息表的文件名各家不同，按内容找含 infoTable 的那个；2013 年二季度以前的 13F 是纯文本，不解析，返回 DataNotAvailable
  • 「最新一季」按报告期挑，不按申报日（补报的旧季度不会被当成最新）
  • SEC 的 XML 不声明字符集，按字节交给解析器，避免非英文名字乱码（通用出口 official_get 新增 raw=True）
  • 只读原始申报，修订版（4/A、13F-HR/A）不读；Form 4 只读股票本身的买卖表，不读期权等衍生品表

新增：Layer 14 台股（台湾证交所 / 柜买中心 OpenAPI，S 级）

入口 内容
tw_stock(code) 单只台股最新行情 + 本益比 / 股价净值比 / 殖利率，自动判断上市还是上柜（2330 / 2330.TW / 6488.TWO 都行）
tw_market(dataset, market, code) 上市或上柜全市场或单只：行情 / 估值 / 月营收 / 基本资料 / 融资融券 / 除权除息预告 / 股利决议

只有最新一个交易日，没有历史；台股历史 K 线仍用 Yahoo .TW / .TWO（D 级）。两家字段名不同，统一成同一套英文字段；
民国纪年日期换成公历；全市场快照 10 分钟内复用（返回的是副本，改了不影响缓存）。没有收盘价时涨跌返回 None（官方写 0）。
柜买中心的股利分派表实测停在 2021 年，不收。

新增：Layer 15 能源（美国能源信息署 EIA，库存 S 级 · 现货价格 B 级）

入口 内容
energy_prices(series, start, end) WTI（1986 起）/ 布伦特（1987 起）原油现货、Henry Hub 天然气（1997 起）日价
energy_inventories() 原油（商业 + 战略储备）、汽油、馏分油等每周库存，含上周与去年同期对比；美国本土及分区天然气储量，另含五年均值对比

用的是 EIA 官网的公开页面和文件；EIA 正式 API 要申请 key，按项目规则不用。Henry Hub 走原油那种接口会 404，改读天然气历史页。

合规分级

新读条款原文（2026-10-12）：

  • EIA 库存 → S 级："U.S. government publications are in the public domain and are not subject to copyright protection."，转载时注明来源与日期
  • EIA 现货价格 → B 级：EIA 数据说明页写明 WTI / 布伦特 / Henry Hub 现货价的来源是 "Refinitiv, an LSEG business"；
    EIA 版权页对第三方授权材料写明，超出合理使用的转载须版权方书面许可。页面公开、个人研究可用，商用或再分发前自行确认（归 B 级是本工具的判断）
  • 台湾证交所 / 柜买中心 → S 级：本工具用到的 13 个数据集（证交所 7 个、柜买中心 6 个）都登记在台湾「政府资料开放平台」，
    适用《政府资料开放授权条款-第1版》（「不限目的、時間及地域、非專屬、不可撤回、免授權金」，须注明来源）；
    两家网站条款的知识产权一节写明，授权给政府资料开放平台的资料 「不在此限」，转载须 「清楚註明資料來源，並確保資料完整性，不得任意增刪」。
    网站条款禁止 「非依（交易所）同意之方式」 用自动程序下载；两家 OpenAPI 说明页都写 「歡迎各位介接使用」，证交所的还链接上述授权条款，
    官方开放的程序接口即为其同意的方式（本工具的理解）。柜买中心的 OpenAPI 页没有链接授权条款，平台上登记的多是网页下载地址，
    归 S 级是本工具的判断，已在 SKILL.md 与 README 标明
  • FINRA（B 级）与 CBOE（C 级）的说明分别补上做空余额与波动率指数

测试

  • Python 3.9.6 实测（2026-10-12）：
    • 波动率：VIX 1990-01-02 起 9,291 根，2020 年 3 月最高收盘 82.69；期限结构 contango，长短端差 10.47；代码含非法字符、日期格式错、start 晚于 end 报 ValueError，不存在的指数与区间内无数据返回 DataNotAvailable
    • 做空余额：2026-09-15 一期 22,595 只；AAPL 1.29 亿股、回补天数 2.85；BRK.B 按 BRKB 查到；假日结算日回退到 2024-01-12；未发布的一期、查不到的代码（含 BAC-PL 这种非 FINRA 写法）返回 DataNotAvailable
    • Form 4：AAPL 近 30 天 14 份、卖出 14 笔合计 9,067 万美元；NVDA 近 180 天 37 份、卖出 32 笔合计 13.78 亿美元，其中 10 笔所在申报勾了 10b5-1 选框；高盛回看 730 天自动读历史分页，窗口内 129 份，全读得 303 笔、最早 2024-10-18 申报（135 次请求约 100 秒）；港股代码、不存在的代码、参数越界报错
    • 13F：伯克希尔 2026-06-30 季度 29 个持仓、合计 2,992.5 亿美元，与封面总额一致；2022-09-30 季度千美元单位换算正确；高盛 2024-12-31 季度（在历史分页里）5,993 个持仓、合计 6,344 亿美元，与封面一致；非 13F 申报人、2013 年二季度以前的纯文本 13F（潘兴广场 2012-12-31、伯克希尔 2013-03-31）返回 DataNotAvailable
    • 台股：台积电 2330 收盘 2,550、本益比 29.56；环球晶 6488（上柜）收盘 1,130；七类数据上市、上柜（股利仅上市）都能按代码筛出单只；ETF、杠杆 ETF（00631L）可查；无效代码报 ValueError，查不到的代码返回 DataNotAvailable
    • 能源：WTI 9,517 根，2020-04-20 为 -36.98；天然气储量 3,500 Bcf，比五年均值高 2.0%
    • 参数检查：None、非整数（含无穷大）、不存在的日期（如 2026-06-31、20261315）、13F 非季末日或还没到的季度、ticker 与 cik 同时给、无效交易代码、期限结构给了非期限指数、台股空代码，都在联网前报 ValueError（27 项逐条实测）
  • 独立复审（Opus）一轮：4 条应修——SEC 只读申报列表主文件，一年以前的数据静默缺失；10b5-1 是整份申报的选框却当成逐笔；EIA 现货价来自 Refinitiv，不该是 S 级；更新日志留了占位符。另有 9 条小问题（台股缓存可被改、无成交行涨跌写 0、台湾条款引错段落、参数检查缺口、2013 年前 13F 报错类型、XML 字符集、层数口径与措辞、OTCBB 与优先股、申报计数口径）和 3 条读代码推断的疑点，全部修复或写明（优先股写法、申报计数口径、多申报人合并三条是写进文档），并逐条实测；五个模块的原有用例重跑，除报错文字外输出不变
  • 修复部分再做一次独立复审（Opus，只审补丁）：没有应修问题；6 条小问题——README 把台湾数据写成「不得改动」说过头、13F 不传报告期时翻分页太慢、两处参数检查漏网（无穷大、codes 传数字）、台股空代码先下载再报错、更新日志三处措辞、回看超一年时读分页与 max_filings 无关没写明——已全部处理并复测
Assets 2
Loading