无参数 select():先看全量
Equities、ETFs、Funds、Indices、Currencies、Cryptos、Moneymarkets 七个类 这类入口,一次性把某一类证券的清单取回来。适合初次探索字段结构、确认某一类到底覆盖多少标的,也适合做全量导出。它不做筛选,所以拿到的是最全的集合。
Features & Limits
FinanceDatabase 以简洁 API 提供证券代码与元数据查询能力:全量取数、select 筛选、search 搜索,均返回 pandas DataFrame。这一页的重点不是再讲一遍功能,而是把「它能做什么、明确不做什么、许可怎么看、配什么用」摊开讲清楚,方便你在动手前判断该不该用它。建议的阅读顺序是:先看功能与不适用场景,再看许可与限制,最后用决策表选定路线。
事实核验卡(核验日期 2026-09-29)
以上数字来自本站 2026-09-29 在 Windows + Python 3.11.9 + financedatabase 2.4.0 下的真实运行输出,不是从文章里转抄的;数据文件由上游持续更新,行数会变,以官方 PyPI 与 GitHub Release 为准。采集时 GitHub star 约 9,374(2026-09-29)。
官方 README 声明的主要能力,这里补上「什么时候用得上」与「容易误判的地方」两列。FinanceDatabase 的能力都集中在「把证券找出来」这件事上。
| 能力 | 具体表现 | 适用场景 | 注意点 |
|---|---|---|---|
| 证券展示 | 无参数的 select() 一次性获取某类证券的完整列表 | 先摸清某一类证券有多少、都有哪些字段 | 返回的是清单,不是行情;数据量较大时注意内存与打印截断 |
| 条件筛选 | select()按国家 / 行业 / 板块 / 市值筛出子集 | 搭建候选池、按市场或行业分箱 | 条件值要按官方取值口径写,写错通常返回空表而不是报错 |
| 名称搜索 | search() 按名称模糊查找证券 | 只记得中文简称或英文名,不确定代码 | 模糊匹配会给出多个候选,需自己确认哪一个才是目标标的 |
| 七类证券覆盖 | 股票 / ETF / 基金 / 指数 / 货币 / 加密货币 / 货币市场分别有查询入口 | 跨资产类别找标的 | 同一标的可能在不同类别下以不同代码出现,跨类比较前先去重 |
| DataFrame 返回 | 查询结果统一以 pandas DataFrame 返回 | 直接接入后续清洗、落库、导出流程 | 列名与索引要自己核对,别默认首列就是代码 |
| 元数据字段 | 名称 / 代码 / 国家 / 行业 / 板块 / 市值 / 货币等 | 给数据管道补上标的维表 | 字段由上游数据源提供,可能存在空值与滞后 |
| 可导出可复用 | DataFrame 可直接存成 CSV 或写入数据库 | 把证券清单固化下来做可复现研究 | 导出的快照会过时,定期重跑比长期沿用旧文件可靠 |
select / search / show_options 三类方法各司其职,分清职责就不会在错误的函数上反复试参数。
Equities、ETFs、Funds、Indices、Currencies、Cryptos、Moneymarkets 七个类 这类入口,一次性把某一类证券的清单取回来。适合初次探索字段结构、确认某一类到底覆盖多少标的,也适合做全量导出。它不做筛选,所以拿到的是最全的集合。
Equities().select() 支持按 country、sector、industry、market_cap 这些维度筛出子集,是把「全量清单」变成「我的候选池」的主要手段。它的输出仍然是清单而非行情,筛选依据来自元数据字段,所以字段本身的滞后会直接传导到筛选结果上。
search() 支持按名称模糊搜索,也可以指定在某一类数据库内搜索。它的价值在于「我只记得名字、不知道代码」这一步:先用名称找到候选,再把代码交给后续流程。模糊匹配天然会返回多条结果,需要人工或规则确认目标只有一个。
官方资料对「不提供行情价格」有明确说明,但很少把「所以你拿它做不了哪些事」逐条写出来。这一节把边界翻到使用场景一侧,避免装完才发现方向不对。FinanceDatabase 的定位是证券清单与元数据,凡是要时间序列或交易能力的需求都不在它的范围内。
| 你想做的事 | 它能不能做 | 该用什么替代 | 注意点 |
|---|---|---|---|
| 取某只标的的历史收盘价 | 不能:只提供代码与元数据,不提供价格 | 公开行情接口或商业行情源 | 元数据里的字段不是价格,不要拿市值当价格用 |
| 算 MACD、RSI 等技术指标 | 不能:没有时间序列输入 | 行情源自带的指标能力或指标计算库 | 指标必须先有行情,顺序上行情在前 |
| 做策略回测 | 不能:不含撮合、手续费、持仓与计费 | 回测框架(另行评估选型) | 回测框架本身也要自带或外接行情数据 |
| 盘中盯盘与实时推送 | 不能:属于静态清单与元数据 | 实时行情接口或推送服务 | 清单更新节奏与行情推送节奏是两件事 |
| 做财务报表与基本面分析 | 不直接提供:定位在清单与元数据 | 基本面数据工具(同作者另有 FinanceToolkit 方向) | 以官方说明与实际返回为准 |
| 覆盖全部市场(含 A 股全量) | 覆盖范围以官方声明为准,A 股并不完整 | 面向国内市场的财经数据接口 | 用之前先用一只你熟悉的标的试查,确认是否覆盖 |
| 保证字段始终最新 | 不保证:字段由上游数据源提供 | 以官方更新节奏为准,自行定期重跑 | 市值一类字段可能滞后于实时市场 |
所有查询返回 pandas DataFrame,便于二次分析。下面这张表按「调用 → 返回 → 怎么用」把常见入口串起来,右侧两列是实际使用中较易踩到的点。表里这几行覆盖了从探索到落盘的完整过程,照着走一遍基本能把常见入口都试到。
| 调用 | 返回 | 典型内容 | 什么时候用它 | 注意点 |
|---|---|---|---|---|
Equities().select() | DataFrame | 该类全部股票及其元数据 | 探索字段、全量导出 | 行数多,直接打印会被截断,先看 shape 与列名 |
ETFs().select() 等同族 | DataFrame | 对应类别的清单 | 跨类别铺开找标的 | 类别之间的列名不完全一致,合并前先对齐 |
Equities().select(country=...) | DataFrame | 某国家/地区的股票子集 | 按市场收窄候选池 | 取值口径以官方为准,写错一般返回空表 |
Equities().select(sector=...) | DataFrame | 某行业/板块的子集 | 做行业分组研究 | 行业名称需与官方字段取值一致 |
Equities().search(name="Apple") | DataFrame | 名称匹配的候选证券 | 只知道名字、要找代码 | 返回多条候选,需确认目标只有一个 |
df.to_csv(...) | 落盘文件 | 清单快照 | 做可复现研究、交付给下游 | 快照会过时,记录采集时间并定期重跑 |
项目以开源许可发布,但「代码许可」和「你在上面拿到的数据能不能二次分发」是两件事。下面这张表只陈述仓库现状与该去核对的地方,具体结论请以仓库 LICENSE 文件与各上游数据源条款为准。FinanceDatabase 的许可信息请优先看仓库里的 LICENSE 原文,而不是任何二手转述。
| 问题 | 现状 | 该去哪核对 | 注意点 |
|---|---|---|---|
| 用什么许可发布 | 仓库 README 声明为 MIT 许可 | 仓库根目录的 LICENSE 文件原文 | 以 LICENSE 原文为准,本页不替官方下结论 |
| 能不能用于商业项目 | 需按许可原文与你的使用方式判断 | LICENSE 原文 | 开源许可通常较宽松,但请自行核对,别转述二手结论 |
| 要不要保留版权声明 | 按许可原文执行 | LICENSE 原文 | 保留原始版权与许可声明是通行做法 |
| 代码许可能否覆盖数据 | 不能直接推定:数据来自上游源 | 各上游数据源各自的使用条款 | 数据条款往往比代码许可更严,商用前务必单独核对 |
| 二次分发证券清单可以吗 | 需同时满足代码许可与上游数据条款 | 上游源条款与 LICENSE 原文 | 把清单打包再分发属于典型需要单独确认的场景 |
| 引用出处怎么写 | 建议注明项目名与仓库地址 | 仓库 README 与官方说明 | 学术或对外材料中注明来源更稳妥 |
| 用于投资决策合规吗 | 本库只提供清单与元数据,不构成投资建议 | 本站披露与你的合规要求 | 不得用于收益承诺;结果仅供研究 |
知道有哪几条限制只算一半,更关键的是判断「这条限制会不会影响我这件事」。下表把每条限制拆成影响面、不受影响的场景与应对方式。
| 限制 | 具体影响 | 什么时候不影响你 | 应对方式 |
|---|---|---|---|
| 不提供行情价格 | 无法直接计算收益、波动、指标 | 你只需要一份标的清单或维表 | 拿到代码后另接行情源 |
| 字段可能滞后 | 市值一类字段滞后会让筛选结果偏离当下 | 你做的是长期结构分析而非择时 | 记录采集时间,定期重跑并说明口径 |
| 覆盖以官方声明为准 | 某些市场(如 A 股)覆盖不完整 | 你的研究集中在其覆盖较好的市场 | 先用熟悉标的试查,确认覆盖后再批量用 |
| 上游数据源可达性 | 网络受限时取数可能失败或变慢 | 你已有稳定网络或代理条件 | 把取数步骤与后续分析解耦,失败可重跑 |
| 字段存在空值 | 筛选或分组时空值会造成遗漏 | 你使用的是字段齐全的类别 | 先统计缺失情况,再决定是否填补或排除 |
| 不是投资建议 | 不能作为买卖依据 | 你把它当作数据准备工具 | 对外输出时明确标注用途与免责 |
| 版本与接口会演进 | 旧脚本可能因接口调整而失效 | 你锁定了可用版本 | 升级前预留核验步骤,以官方发布说明为准 |
| 依赖 pandas 生态 | 环境里没有 pandas 时无法直接使用 | 你已有 Python 数据环境 | 先把依赖装好再开始,避免中途卡在环境问题上 |
FinanceDatabase 常常只负责链路的上游一段:把标的找出来。下面这张表按「定位 → 拿到什么 → 拿不到什么 → 适合谁」把常见搭配摊开,其中本机技能路线只描述定位与前置条件,不代表与本项目存在集成。选哪一个取决于你的数据范围与是否愿意自己搭环境。
| 搭配对象 | 定位 | 拿得到什么 | 拿不到什么 | 适合谁 |
|---|---|---|---|---|
| FinanceToolkit(同作者方向) | 财务与基本面分析工具 | 基本面维度的分析能力 | 具体能力以官方文档为准 | 拿到代码后要接着做基本面研究 |
| yfinance 一类的公开行情接口 | 行情获取 | 历史行情与基础报价 | 覆盖范围与频率以官方说明为准 | 需要快速把代码补成行情序列 |
| 面向国内市场的财经数据接口 | A 股等国内品种取数 | 国内市场数据 | 具体品种与频率以各项目文档为准 | 研究范围在国内市场 |
| 本机已核验的金融数据技能路线 | 对话式取数与研究 | 一句话发起数据或研究任务 | 各技能的数据源、账号与覆盖范围不同 | 不想先搭 Python 环境 |
| 自建证券清单库 / ETL | 把清单沉淀为可复现资产 | 本地可控、可版本化的维表 | 需要自己维护更新与校验 | 长期项目、要求结果可复现 |
| 研究终端类工具 | 综合研究界面 | 以各自官方文档为准 | 以各自官方文档为准 | 习惯在图形界面里完成研究 |
| 本地数据库或表格文件 | 清单的落地层 | 把清单存成可反复查询的表 | 更新与校验仍需自己负责 | 想用 SQL 或表格工具继续加工 |
同一个目标——拿到一份可用的标的清单,两条路要准备的东西并不一样。下面按前置条件逐项对照,先看你要付出什么,再决定走哪条。FinanceDatabase 自建路线的优势是可控与可复现,代价是要自己维护环境与数据链路。
| 前置条件 | 自建 FinanceDatabase 路线要准备 | 对话式免部署路线要准备 | 注意点 |
|---|---|---|---|
| 运行环境 | Python 环境与 financetoolkit 依赖(实测连带 pandas 3.0 / numpy 2.4) | 安装客户端后直接提问 | 自建路线需要自己处理依赖冲突 |
| 数据范围 | 以该库覆盖范围为准,A 股不完整 | 取决于所用技能的数据源 | 两条路的数据范围都不等于「全市场」 |
| 账号与密钥 | 多数情况下不需要额外密钥 | 部分技能需要各自的数据账号或 Key | 密钥类前置条件以各技能说明为准 |
| 结果形态 | DataFrame / CSV,可进管道 | 对话返回的表格与摘要 | 需要接入代码流水线时,结构化输出更省事 |
| 可复现性 | 高:脚本与快照都可存档 | 中:依赖当次提问与账号状态 | 要写进报告或审计的结论,优先选可存档的方式 |
| 维护成本 | 需要自己定期重跑与校验 | 更新由所用技能侧负责 | 省下的维护成本换来的是可控性下降 |
| 适合的提问方式 | 自己写筛选条件与后处理 | 用自然语言描述任务 | 任务越复杂,越需要先确认数据口径 |
用一只你熟悉的标的试查,确认它是否在覆盖范围内。python -c "import financedatabase as fd; print(fd.Equities().search(name='Apple').head())" —— 能打印出候选行即说明库可用且覆盖该标的,无输出则先排查覆盖范围与网络。
看你需要的维度(国家、行业、市值等)是否在返回列里,缺失字段会影响后续筛选口径。
清单之后的行情、指标、回测分别由哪个工具负责,提前定好接口格式,避免中途返工。
结论要进报告或需要长期复现 → 选自建并可存档的方式;只是快速看一看 → 选对话式路线更省准备时间。
导出时在文件名里带上采集时间,并在备注中写明筛选条件与字段口径,方便几天后复查时知道自己当时筛的是什么。
把「覆盖哪些市场、字段截至什么时候、后续行情来自哪里」一并写进结论,避免把一份清单当成完整的数据依据。
把常见目标逐条列出来对照,比反复读功能列表更快得出结论。下表左列是你要达成的目标,中间给出更合适的路线方向,右侧两列是判断依据与容易被忽略的地方。表里的路线方向只是更常见的选择,不是硬性规定。
| 你的目标 | 更合适的路线 | 判断依据 | 注意点 |
|---|---|---|---|
| 建一份可复现的证券维表 | 用这个库自建清单 | 它专做清单与元数据,结果可导出存档 | 需要自己维护更新节奏与校验流程 |
| 只想知道某只标的的代码 | 名称搜索就够了 | search() 可直接由名称反查 | 模糊匹配会给出多条候选,要确认目标 |
| 按国家 / 行业 / 市值圈定候选池 | 条件筛选 | select()按维度收窄集合 | 条件取值口径以官方为准,写错多为空表 |
| 要历史行情做指标或回测 | 行情源加回测框架 | 该库不提供价格与时间序列 | 顺序上先有行情,再谈指标与回测 |
| 只想快速看看某个行业有哪些标的 | 对话式免部署路线 | 不必先搭 Python 环境 | 可复现性弱于脚本,适合一次性了解 |
| 研究范围主要在国内市场 | 面向国内市场的财经数据接口 | 该库对 A 股的覆盖并不完整 | 先用一只熟悉的标的试查覆盖情况 |
| 要长期维护、多人协作的数据资产 | 自建清单库并做版本化落地 | 脚本与快照都能归档,便于交接 | 需要约定更新频率与字段口径,否则口径会分叉 |
本库自己在 helpers.py 里写明了定位——不提供最新的基本面与行情。官方给出的衔接入口是 FinanceFrame.to_toolkit()。下面是 2026-09-29 的真实调用记录。
from financedatabase import FinanceFrame import financedatabase as fd equities = fd.Equities() one = FinanceFrame(equities.data.iloc[[0]]) # 注意:不能用 .head(),那样会丢掉方法 tk = one.to_toolkit(start_date="2024-01-02", end_date="2024-01-05", progress_bar=False) # 实测终端输出(原样摘录): # The parameter api_key is not set. Therefore, using Yahoo Finance as the source which # is limited to 5 years of fundamental data. Consider obtaining a key with the following # link: https://www.jeroenbouma.com/fmp # You can get 15% off by using the above affiliate link to get access to 30+ years of # (quarterly) data which also supports the project. # 返回类型:Toolkit(耗时 40.1 秒,含联网取数)
| 实测项 | 结果 | 你要提前知道的事 |
|---|---|---|
| 返回类型 | Toolkit(FinanceToolkit 对象) | 后续的比率、报表、技术指标都走 FinanceToolkit 的接口 |
| 是否要 API Key | 不必填,但会打印提示 | 不填 api_key 时回落到 Yahoo Finance,官方提示只有 5 年基本面数据 |
| 官方提示里的链接 | 是带 15% 折扣的推广链接 | 该提示文本把商业推广写进了运行日志,介意的话可自行换成别的数据源 |
| 耗时 | 单标的 40.1 秒(含联网) | 批量传入多标的会明显更久,且受上游限流影响 |
| 可否先切片再调用 | 不行 | .head() / 布尔切片返回普通 DataFrame,to_toolkit() 直接 AttributeError |
| 依赖 | 需已装 financetoolkit | 本库已把它设为直接依赖,因此通常已经具备 |
to_toolkit() 负责「这些标的的行情与财务长什么样」。两者是两件事、两个上游,任一侧故障都会让整条链路断掉——排查时先分清是哪一侧。不要问「哪个工具更好」,要问「这一步该谁做」。下表按任务拆分,并把实测到的失败点写在同一行。
| 任务 | FinanceDatabase | yfinance | AKShare / OpenBB | FinanceToolkit | 典型失败点 |
|---|---|---|---|---|---|
| 证券名录与元数据 | 强(30 万+条) | 弱(按代码查) | 部分支持 | 弱 | 本库字段缺失率差异大,先跑 isna().mean() |
| 按国家 / 行业 / 市值筛选 | 强 | 不支持 | 依赖各自数据源 | 不支持 | 取值写错会静默返回空表 |
| 历史行情 | 不提供 | 支持部分市场 | 支持部分市场 | 支持(含缓存) | 本库不提供,必须换工具 |
| 财报与估值指标 | 不提供 | 有限支持 | 视市场而定 | 强 | 免 key 走 Yahoo 只有 5 年数据 |
| A 股 / 港股代码映射 | 提供后缀代码(.SS/.SZ/.HK) | 用同一套后缀 | 中国市场更友好 | 依赖行情源 | 各源后缀写法并不完全一致 |
| 离线可用性 | 支持(需自行缓存数据文件) | 不支持 | 部分支持 | 支持缓存 | 本库默认每次都重新下载 |
| 回测与策略验证 | 不提供 | 不提供 | 不提供 | 不提供 | 需另接回测框架,注意复权与成本口径 |
不是。它是证券代码与元数据库,官方说明中明确不提供行情价格;历史价格、实时报价一类需求需要另接行情源。以官方 README 与仓库说明为准。
该库的覆盖范围以官方声明为准,A 股并不完整,直接用国内标的试查最可靠。如果研究范围主要在国内市场,更适合用面向国内市场的财经数据接口;本机已核验的金融数据技能路线里也有覆盖 A 股的技能方向,但与本项目并无集成关系。
可以。查询结果就是 pandas DataFrame,能存成 CSV、写入数据库或直接接进下游管道。建议在导出文件名里带上采集时间,方便区分不同批次的快照。如果下游是数据库,导入前先去重,避免同一标的被重复写入。
它的定位是「证券清单与元数据」这一层:把标的、代码、市场、行业整理清楚,价格与基本面交由别的工具承接。这样职责单一,也解释了为什么它适合做数据准备的起步环节。
字段来自上游数据源,可能滞后于实时市场;官方并未承诺实时性。用它做筛选时,建议记录采集时间并在结论里说明口径,涉及时效敏感的用途要另行核对。另外不同上游源的统计口径可能不同,跨源比较前先确认字段定义一致。
仓库 README 声明为 MIT 许可,正式使用请以仓库 LICENSE 文件原文为准;同时注意证券清单的数据来自上游数据源,数据条款可能与代码许可不同,商用或再分发前需单独核对上游条款。