0
# Core Serialization
1

2
dill's core serialization functions provide extended pickle functionality that can handle complex Python objects including functions, classes, lambdas, and nested structures that standard pickle cannot serialize.
3

4
## Primary Serialization Functions
5

6
### File-based Operations
7

8
```python { .api }
9
def dump(obj, file, protocol=None, byref=None, fmode=None, recurse=None, **kwds):
10
    """
11
    Serialize object to a file.
12
    
13
    Provides enhanced serialization capabilities beyond standard pickle.dump,
14
    supporting complex objects like functions, classes, and nested structures.
15
    
16
    Parameters:
17
    - obj: object to serialize
18
    - file: file-like object to write to (must have write() method)
19
    - protocol: int, pickle protocol version (default: DEFAULT_PROTOCOL)
20
    - byref: bool, pickle by reference when possible to reduce file size
21
    - fmode: int, file mode for handle management (0=HANDLE_FMODE, 1=CONTENTS_FMODE, 2=FILE_FMODE)
22
    - recurse: bool, recursively pickle nested objects and their dependencies
23
    - **kwds: additional keyword arguments passed to Pickler
24
    
25
    Returns:
26
    None
27
    
28
    Raises:
29
    - PicklingError: when object cannot be serialized
30
    - IOError: when file operations fail
31
    """
32

33
def load(file, ignore=None, **kwds):
34
    """
35
    Deserialize object from a file.
36
    
37
    Provides enhanced deserialization capabilities beyond standard pickle.load,
38
    with improved error handling and support for complex object restoration.
39
    
40
    Parameters:
41
    - file: file-like object to read from (must have read() method)
42
    - ignore: bool, ignore certain unpickling errors and continue
43
    - **kwds: additional keyword arguments passed to Unpickler
44
    
45
    Returns:
46
    object: deserialized object with full functionality restored
47
    
48
    Raises:
49
    - UnpicklingError: when deserialization fails
50
    - IOError: when file operations fail
51
    """
52
```
53

54
### String-based Operations
55

56
```python { .api }
57
def dumps(obj, protocol=None, byref=None, fmode=None, recurse=None, **kwds):
58
    """
59
    Serialize object to a bytes string.
60
    
61
    Converts any Python object to a bytes representation that can be
62
    stored, transmitted, or restored later with full functionality.
63
    
64
    Parameters:
65
    - obj: object to serialize (any Python object)
66
    - protocol: int, pickle protocol version (default: DEFAULT_PROTOCOL)
67
    - byref: bool, pickle by reference when possible to reduce size
68
    - fmode: int, file mode for handle management
69
    - recurse: bool, recursively pickle nested objects and dependencies
70
    - **kwds: additional keyword arguments passed to Pickler
71
    
72
    Returns:
73
    bytes: serialized object as bytes string
74
    
75
    Raises:
76
    - PicklingError: when object cannot be serialized
77
    """
78

79
def loads(str, ignore=None, **kwds): 
80
    """
81
    Deserialize object from a bytes string.
82
    
83
    Restores a Python object from its bytes representation with
84
    full functionality and state preservation.
85
    
86
    Parameters:
87
    - str: bytes, bytes string containing serialized object
88
    - ignore: bool, ignore certain unpickling errors and continue
89
    - **kwds: additional keyword arguments passed to Unpickler
90
    
91
    Returns:
92
    object: deserialized object with original functionality
93
    
94
    Raises:
95
    - UnpicklingError: when deserialization fails
96
    - TypeError: when input is not bytes
97
    """
98
```
99

100
### Deep Copy Operation
101

102
```python { .api }
103
def copy(obj, *args, **kwds):
104
    """
105
    Create a deep copy of an object using serialization.
106
    
107
    Uses dill's enhanced serialization to create deep copies of complex
108
    objects that standard copy.deepcopy cannot handle.
109
    
110
    Parameters:
111
    - obj: object to copy (any Python object)
112
    - *args: positional arguments passed to dumps/loads
113
    - **kwds: keyword arguments passed to dumps/loads
114
    
115
    Returns:
116
    object: deep copy of the input object with independent state
117
    
118
    Raises:
119
    - PicklingError: when object cannot be serialized for copying
120
    """
121
```
122

123
## Usage Examples
124

125
### Basic Function Serialization
126

