This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new f518059d3f 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
f518059d3f is described below
commit f518059d3f13a0190ad39eae61f79d93c19f7d1a
Author: chaokunyang <[email protected]>
AuthorDate: Sat May 2 04:26:03 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/python/cross-language.md | 15 +++++++++++----
docs/guide/python/field-configuration.md | 32 +++++++++++++++++++++++++++++++-
2 files changed, 42 insertions(+), 5 deletions(-)
diff --git a/docs/guide/python/cross-language.md
b/docs/guide/python/cross-language.md
index 3064538365..fbe3e90bc3 100644
--- a/docs/guide/python/cross-language.md
+++ b/docs/guide/python/cross-language.md
@@ -99,16 +99,23 @@ Use pyfory type annotations for explicit cross-language
type mapping:
```python
from dataclasses import dataclass
+from typing import Dict, List
import pyfory
@dataclass
class TypedData:
- int_value: pyfory.int32 # 32-bit integer
- long_value: pyfory.int64 # 64-bit integer
- float_value: pyfory.float32 # 32-bit float
- double_value: pyfory.float64 # 64-bit float
+ int_value: pyfory.int32 # 32-bit integer
+ long_value: pyfory.int64 # 64-bit integer
+ float_value: pyfory.float32 # 32-bit float
+ double_value: pyfory.float64 # 64-bit float
+ values: Dict[pyfory.fixed_int32, List[pyfory.tagged_int64]]
```
+Nested collection annotations are part of the field schema. For example,
+`Dict[pyfory.fixed_int32, List[pyfory.tagged_int64]]` writes map keys as fixed
int32 values and the
+nested list elements as tagged int64 values. Compatible-mode reads consume
bytes with the remote
+schema metadata, then assign only when the decoded value safely satisfies the
local schema.
+
## Reduced-Precision Types
`pyfory.serialization` exports Cython-only carrier types for xlang
reduced-precision values:
diff --git a/docs/guide/python/field-configuration.md
b/docs/guide/python/field-configuration.md
index 4879133069..1e4e8f35ca 100644
--- a/docs/guide/python/field-configuration.md
+++ b/docs/guide/python/field-configuration.md
@@ -278,6 +278,9 @@ class FloatingPoint:
| `pyfory.int16` | fixed | 2 bytes |
| `pyfory.int32` | varint | 1-5 bytes |
| `pyfory.int64` | varint | 1-10 bytes |
+| `pyfory.fixed_int32` | fixed | 4 bytes |
+| `pyfory.fixed_int64` | fixed | 8 bytes |
+| `pyfory.tagged_int64` | tagged | 1-9 bytes |
| `pyfory.uint8` | fixed | 1 byte |
| `pyfory.uint16` | fixed | 2 bytes |
| `pyfory.uint32` | varint | 1-5 bytes |
@@ -292,7 +295,32 @@ class FloatingPoint:
- `varint`: Best for values that are often small (default for
int32/int64/uint32/uint64)
- `fixed`: Best for values that use full range (e.g., timestamps, hashes)
-- `tagged`: When type information needs to be preserved (uint64 only)
+- `tagged`: When type information needs to be preserved (int64/uint64 only)
+
+## Nested Container Type Annotations
+
+Integer encoding aliases can be used inside declared collection schemas. Fory
uses the declared
+field schema for every nested element, key, and value in both pure Python and
Cython modes:
+
+```python
+from dataclasses import dataclass, field
+from typing import Dict, List
+import pyfory
+
+
+@dataclass
+class Counters:
+ values: Dict[pyfory.fixed_int32, List[pyfory.tagged_int64]] =
field(default_factory=dict)
+```
+
+For `values`, map keys are written as fixed-width int32 values and each nested
list element is
+written as tagged int64. Runtime type inference is used only for dynamic or
unknown container
+schemas.
+
+In compatible mode, readers consume field bytes using the remote schema
metadata. Python assigns the
+decoded value only when it can safely satisfy the local declared schema.
Different integer encodings
+in the same signedness and width domain are compatible, and same-signedness
narrowing is assigned
+only after range validation.
## Complete Example
@@ -481,6 +509,8 @@ class User:
| `pyfory.field(dynamic=False)` | Skip type info (use declared
type) |
| `Optional[T]` | Type hint for nullable fields
|
| `pyfory.int32`, `pyfory.int64` | Signed integers (varint
encoding) |
+| `pyfory.fixed_int32`, `pyfory.fixed_int64` | Fixed-size signed
|
+| `pyfory.tagged_int64` | Tagged encoding for int64
|
| `pyfory.uint32`, `pyfory.uint64` | Unsigned integers (varint
encoding) |
| `pyfory.fixed_uint32`, `pyfory.fixed_uint64` | Fixed-size unsigned
|
| `pyfory.tagged_uint64` | Tagged encoding for uint64
|
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
