0
# Core Serialization
1

2
Primary serialization operations for converting Python objects to/from binary format with optional reference tracking and circular reference support. PyFury provides both Python-native and cross-language serialization modes.
3

4
## Capabilities
5

6
### Fury Serialization Engine
7

8
The main serialization engine that handles object conversion with configurable language modes and security options.
9

10
```python { .api }
11
class Fury:
12
    def __init__(
13
        self,
14
        language: Language = Language.XLANG,
15
        ref_tracking: bool = False,
16
        require_class_registration: bool = True,
17
    ):
18
        """
19
        Create a Fury serialization engine.
20

21
        Args:
22
            language: Serialization language mode (XLANG for cross-language, JAVA for Java compat)
23
            ref_tracking: Enable reference tracking for circular/shared objects
24
            require_class_registration: Require class registration for security (recommended)
25
        """
26

27
    def serialize(
28
        self,
29
        obj,
30
        buffer: Buffer = None,
31
        buffer_callback=None,
32
        unsupported_callback=None,
33
    ) -> Union[Buffer, bytes]:
34
        """
35
        Serialize a Python object to binary format.
36

37
        Args:
38
            obj: Object to serialize
39
            buffer: Optional buffer to write to (auto-allocated if None)
40
            buffer_callback: Callback for handling buffer objects
41
            unsupported_callback: Callback for handling unsupported types
42

43
        Returns:
44
            Serialized binary data as Buffer or bytes
45
        """
46

47
    def deserialize(
48
        self,
49
        buffer: Union[Buffer, bytes],
50
        buffers: Iterable = None,
51
        unsupported_objects: Iterable = None,
52
    ):
53
        """
54
        Deserialize binary data back to Python object.
55

56
        Args:
57
            buffer: Binary data to deserialize
58
            buffers: Additional buffers for zero-copy deserialization
59
            unsupported_objects: Objects to handle unsupported types
60

61
        Returns:
62
            Deserialized Python object
63
        """
64
```
65

66
### Language Modes
67

68
PyFury supports different serialization modes for various compatibility requirements.
69

70
```python { .api }
71
class Language(enum.Enum):
72
    XLANG = 0  # Cross-language mode for multi-language compatibility
73
    JAVA = 1   # Java-compatible mode for JVM interop
74
```
75

76
### Usage Examples
77

78
#### Basic Serialization
79

80
```python
81
import pyfury
82

83
# Create Fury instance
84
fury = pyfury.Fury()
85

86
# Serialize and deserialize simple objects
87
data = {"key": "value", "number": 42}
88
serialized = fury.serialize(data)
89
restored = fury.deserialize(serialized)
90
```
91

92
#### Cross-Language Serialization
93

94
```python
95
import pyfury
96
from dataclasses import dataclass
97

98
@dataclass
99
class Person:
100
    name: str
101
    age: int
102

103
# Enable cross-language mode with reference tracking
104
fury = pyfury.Fury(language=pyfury.Language.XLANG, ref_tracking=True)
105
fury.register_class(Person, type_tag="example.Person")
106

107
person = Person("Alice", 30)
108
serialized = fury.serialize(person)
109

110
# This data can be deserialized by Java/JavaScript/Go Fury implementations
111
restored = fury.deserialize(serialized)
112
```
113

114
#### Reference Tracking
115

116
```python
117
import pyfury
118

119
# Enable reference tracking for circular references
120
fury = pyfury.Fury(ref_tracking=True)
121

122
# Create objects with shared references
123
obj1 = {"shared_data": [1, 2, 3]}
124
obj2 = {"ref1": obj1, "ref2": obj1}  # Both reference same object
125

126
serialized = fury.serialize(obj2)
127
restored = fury.deserialize(serialized)
128

129
# Shared references are preserved
130
assert restored["ref1"] is restored["ref2"]
131
```
132

133
#### Complex Object Serialization
134

135
```python
136
import pyfury
137
from typing import List
138
from dataclasses import dataclass
139

140
@dataclass
141
class User:
142
    name: str
143
    age: int
144
    hobbies: List[str]
145

146
fury = pyfury.Fury()
147
fury.register_class(User)
148

149
# Serialize complex object
150
user = User("Alice", 30, ["reading", "swimming"])
151
user_bytes = fury.serialize(user)
152

153
# Deserialize
154
restored_user = fury.deserialize(user_bytes)
155
```
156

157
### Opaque Objects
158

159
PyFury handles opaque objects for cross-language scenarios where types aren't registered on both sides.
160

161
```python { .api }
162
class OpaqueObject:
163
    def __init__(self, type_id: int, data: bytes):
164
        """
165
        Represents an object that couldn't be deserialized due to missing type info.
166

167
        Args:
168
            type_id: Type identifier from the serialization metadata
169
            data: Raw serialized data of the object
170
        """
171
```
172

173
### Buffer Operations
174

175
Direct buffer operations for advanced use cases and memory optimization.
176

177
```python
178
import pyfury
179

180
fury = pyfury.Fury()
181

182
# Use pre-allocated buffer
183
buffer = pyfury.Buffer.allocate(1024)
184
result = fury.serialize(my_object, buffer=buffer)
185

186
# Deserialize from buffer
187
restored = fury.deserialize(result)
188
```
189

190
### Class Registration
191

192
Register classes for security and cross-language compatibility.
193

194
```python
195
import pyfury
196

197
fury = pyfury.Fury()
198

199
# Register class with auto-generated ID
200
fury.register_class(MyClass)
201

202
# Register with specific type tag for cross-language compatibility
203
fury.register_class(MyClass, type_tag="com.example.MyClass")
204

205
# Register with specific class ID
206
fury.register_class(MyClass, class_id=100)
207
```
208

209
### Performance Considerations
210

211
- **Reference Tracking**: Only enable when dealing with circular references or shared objects
212
- **Language Mode**: Use `XLANG` for cross-language compatibility, omit for Python-only scenarios
213
- **Class Registration**: Keep enabled for security; pre-register all classes for best performance
214
- **Buffer Reuse**: Pass the same Buffer instance across multiple serialize() calls to reduce allocations
215

216
### Error Handling
217

218
```python
219
import pyfury
220

221
fury = pyfury.Fury()
222

223
try:
224
    data = fury.serialize(some_object)
225
    restored = fury.deserialize(data)
226
except pyfury.FuryError as e:
227
    print(f"Serialization error: {e}")
228
except pyfury.ClassNotCompatibleError as e:
229
    print(f"Class compatibility error: {e}")
230
```
231

232
### Handling Unsupported Types
233

234
PyFury provides callbacks for handling types that cannot be serialized directly.
235

236
```python
237
import pyfury
238

239
def buffer_callback(obj):
240
    """Handle buffer objects during serialization."""
241
    if hasattr(obj, 'to_buffer'):
242
        return obj.to_buffer()
243
    return None
244

245
def unsupported_callback(obj):
246
    """Handle unsupported objects during serialization."""
247
    # Custom logic for unsupported types
248
    return obj
249

250
fury = pyfury.Fury()
251
serialized = fury.serialize(
252
    my_object,
253
    buffer_callback=buffer_callback,
254
    unsupported_callback=unsupported_callback
255
)
256
```