FlatBuffers Python 使用指南库结构、读写与 NumPy 向量加速【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffers本篇指南基于 FlatBuffers 官方文档中 Python 语言章节系统讲解如何在 Python 中读写 FlatBuffers 二进制数据包括 Python 运行库在仓库中的位置、flatc --python代码生成与项目集成方式、GetRootAsMonster读取流程、AsNumpy()向量零拷贝加速以及文本解析的能力边界。读完本文你将能够独立完成编写 schema → 生成 Python 代码 → 序列化/反序列化 → 用 NumPy 批量读取标量向量的完整链路。开始之前需要掌握的前置知识本文是 Tutorial 的 Python 语言专项补充聚焦 Python 使用上的细节与差异。建议在阅读本文前先完成以下准备工作通读 Tutorial其中包含全部支持语言含 Python的完整使用指南覆盖 schema 编写、flatc编译、应用集成、序列化与反序列化全流程阅读 Building 文档并构建出flatc编译器熟悉 Using the schema compiler 与 Writing a schema掌握flatc的命令行用法与.fbsschema 语法。# 在仓库根目录下用 CMake 构建 flatcUnix 环境 cmake -G Unix Makefiles make flatc构建完成后flatc可执行文件位于仓库根目录tests/PythonTest.sh正是以../flatc方式引用它。FlatBuffers Python 库代码位置Python 运行时库的源码位于仓库的python/flatbuffers目录由以下核心模块组成模块文件职责python/flatbuffers/builder.pyBuilder类序列化核心管理字节缓冲与 vtablepython/flatbuffers/table.pyTable类只读访问器基类提供向量/字符串/联合的读取python/flatbuffers/encode.py标量编解码与GetVectorAsNumpy实现python/flatbuffers/number_types.py各标量类型的 packer 与 NumPy dtype 映射python/flatbuffers/packer.py基于struct的小端二进制打包python/flatbuffers/compat.pyPython 2/3 兼容层与 NumPy 可选依赖探测python/flatbuffers/flexbuffers.pyFlexBuffers 变长格式支持python/flatbuffers/util.py工具函数如GetBufferIdentifier该目录还提供标准的打包配置python/setup.py当前版本号25.12.19与 python/setup.cfg可通过pip install flatbuffers安装或直接将python目录加入PYTHONPATH使用仓库内源码。测试 Python 库Python 库的测试代码位于 tests/py_test.py覆盖了对象 API、向量、联合、gRPC、NumPy 向量等大量场景。运行测试使用 tests/PythonTest.sh 脚本# 需已安装 Python脚本会自动探测可用的解释器 cd tests ./PythonTest.sh该脚本会依次完成以下工作详见 tests/PythonTest.sh用仓库内flatc针对monster_test.fbs、monster_extra.fbs、arrays_test.fbs、nested_union_test.fbs、service_test.fbs等 schema 生成 Python 代码生成命令带有--gen-object-api、--python-typing、--gen-compare、--gen-onefile、--grpc、--grpc-python-typed-handlers、--no-python-gen-numpy、--python-decode-obj-api-strings等选项依次用python2.6、python2.7、python3、pypy运行 tests/py_test.py若环境中存在并对python3额外运行 tests/py_flexbuffers_test.py若安装了coveragepip install coverage还会以默认 Python 生成覆盖率报告若系统没有任何 Python 解释器则输出 No Python interpreters found 并退出码 1。运行方式示例python3 py_test.py 100 100 100 100 false后四个参数是 vtable 去重、读/写基准测试的次数与开关。在 Python 中使用 FlatBuffersPython 同时支持 FlatBuffers 的读取与写入。整体流程是先用flatc的--python选项从 schema 生成 Python 类然后在业务代码中同时导入 FlatBuffers 运行时库与生成的代码。第一步用 flatc 生成 Python 代码flatc --python monster.fbs生成的文件会按 schema 中的namespace组织成对应的 Python 包例如MyGame/Example目录下的Monster.py、Vec3.py等。以本仓库 samples/monster.fbs 为例其namespace MyGame.Sample;会生成MyGame/Sample/包。也可以像测试脚本那样追加--gen-object-api生成可变的 Object API 与Pack/UnPack方法、--python-typing生成.pyi类型标注文件等选项。第二步读取一个 FlatBuffer 二进制文件import MyGame.Example as example # flatc --python 生成的代码 import flatbuffers # 运行时库 # 将二进制文件读入 bytearray buf open(monster.dat, rb).read() buf bytearray(buf) # 以根对象方式解析 monster example.GetRootAsMonster(buf, 0)随后即可像普通访问器一样读取字段hp monster.Hp() pos monster.Pos()这里的GetRootAsMonster(buf, 0)是flatc生成代码提供的入口函数buf是bytearray形式的二进制数据0是根对象在缓冲中的偏移。读取器底层由 python/flatbuffers/table.py 中的Table类支撑——它保存Bytes与Pos两个状态通过Offset()查询 vtable、Get()解码标量、String()/Vector()解析引用类型并利用GetSlot()在字段缺失时返回 schema 中声明的默认值因此读取过程不产生反序列化副本、无需解析整棵树这正是 FlatBuffers 零拷贝读取特性的体现。写入序列化示例如果需要写入则使用 python/flatbuffers/builder.py 中的Builderimport flatbuffers import MyGame.Sample.Monster import MyGame.Sample.Vec3 import MyGame.Sample.Color import MyGame.Sample.Equipment # 构造 Builder默认初始缓冲 1024 字节需要时会自动扩容 builder flatbuffers.Builder(1024) # 引用类型string、vector、table需先序列化自叶子向根构建 name builder.CreateString(Orc) inv builder.CreateStringVector([0, 1, 2, 3]) # 或用 CreateNumpyVector MyGame.Sample.Monster.Start(builder) MyGame.Sample.Monster.AddPos(builder, MyGame.Sample.Vec3.CreateVec3(builder, 1.0, 2.0, 3.0)) MyGame.Sample.Monster.AddHp(builder, 300) MyGame.Sample.Monster.AddName(builder, name) MyGame.Sample.Monster.AddInventory(builder, inv) MyGame.Sample.Monster.AddColor(builder, MyGame.Sample.Color.Color().Red) orc MyGame.Sample.Monster.End(builder) builder.Finish(orc) # 标记根对象 buf builder.Output() # 必须在 Finish() 之后调用返回 bytearray从源码实现看Builder的几个关键行为值得注意见 python/flatbuffers/builder.py向后构建缓冲从尾部向前写入head指向当前写入位置读取时无需前向解析初始大小与上限Builder(initialSize1024)缓冲可自动增长但受MAX_BUFFER_SIZE 2**312 GiB硬上限约束超过会抛出BuilderSizeErrorvtable 去重WriteVtable()会将新 vtable 与已记录的self.vtables比较内容相同的对象复用已有 vtable从而显著压缩重复结构的内存占用Output()前必须Finish()否则抛出BuilderNotFinishedErrorOutput()返回的是Bytes[head:]切片即实际已写入的数据序列化过程的状态机还会抛出IsNotNestedError、IsNestedError、StructIsNotInlineError、EndVectorLengthMismatched等异常用于在嵌套/顺序错误时给出明确提示。对 NumPy 数组的支持Python 库对标量向量提供 NumPy 数组访问支持。相比逐元素迭代这可以带来数量级的性能提升尤其在解包大型嵌套 FlatBuffers 时优势明显。生成的代码会为每个标量向量提供一个vector nameAsNumpy()方法。以 Monster 示例的inventory向量为例inventory monster.InventoryAsNumpy() # inventory 是一个 numpy 数组类型为 np.dtype(uint8)而不是inventory [] for i in range(monster.InventoryLength()): inventory.append(int(monster.Inventory(i)))从实现看AsNumpy()的底层链路是生成的访问器调用Table.GetVectorAsNumpy()见 python/flatbuffers/table.py先定位向量起始位置与长度再按字段类型映射到 NumPy dtype映射表在 python/flatbuffers/number_types.py 的to_numpy_type最终在 python/flatbuffers/encode.py 中通过np.frombuffer(buf, dtypenumpy_type, countcount, offsetoffset)构造数组。也就是说返回的 NumPy 数组是原缓冲区的零拷贝视图view——修改该数组会直接改动底层Bytes同时避免了逐元素 Python 循环的开销。NumPy 不是必需依赖NumPy 是可选依赖。运行库在 python/flatbuffers/compat.py 的import_numpy()中通过探测模块是否存在来决定是否导入存在则正常加载不存在则置为None。若系统未安装NumPy调用任何*AsNumpy()方法都会抛出NumpyRequiredForThisFeature异常该异常继承自RuntimeError定义于 python/flatbuffers/compat.py因此只有当你确实需要 NumPy 向量访问时才需要额外安装pip install numpy官方测试 tests/py_test.py 对此做了双向验证当 NumPy 存在时断言InventoryAsNumpy().dtype np.dtype(u1)且sum() 10当 NumPy 不存在时则断言访问AsNumpy()会抛出NumpyRequiredForThisFeature。该特性同时覆盖多种标量类型与固定长度数组测试中还包含TestarrayofboolsAsNumpy、VectorOfLongsAsNumpy、VectorOfDoublesAsNumpy、VectorOfEnumsAsNumpy以及test_create_numpy_vector_*系列用例对应CreateNumpyVector写入 API说明布尔、长整型、浮点、枚举向量乃至arrays_test的定长数组都可享受同样的零拷贝批量访问能力。文本解析JSON/Schema说明目前 Python 库不支持直接从 Python 解析文本格式包括.fbsschema 与 JSON 数据。如果需要文本解析能力官方文档给出的路径是通过 SWIG 或 ctypes 包装并调用 C 解析器或者直接查阅 C 文档docs/source/languages/cpp.md了解文本解析的完整实现。这也意味着 Python 侧的常规使用方式是schema 文本交由flatc编译为二进制flatc文件或直接生成代码JSON 与二进制之间的转换可借助flatc -t --json等命令完成而运行时只处理二进制格式。小结库位置运行时库在 python/flatbuffers可通过pip install flatbuffers安装或以PYTHONPATH引用仓库源码读写流程flatc --python monster.fbs生成代码 → 导入flatbuffers与生成包 → 读取用GetRootAsMonster(buf, 0)写入用BuilderStart/Add/EndFinish()Output()性能关键点标量向量用nameAsNumpy()获得零拷贝 NumPy 视图避免逐元素迭代NumPy 为可选依赖缺失时访问会抛NumpyRequiredForThisFeature能力边界文本schema/JSON解析需借助 C 解析器SWIG/ctypesPython 库本身不提供。如需完整的逐语言对照示例与 schema 类型系统讲解请继续阅读 Tutorial、Writing a schema 与 Using the schema compiler。【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考