Add C++ and Python TsFile properties support

[ColinLeeo]

Summary

Add file-level TsFile properties read/write support to the C++ and Python APIs.

Properties can be added or replaced while a writer is open, including after flush(). Property values are stored as binary data and remain compatible with Java's Map<String, byte[]> representation.

Changes

C++

• Add TsFilePropertyValue and TsFileProperties.
• Add property setters to TsFileWriter and TsFileTableWriter.
• Add TsFileReader::get_tsfile_properties().
• Preserve the distinction between:
  • null values
  • non-null zero-length values
  • arbitrary binary values
• Support embedded NUL and non-text bytes without truncation.
• Copy property values immediately and replace previous values when the same key is used.
• Allow properties to be changed after flush().
• Reject modifications after the writer is closed.
• Ensure system-generated encryptLevel, encryptType, and encryptKey properties override custom properties with the same names.
• Replace the raw-pointer property map in TsFileMeta with value-based ownership.

C wrapper

• Add length-aware binary property setter APIs.
• Add a reader API returning explicit key/value lengths and an is_null field.
• Add tsfile_free_tsfile_properties() for releasing reader results.
• Add argument validation, size limits, allocation failure handling, and partial-allocation cleanup.

Python

• Add add_tsfile_property(key: str, value: bytes) to:
  • TsFileWriter
  • TsFileTableWriter
• Add TsFileReader.get_tsfile_properties().
• Return properties as dict[str, bytes | None].
• Accept exact bytes values only; strings and other bytes-like objects are not converted implicitly.
• Keep TsFileTreeWriter unchanged.

Compatibility

The existing TsFile footer format is unchanged:

• null value: length -1
• non-null value: byte length followed by the original bytes

No property type tag is added. Applications are responsible for using an explicit, portable byte encoding for integers, floating-point values, and structures.

This change does not support modifying properties in an already closed TsFile.

Tests

Added coverage for:

• binary values and embedded NUL bytes
• null versus empty values
• duplicate-key replacement
• property updates after flush()
• closed-writer rejection
• system property precedence
• C wrapper lengths, validation, and result cleanup
• both Python writer APIs
• Python type validation and bytes | None reader results

Validation completed:

• ./mvnw spotless:check -P with-cpp
• ./mvnw -P with-cpp clean verify
  • 738 C++ tests passed
• ./mvnw -P with-python clean verify
  • 738 C++ tests passed
  • 172 Python tests passed

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds file-level TsFile property support across C++, the C wrapper, and Python APIs, enabling binary property read/write with null vs empty distinction and compatibility with Java’s Map<String, byte[]>.

Changes:

• Introduces TsFilePropertyValue / TsFileProperties, wires property storage into writer/metadata serialization and reader access.
• Extends C wrapper with length-aware setter and reader APIs plus explicit free function.
• Adds Python writer/reader bindings plus tests and documentation updates.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
python/tsfile/tsfile_writer.pyx	Adds Python writer API to set binary file properties via C wrapper.
python/tsfile/tsfile_table_writer.py	Delegates table-writer property setting to underlying writer.
python/tsfile/tsfile_reader.pyx	Adds Python reader API to retrieve properties as `dict[str, bytes
python/tsfile/tsfile_cpp.pxd	Declares new C wrapper structs/enums and functions for properties.
python/tests/test_tsfile_properties.py	Adds Python tests for round-trip, types, binary/NUL behavior, and closed-writer rejection.
python/README.md	Documents Python file-level properties API and encoding guidance.
python/README-zh.md	Chinese documentation for Python file-level properties.
cpp/test/writer/tsfile_properties_test.cc	Adds C++ tests for property semantics and system property precedence.
cpp/test/writer/table_view/tsfile_writer_table_test.cc	Adds table-writer delegation test for properties.
cpp/test/cwrapper/cwrapper_properties_test.cc	Adds C wrapper tests for length-aware round-trips, validation, and cleanup.
cpp/test/common/tsfile_common_test.cc	Updates metadata serialization test to new value-owned property model.
cpp/src/writer/tsfile_writer.h / .cc	Adds C++ writer public setters for properties.
cpp/src/writer/tsfile_table_writer.h / .cc	Adds C++ table-writer setters delegating to writer with closed checks.
cpp/src/reader/tsfile_reader.h / .cc	Adds C++ reader API to return file-level properties.
cpp/src/file/tsfile_io_writer.h / .cc	Stores properties in IO writer; serializes them into TsFileMeta, enforces system property override.
cpp/src/cwrapper/tsfile_cwrapper.h / .cc	Adds C APIs for setting/reading properties plus memory-free helper and validation.
cpp/src/common/tsfile_common.h / .cc	Introduces TsFilePropertyValue and updates meta (de)serialization format handling.
cpp/README.md	Documents C++ file-level properties usage.
cpp/README-zh.md	Chinese documentation for C++ file-level properties.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated no new comments.

Suppressed comments (1)

cpp/src/reader/bloom_filter.cc:261

• BloomFilter::deserialize_from() returns immediately when filter_data_bytes_len == 0, which matches the new encoding but can break backward compatibility with files produced by the previous code path (which still wrote size_ and hash_func_count_ after a zero-length bitset). In that legacy case, the extra fields would remain unread and shift the subsequent TsFileMeta parsing. Consider using ByteStream::read_pos() / set_read_pos() to detect-and-consume the legacy fields when present, while preserving the new 1-byte empty encoding.

    } else if (filter_data_bytes_len == 0) {
        size_ = 0;
        hash_func_count_ = 0;
        return E_OK;
    } else if (filter_data_bytes_len > in.remaining_size()) {