Bokeh 序列化终章：深入 `bokeh.core.json_encoder` 与 `serialize

Bokeh 序列化终章深入bokeh.core.json_encoder与serialize_json实现原理【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh导读bokeh.core.json_encoder是 Bokeh 前端BokehJS与 Python 后端之间数据交换的最后一公里——它负责把经过Serializer规范化后的数据表示最终转换为可在网络上传输、被 BokehJS 解析的 RFC-8259 JSON 字符串。本文以该模块的官方 API 参考文档json_encoder.rst为主线结合 json_encoder.py 源码与单元测试系统讲解serialize_json的参数语义、底层PayloadEncoder的实现细节、BOKEH_PRETTY环境变量的优先级规则以及它与bokeh.core.serialization.Serializer的分工边界。读完本文你将掌握 Bokeh 对象序列化的完整链路并能独立使用serialize_json生成紧凑或美化格式的 JSON 载荷。bokeh.core.json_encoder模块定位在 Bokeh 的架构中bokeh.core.json_encoder属于核心基础模块它提供用于将对象序列化为 BokehJS 可消费 JSON 的自定义 JSON 编码器模块 docstring 原话。官方 API 参考文档 json_encoder.rst 通过 Sphinx 的automodule指令自动拉取模块内容并显式声明了公开 API 中的核心函数.. automodule:: bokeh.core.json_encoder .. autofunction:: serialize_json也就是说该模块面向用户的唯一公开入口是serialize_json它也是模块__all__中唯一导出的符号见 json_encoder.py。理解这一模块本质上就是理解serialize_json及其依赖的PayloadEncoder。模块级转换规则Bokeh 对象 → JSON 的九条约定模块 docstringjson_encoder.py开篇就定义了该模块处理各类 Python 对象时的统一转换规则这是理解整个 Bokeh 序列化行为的基础逐条列举如下输入类型转换结果Datetime 值Pythondatetime、Pandas、NumPy 的日期时间自纪元起的毫秒级浮点数TimeDelta值绝对值形式的毫秒级浮点数RelativeDelta值转换为一字典Decimal值转换为浮点数序列PandasSeries、NumPy 数组、Python 序列转换为列表但注意Bokeh Document 内数据源中的数组在别处转换默认走二进制编码格式BokehModel实例通常在整个 Bokeh Document 上下文中序列化若直接经过本接口转换为引用referenceHasProps非 Bokeh Model转换为所有属性与值的key/value 字典Color实例转换为CSS 颜色值其他可序列化对象由Serializer按类型分派见下文需要特别强调的是序列转列表与数据源数组走二进制编码的区别serialize_json本身不执行上述类型转换这些转换由Serializer完成serialize_json只负责把转换后的中间表示压成字符串。serialize_json函数签名与参数语义serialize_json定义在 json_encoder.py签名如下def serialize_json(obj: Any | Serialized[Any], *, pretty: bool | None None, indent: int | None None) - strobj接受普通对象或Serialized包装函数同时接受两种输入任意 Python 可序列化对象bokeh.core.serialization.Serializer返回的Serialized实例.content字段保存编码后的表示.buffers保存二进制缓冲区列表定义见 serialization.py。源码中通过content obj.content if isinstance(obj, Serialized) else obj统一取内容随后交给编码器处理因此两种调用方式等价from bokeh.core.serialization import Serializer from bokeh.core.json_encoder import serialize_json s Serializer() rep s.encode({a: 1}) # 普通编码结果 serialize_json(rep) # 直接传编码结果 serialize_json(s.serialize({a: 1})) # 或传 Serialized 包装pretty是否美化输出True时分隔符使用(,, : )冒号后加空格并启用缩进与换行False默认时分隔符为紧凑的(,, :)输出为无空白的单行字符串更关键的是优先级规则环境变量BOKEH_PRETTY一旦设置将覆盖本参数。这一行为由settings.pretty(pretty)实现底层定义位于 settings.pyPrioritizedSetting(pretty, BOKEH_PRETTY, defaultFalse, dev_defaultTrue)——即默认关闭但开发模式dev下默认开启环境变量优先级最高。indent缩进量None默认时默认不缩进但若prettyTrue且indentNone则自动回退为 2 个空格缩进显式传入整数可自定义缩进宽度例如bokeh json子命令正是通过serialize_json(doc.to_json(), indentargs.indent)把用户指定的缩进透传给该函数见 command/subcommands/json.py。返回值返回类型为str即符合RFC-8259规范的 JSON 字符串。与json.dumps的区别内存缓冲区的处理文档在函数 docstring 的.. note::中明确提醒使用serialize_json并非严格必要。因为Serializer可以配置为产出与标准库json.dumps完全兼容的输出两者的主要差异在于内存缓冲区的处理方式 s Serializer(deferredFalse) # 关闭延迟编码缓冲区内联为 base64 import json json.dumps(s.encode(obj)) # 此时标准库 dumps 也能直接用当Serializer默认以deferredTrue创建时NumPy 数组等大块二进制数据不会立即编码而是被收集为Buffer对象列表.buffers等待后续通过 WebSocket 等二进制通道单独传输serialize_json则会把Buffer就地转换为引用{id: ...}从而让 JSON 载荷保持紧凑且可独立传输。底层实现PayloadEncoder与default钩子serialize_json最终实例化模块内部的PayloadEncoder来完成编码encoder PayloadEncoder(indentindent, separatorsseparators) return encoder.encode(content)PayloadEncoderjson_encoder.py继承标准库json.JSONEncoder构造函数固定了三个关键行为class PayloadEncoder(JSONEncoder): def __init__(self, *, indentNone, separatorsNone): super().__init__(sort_keysFalse, allow_nanFalse, indentindent, separatorsseparators) def default(self, o): if isinstance(o, Buffer): return o.ref else: return super().default(o)逐一解读sort_keysFalse保持字典原始键序不排序。这一点被单元测试test_json_encoder_dict_no_sort明确验证——包含nan键与普通字符串键混合的字典序列化后键的顺序保持插入序test_json_encoder.pyallow_nanFalse禁止输出 JSON 标准之外的NaN/Infinity字面量。因此nan等特殊浮点值必须在Serializer层就被转换为带类型的表示如{type:number,value:nan}再由编码器安全输出default钩子对Buffer实例返回其引用ref即{id: buffer.id}见 serialization.py其余类型交给父类处理。官方示例从编码表示到 JSON 字符串模块 docstring 中给出了端到端示例可直接在 Python 中复现。它展示了np.datetime64被转换为毫秒时间戳、np.arange(3)数组被编码为带ndarray元信息的二进制 base64 表示 import numpy as np from bokeh.core.serialization import Serializer from bokeh.core.json_encoder import serialize_json s Serializer() obj dict(bnp.datetime64(2023-02-25), anp.arange(3)) rep s.encode(obj) rep { type: map, entries: [ (b, 1677283200000.0), (a, { type: ndarray, array: {type: bytes, data: Buffer(idp1000, datamemory at 0x7fe5300e2d40)}, shape: [3], dtype: int32, order: little, }), ], } serialize_json(rep) {type:map,entries:[[b,1677283200000.0],[a,{type:ndarray,array: {type:bytes,data:AAAAAAEAAAACAAAA},shape:[3],dtype:int32,order:little}]]}注意np.datetime64(2023-02-25)被转换为1677283200000.0毫秒级浮点正是模块 docstring 转换规则表的第一条约定np.arange(3)以延迟缓冲区的形式存在而serialize_json将其Buffer就地转成 base64 字符串内联输出。单元测试验证三组关键行为仓库单元测试 test_json_encoder.py 从三个维度锁定了函数行为可作为理解与回归验证的依据1.test_json_encoder标量列表与美化输出[None, True, False, -128, -1, 0, 1, 128, nan]序列化后nan被输出为{type:number,value:nan}prettyTrue时输出变为多行、两空格缩进、冒号后带空格的格式。该测试同时断言serialize_json(rep0.content)与serialize_json(rep0)传入整个Serialized结果一致验证了包装解包的等价性。2.test_json_encoder_bytes内联缓冲区的 base64 编码使用Serializer(deferredFalse)时字节串buvw的缓冲区被 gzip 压缩压缩级别取自settings.compression_level()后做 base64 编码内联进 JSON输出形如{type:map,entries:[[key,{type:bytes,data:H4sIAAAAAAAACwvJyCxWAgB7L7bNAgAAAA}]]}。3.test_json_encoder_dict_no_sort键序保持混入nan键的字典保持插入顺序验证了sort_keysFalse的设计意图。真实应用场景协议消息封套与bokeh json命令serialize_json并非孤立工具它在 Bokeh 的运行时与命令行中都有实际应用协议消息封套序列化Bokeh 服务端协议bokeh.protocol在构造消息时用serialize_json将header、content与buffers的 id 列表打包成单条 JSON 封套见 protocol/message.pydef _serialize_envelope(self) - str: return serialize_json({ header: self.header, content: self.content, buffers: [buffer.id for buffer in self._buffers], })bokeh json子命令该命令将文档导出为 JSON 文件并把命令行--indent参数直接透传给serialize_json见 command/subcommands/json.py实现了用户可读的美化输出。小结serialize_json的使用要点先序列化、后编码对于含 Bokeh 模型、NumPy 数组、日期时间等复杂类型的对象务必先用Serializer编码再把结果或其.content交给serialize_json直接传入原始 Python 对象只能得到普通 JSON不会做任何 Bokeh 特定转换紧凑输出是默认未设置BOKEH_PRETTY时pretty默认为False输出无空白的最小化 JSON适合网络传输环境变量优先BOKEH_PRETTY1会覆盖代码中的prettyFalse参数这在调试服务端协议消息时尤为实用indentNoneprettyTrue会自动使用 2 空格缩进无需手动指定缓冲区策略可切换需要与json.dumps完全兼容、将二进制数据内联输出时使用Serializer(deferredFalse)默认的deferredTrue则配合serialize_json将缓冲区转为引用或 base64 内联兼顾 WebSocket 二进制传输与 JSON 自包含两种诉求。进一步阅读模块源码 json_encoder.py、序列化核心 serialization.py、行为测试 test_json_encoder.py以及BOKEH_PRETTY的设置定义 settings.py。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Bokeh 序列化终章：深入 `bokeh.core.json_encoder` 与 `serialize_json` 实现原理

相关推荐

UnoCSS Extracting 机制完全解析：构建时按需扫描、Safelist 与 Blocklist 工程化实践

NV12视频格式与GStreamer播放器开发指南

TiDB 保存点实操：长事务部分回滚避坑

更多资讯

Pydantic Evals 数据集序列化完全指南：YAML/JSON 持久化、Schema 生成与自定义 Evaluator

数据可视化基础：从图表类型到商业决策应用

DenseNet迁移学习实战：水果五分类模型构建与优化

AI教材生成工具：核心技术、应用场景与实操指南

EKF-SLAM可观测性分析与不一致性改进研究

FastAPI框架入门：高性能Python Web开发实战

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？