127
```python
128
import dill
129

130
# Serialize a function with closure
131
def create_multiplier(factor):
132
    def multiply(x):
133
        return x * factor
134
    return multiply
135

136
# Create function with closure
137
times_three = create_multiplier(3)
138

139
# Serialize to bytes
140
serialized = dill.dumps(times_three)
141

142
# Deserialize and use
143
restored_function = dill.loads(serialized)
144
result = restored_function(4)  # Returns 12
145
```
146

147
### Class and Instance Serialization
148

149
```python
150
import dill
151

152
# Define a class with methods
153
class Calculator:
154
    def __init__(self, precision=2):
155
        self.precision = precision
156
    
157
    def add(self, a, b):
158
        return round(a + b, self.precision)
159

160
# Create instance
161
calc = Calculator(precision=3)
162

163
# Serialize to file
164
with open('calculator.pkl', 'wb') as f:
165
    dill.dump(calc, f)
166

167
# Load from file
168
with open('calculator.pkl', 'rb') as f:
169
    restored_calc = dill.load(f)
170

171
result = restored_calc.add(1.2345, 2.6789)  # Returns 3.913
172
```
173

174
### Lambda and Nested Function Handling
175

176
```python
177
import dill
178

179
# Complex nested structure with lambdas
180
operations = {
181
    'square': lambda x: x * x,
182
    'cube': lambda x: x ** 3,
183
    'factorial': lambda n: 1 if n <= 1 else n * operations['factorial'](n-1)
184
}
185

186
# Serialize complex structure
187
data = dill.dumps(operations)
188

189
# Restore and use
190
restored_ops = dill.loads(data)
191
print(restored_ops['square'](5))      # 25
192
print(restored_ops['factorial'](5))   # 120
193
```
194

195
### Error Handling
196

197
```python
198
import dill
199
from dill import PicklingError, UnpicklingError
200

201
# Handle serialization errors
202
def safe_serialize(obj):
203
    try:
204
        return dill.dumps(obj)
205
    except PicklingError as e:
206
        print(f"Cannot serialize object: {e}")
207
        return None
208

209
# Handle deserialization errors  
210
def safe_deserialize(data):
211
    try:
212
        return dill.loads(data)
213
    except UnpicklingError as e:
214
        print(f"Cannot deserialize data: {e}")
215
        return None
216
```
217

218
## Advanced Features
219

220
### Protocol Selection
221

222
```python
223
import dill
224

225
# Use specific protocol version
226
data = dill.dumps(my_object, protocol=dill.HIGHEST_PROTOCOL)
227

228
# Check protocol compatibility
229
print(f"Default protocol: {dill.DEFAULT_PROTOCOL}")
230
print(f"Highest protocol: {dill.HIGHEST_PROTOCOL}")
231
```
232

233
### File Mode Options
234

235
```python
236
import dill
237

238
# Different file modes for handle management
239
obj = complex_object_with_files
240

241
# Handle mode - preserve file handles
242
dill.dump(obj, file, fmode=dill.HANDLE_FMODE)
243

244
# Contents mode - save file contents
245
dill.dump(obj, file, fmode=dill.CONTENTS_FMODE)
246

247
# File mode - save file metadata
248
dill.dump(obj, file, fmode=dill.FILE_FMODE)
249
```
250

251
### Recursive Serialization
252

253
```python
254
import dill
255

256
# Enable recursive pickling for nested dependencies
257
nested_structure = create_complex_nested_object()
258

259
# Recursively serialize all dependencies
260
data = dill.dumps(nested_structure, recurse=True)
261
```
262

263
## Integration with Standard Library
264

265
dill functions as a drop-in replacement for pickle:
266

267
```python
268
# Replace pickle with dill
269
import dill as pickle
270

271
# All pickle functionality works
272
data = pickle.dumps(obj)
273
restored = pickle.loads(data)
274

275
# Plus extended capabilities
276
function_data = pickle.dumps(my_function)  # Works with dill, fails with pickle
277
```
278

279
## Performance Considerations
280

281
- **Protocol Selection**: Higher protocols generally provide better performance and smaller file sizes
282
- **Recursive Mode**: Use `recurse=True` cautiously as it can significantly increase serialization time for large object graphs
283
- **File vs String**: File-based operations are more memory-efficient for large objects
284
- **Reference Mode**: `byref=True` can reduce file size but may affect object independence after deserialization