feat(python): support configure field meta for python#3091
Merged
chaokunyang merged 6 commits intoapache:mainfrom Dec 25, 2025
Merged
feat(python): support configure field meta for python#3091chaokunyang merged 6 commits intoapache:mainfrom
chaokunyang merged 6 commits intoapache:mainfrom
Conversation
LiangliangSui
approved these changes
Dec 25, 2025
48c588f to
0cfac8c
Compare
0cfac8c to
8134a43
Compare
Add `from __future__ import annotations` to field.py and struct.py to support Python 3.9+ type hints syntax (dict[str, ...], list[...]) on Python 3.8.
…orts Only export `field` and `ForyFieldMeta` as public API. Internal functions like `extract_field_meta`, `validate_field_metas`, and `FORY_FIELD_METADATA_KEY` should be accessed via `pyfory.field` module directly if needed.
ForyFieldMeta is an internal implementation detail.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why?
This PR adds field-level metadata configuration support for Python, completing the cross-language field metadata feature across all Fory language implementations (Java, Rust, Go, C++, and now Python).
Field metadata allows users to:
What does this PR do?
1. New
pyfory.field()APIIntroduces a new
pyfory.field()function for fine-grained control over serialization behavior per field:2. TAG_ID Encoding Support
Implements TAG_ID encoding in the xlang serialization protocol:
id >= 0: Uses numeric tag ID (2-bit encoding = 0b11)id = -1: Uses field name with meta string encoding3. Field Header Format
4. Schema Evolution Support
When deserializing data with a different schema than the registered class:
5. Files Changed
New files:
python/pyfory/field.py:pyfory.field()function andForyFieldMetadataclassModified files:
python/pyfory/struct.py: UpdatedDataClassSerializerto support field metadatapython/pyfory/meta/typedef.py: Added TAG_ID to field name resolutionpython/pyfory/meta/typedef_encoder.py: TAG_ID encoding supportpython/pyfory/meta/typedef_decoder.py: TAG_ID decoding supportpython/pyfory/__init__.py: ExportfieldfunctionTest files:
python/pyfory/tests/test_field_meta.py: Comprehensive tests for field metadataRelated issues
#3002
Does this PR introduce any user-facing change?
Yes, introduces the new
pyfory.field()API for field-level metadata configuration.The binary protocol changes (TAG_ID encoding) are already part of the xlang specification and implemented in other languages.
Benchmark
No performance regression expected. TAG_ID encoding is more compact than field name encoding.