bokeh.sampledata 完全指南：数据集模块的安装方式、代理加载机制与全部内置数据集目录

bokeh.sampledata 完全指南：数据集模块的安装方式、代理加载机制与全部内置数据集目录

【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh

bokeh.sampledata是 Bokeh 官方提供的"随取随用"数据集入口，仓库中绝大多数示例脚本和文档教程都依赖它来快速获取示例数据，而不必自己准备 CSV 文件。本文围绕官方 API 参考页 sampledata.rst 所登记的全部数据集模块展开：先讲清楚它的安装前提与版本约束，再结合 src/bokeh/sampledata/init.py 的源码解析其"惰性代理（shim）"加载机制，最后给出完整数据集目录及各数据集在官方示例中的真实用法，帮助你把示例代码改造成自己的数据管线。

模块定位：示例与文档的公共数据底座

官方文档对该模块的定义非常直接（见 src/bokeh/sampledata/init.py 的模块 docstring）：

Thebokeh.sampledatamodule exposes datasets that are used in examples and documentation. Some datasets require separate installation.

也就是说，它的服务对象有两类：

1. 仓库中的示例脚本（examples/目录）：例如 parallel_plot.py 用from bokeh.sampledata.autompg import autompg_clean as df直接取到清洗好的 auto-mpg 数据表；
2. 交互式教程与文档：如 box_annotation.py 中的from bokeh.sampledata.glucose import data、polygon_annotation.py 中的from bokeh.sampledata.stocks import GOOG、span.py 中的from bokeh.sampledata.daylight import daylight_warsaw_2013。

这些示例代码之所以能"一行 import 就有 DataFrame"，靠的正是 sampledata 模块的代理机制（下文详述）。

安装方式：独立包 bokeh_sampledata

数据集本体不随 Bokeh 主包分发，而是放在独立 PyPI 包bokeh_sampledata中。这是本模块最重要的使用前提：

pip install bokeh_sampledata

也可以走 Bokeh 的可选依赖组方式（见 pyproject.toml 的[project.optional-dependencies]）：

pip install bokeh[sampledata] # 仅数据集 pip install bokeh[all] # sampledata + extra + export

其中sampledata依赖组声明为bokeh_sampledata >=2025.0，与all组合的关系为bokeh[sampledata,extra,export]。

版本约束的源码实现

src/bokeh/sampledata/init.py 在模块导入时做两道检查：

1. 缺失检查：import bokeh_sampledata失败时立即抛出RuntimeError，提示 "The separate bokeh_sampledata is needed in order to use the sampledata module. Install with 'pip install bokeh_sampledata'."——即未安装时不是静默失败，而是给出可操作的报错信息；
2. 版本检查：定义常量SAMPLEDATA_MIN_VERSION = "2025.0"，若已安装版本低于该值，则通过bokeh.util.warnings发出BokehUserWarning，建议使用pip install -U bokeh_sampledata升级，以保证"all examples properly"运行。

这两段逻辑意味着：如果你的示例脚本能跑通但版本告警出现，通常只影响部分新示例（依赖新字段的数据集），升级独立包即可，无需动 Bokeh 主包。

加载机制解析：每个子模块其实是一个"代理壳"

阅读参考页时容易产生一个疑问：bokeh/sampledata/目录下有 30 多个同名.py文件，它们真的存放数据吗？

答案是否定的。以 src/bokeh/sampledata/iris.py 为例，整个文件只有两行核心代码：

from . import _create_sampledata_shim __getattr__, __dir__, __doc__ = _create_sampledata_shim(__name__)

其余anscombe.py、stocks.py、us_states.py等 40 余个文件（每个 9 行左右）结构完全相同。真正的工厂函数_create_sampledata_shim位于 src/bokeh/sampledata/init.py，其逻辑可以概括为三步：

1. import_module(f"bokeh_sampledata.{mod_name.split('.')[-1]}")——按需导入独立包中同名的数据模块，例如bokeh.sampledata.iris对应bokeh_sampledata.iris；
2. 闭包函数__getattr__(name)转发为getattr(mod, name)，实现"取什么属性查什么属性"的惰性转发——只有在你真正执行from bokeh.sampledata.iris import data时才会触发实际的数据加载；
3. 同步转发__dir__（决定dir()/ 自动补全的可用成员列表）和__doc__（让文档的automodule指令能抓取到数据模块的 docstring 作为参考页正文）。

这套"shim 壳 + 惰性代理"设计带来三个实际收益：

