README-zh.md

TsFile Python 文档

简介

本目录包含 TsFile 的 Python 实现版本。Python 版本基于 C++ 版本构建，并通过 Cython 包将 TsFile 的读写能力集成到 Python 环境中。用户可以像在 Pandas 中使用 read_csv 和 write_csv 一样，方便地读取和写入 TsFile。

源代码位于 ./tsfile 目录。 以 .pyx 和 .pyd 结尾的文件为使用 Cython 编写的封装代码。 tsfile/tsfile.py 中定义了一些对用户开放的接口。

你可以在 ./examples/examples.py 中找到读写示例。

---

如何贡献

建议使用 pylint 对 Python 代码进行检查。

目前尚无合适的 Cython 代码风格检查工具，因此 Cython 部分代码应遵循 pylint 所要求的 Python 代码风格。

功能列表

• 在 pywrapper 中调用 TsFile C++ 版本实现的批量读取接口。
• 支持将多个 DataFrame 写入同一个 TsFile 文件。

---

构建

在构建 TsFile 的 Python 版本之前，必须先构建 TsFile C++ 版本，因为 Python 版本依赖于 C++ 版本生成的共享库文件。

使用 Maven 在根目录构建

mvn -P with-cpp,with-python clean verify

使用 Python 命令构建

python setup.py build_ext --inplace

文件级 Properties

TsFileWriter 和 TsFileTableWriter 可以在打开期间写入二进制 property。 setter 仅接受 bytes。reader 返回 dict[str, bytes | None]，并区分 null 与 零长度 bytes。

with TsFileWriter("example.tsfile") as writer:
    writer.add_tsfile_property("binary-property", b"\x01\x00\xff")

with TsFileReader("example.tsfile") as reader:
    properties = reader.get_tsfile_properties()

Property value 不携带数据类型；保存数字或结构体时应使用明确、可跨语言的字节编码。