Skip to main content
Version: dev

Configuration

This page covers Python Fory instance configuration. pyfory.Fory() defaults to xlang mode with compatible schema evolution. Native mode is selected explicitly with xlang=False and also defaults to compatible schema evolution.

Fory Class​

The main serialization interface:

class Fory:
    def __init__(
        self,
        xlang: bool = True,
        ref: bool = False,
        strict: bool = True,
        compatible: Optional[bool] = None,
        max_depth: int = 50,
        max_type_fields: int = 512,
        max_type_meta_bytes: int = 4096,
        max_schema_versions_per_type: int = 10,
        max_average_schema_versions_per_type: int = 3,
        max_graph_memory_bytes: int = 128 * 1024 * 1024,
        max_unbacked_container_items: int = 8192,
        policy: DeserializationPolicy = None,
        field_nullable: bool = False,
        meta_compressor=None,
    )

ThreadSafeFory Class​

Thread-safe serialization interface using a pooled wrapper:

class ThreadSafeFory:
    def __init__(
        self, fory_factory=None, **kwargs
    )

Parameters​

ParameterTypeDefaultDescription
xlangboolTrueUse xlang mode. Set False for Python native mode.
refboolFalseEnable reference tracking for shared/circular references. Disable for better performance if your data has no shared references.
strictboolTrueRequire registration before loading application classes. Compatible unknown Structs use the data-only UnknownStruct carrier.
compatiblebool | NoneNoneSchema evolution mode. None enables compatible mode in both xlang and native mode. Set False only when every reader and writer uses the same schema.
max_depthint50Maximum deserialization depth for security, preventing stack overflow attacks.
max_type_fieldsint512Maximum fields accepted in one received remote struct metadata body.
max_type_meta_bytesint4096Maximum encoded body bytes accepted for one received TypeDef body, excluding the 8-byte header and any extended-size varint.
max_schema_versions_per_typeint10Maximum accepted remote metadata versions for one logical type.
max_average_schema_versions_per_typeint3Average accepted remote metadata versions across accepted remote types. The effective global floor is 8192 schemas.
max_graph_memory_bytesint134217728Approximate graph-memory gate for one root deserialization. Explicit non-positive values are rejected.
max_unbacked_container_itemsint8192Maximum collection elements and map entries whose repeated reads are not backed by input progress. Zero is strict.
policyDeserializationPolicy | NoneNoneDeserialization policy used for security checks. Strongly recommended when strict=False.
field_nullableboolFalseTreat dataclass fields as nullable by default.
meta_compressorAnyNoneOptional metadata compressor used for compatible-mode metadata encoding.
fory_factoryCallable | NoneNoneThreadSafeFory factory hook. When set, ThreadSafeFory creates instances via this callback; otherwise it forwards **kwargs to Fory construction.

Key Methods​

# Serialization (serialize/deserialize are identical to dumps/loads)
data: bytes = fory.serialize(obj)
obj = fory.deserialize(data)

# Alternative API (aliases)
data: bytes = fory.dumps(obj)
obj = fory.loads(data)

# Type registration by id
fory.register(MyClass, type_id=123)
fory.register(MyClass, type_id=123, serializer=custom_serializer)

# Type registration by name
fory.register(MyClass, name="my.package.MyClass")
fory.register(MyClass, name="my.package.MyClass", serializer=custom_serializer)

Xlang And Native Mode Comparison​

FeatureNative mode (xlang=False)Xlang mode (default)
Use casePython-only applicationsMulti-language systems
CompatibilityPython onlyJava, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, Kotlin, etc.
Supported typesPython object surfaceCross-language compatible types
Functions/lambdasSupported with trusted dynamic deserializationNot allowed
Local classesSupported with trusted dynamic deserializationNot allowed
Dynamic classesSupported with trusted dynamic deserializationNot allowed
Schema mode defaultCompatibleCompatible

Xlang Mode​

Xlang mode is the default and restricts payloads to types compatible across Fory implementations:

import pyfory

fory = pyfory.Fory(xlang=True, ref=True)
fory.register(MyDataClass, name="com.example.MyDataClass")
data = fory.serialize(MyDataClass(field1="value", field2=42))

Use compatible=False for xlang payloads only when every reader and writer always uses the same schema and you want faster serialization and smaller size. Use it only after verifying that every language uses that schema, or when native types are generated from Fory schema IDL.

Native Mode​

import pyfory

fory = pyfory.Fory(xlang=False, ref=True, strict=False)

Native mode supports Python-specific object features such as functions, local classes, methods, __reduce__, and __getstate__. Compatible mode is still enabled by default. Set compatible=False only when every reader and writer always uses the same Python class schema and you want faster serialization and smaller size.

Compatible Mode​

Compatible mode is enabled by default for both xlang and native mode. Keep this default when Python classes may evolve independently, when services deploy separately, or when xlang schemas are written by hand in different languages.

For xlang payloads, set compatible=False only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL.

Example Configurations​

Xlang Service​

import pyfory

fory = pyfory.Fory(
    xlang=True,
    ref=False,
    strict=True,
    max_depth=20,
)

fory.register(UserModel, name="example.User")

Native Mode With Dynamic Types​

import pyfory

fory = pyfory.Fory(
    xlang=False,
    ref=True,
    strict=False,
    max_depth=1000,
)

Use strict=False only for trusted data, preferably with a policy= deserialization policy.

Security​

See Python Security for trust boundaries, safe reader configuration, and verification.