• 目录可发现性：IDE 与import bokeh.sampledata.xxx的静态解析都成立，模块路径稳定；
• 按需加载：import bokeh.sampledata.iris并不会立即把其他数据集读进内存；
• 数据与框架解耦：数据集版本可以独立于 Bokeh 主包演进，由SAMPLEDATA_MIN_VERSION单一常量守住兼容下限。

类型提示：.pyi 桩文件

由于数据在外部包中，仓库为类型检查器提供了桩（stub）。src/typings/下有 bokeh_sampledata/init.pyi，仅声明包级属性__version__: str；而模块级类型则直接放在bokeh/sampledata/目录内，与同名.py壳文件并存：

• movies_data.pyi：movie_path: str——声明movies_data模块对外暴露一个文件路径字符串；
• sample_superstore.pyi：data: DataFrame（from pandas import DataFrame）——声明sample_superstore.data是一个 pandas DataFrame。

如果你的编辑器对bokeh.sampledata.xxx的属性补全不满意，检查这两个.pyi是否同步（其余模块的文档字符串与成员列表由代理机制直接从bokeh_sampledata运行时转发，automodule生成的参考页同理）。

完整数据集模块目录

以下是官方参考页 sampledata.rst 登记的全部子模块，均对应src/bokeh/sampledata/下的同名.py代理文件，导入后转发到bokeh_sampledata同名模块：

提示：源码目录中还存在参考页未列出的 cycling.py 代理文件，属于文档滞后于代码的情形；以dir(bokeh.sampledata)运行时转发结果为准。

官方示例中的真实用法

以下示例均来自examples/目录，展示了 sampledata 属性直接充当绘图数据的典型形态：

# 并行坐标图：直接拿清洗后的 DataFrame from bokeh.sampledata.autompg import autompg_clean as df # 注释图形示例：血糖时序 from bokeh.sampledata.glucose import data # 多边形注释：股票数据 from bokeh.sampledata.stocks import GOOG # 跨度注释：华沙 2013 年日照 from bokeh.sampledata.daylight import daylight_warsaw_2013 # 须线图：autompg 第二版数据 from bokeh.sampledata.autompg2 import autompg2 as df

（分别见 parallel_plot.py、box_annotation.py、polygon_annotation.py、span.py、whisker.py。）

另外 examples/models/daylight.py 展示了from bokeh.sampledata import ...的包级导入写法。

测试体系如何处理 sampledata 的可选性

由于bokeh_sampledata是可选依赖，测试套件必须优雅跳过相关检查。在 tests/codebase/test_python_execution_with_OO.py 中可以看到：

if not is_installed("bokeh_sampledata"): SKIP.append("bokeh.sampledata")

即当独立包未安装时，bokeh.sampledata被加入python -OO（丢弃 docstring）执行测试的跳过列表；tests/codebase/test_no_tornado_common.py 也做同样的条件豁免。同时 pyproject.toml 注册了 pytest marker：sampledata: a test for bokeh.sampledata，用于标记专门针对该模块的测试。这说明在 CI 环境中可以按需装/不装该包来隔离数据集相关测试。

实践建议与常见问题

• 报 RuntimeError 提示需要独立包：说明当前环境没装bokeh_sampledata，执行pip install bokeh_sampledata即可；注意报错来自模块导入时，任何import bokeh.sampledata都会触发。
• 出现BokehUserWarning版本过旧：独立包版本低于2025.0，执行pip install -U bokeh_sampledata；这不会破坏已运行的旧示例，但新示例可能缺少数据字段。
• 需要 DataFrame 语义的场景：优先选择 sample_superstore.pyi 声明为pandas.DataFrame的sample_superstore.data等表格型模块；而movies_data只暴露movie_path路径字符串，需要自行加载。
• 只读原则：仓库中src/bokeh/sampledata/下的.py文件是代理壳，不要往里塞数据；数据归属bokeh_sampledata包，类型调整可参考movies_data.pyi、sample_superstore.pyi的桩文件写法。

总结：bokeh.sampledata用一套极薄的"代理壳"把 40 余个常用数据集统一挂在bokeh.命名空间下，通过独立包分发、版本下限常量与运行时双检查保证兼容性，并通过automodule文档指令把数据包的 docstring 直接渲染成 API 参考页。掌握这一机制后，你既能快速读懂任何官方示例的数据来源，也能在自己的教程中沿用"import 即得数据"的惯例。

【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh