0
# Session Management
1

2
dill provides powerful capabilities for saving and restoring complete interpreter sessions and individual modules, enabling persistence of development environments, interactive workflows, and computational state.
3

4
## Session Operations
5

6
### Complete Session Management
7

8
```python { .api }
9
def dump_session(filename=None, main=None, byref=False, **kwds):
10
    """
11
    Save complete interpreter session to a file (deprecated).
12
    
13
    DEPRECATED: This function has been renamed to dump_module().
14
    Captures the entire state of the Python interpreter including all
15
    variables, functions, classes, and imported modules from the main namespace.
16
    
17
    Parameters:
18
    - filename: str, output filename (default: auto-generated in temp directory)
19
    - main: module, main module to save (default: __main__ module)
20
    - byref: bool, pickle objects by reference when possible
21
    - **kwds: additional keyword arguments passed to dump_module
22
    
23
    Returns:
24
    None
25
    
26
    Raises:
27
    - PicklingError: when session cannot be serialized
28
    - IOError: when file operations fail
29
    """
30

31
def load_session(filename=None, main=None, **kwds):
32
    """
33
    Load complete interpreter session from a file (deprecated).
34
    
35
    DEPRECATED: This function has been renamed to load_module().
36
    Restores the entire state of a Python interpreter session including
37
    all variables, functions, classes, and module dependencies.
38
    
39
    Parameters:
40
    - filename: str, input filename to load from
41
    - main: module, target module to restore into (default: __main__)
42
    - **kwds: additional keyword arguments passed to load_module
43
    
44
    Returns:
45
    None (modifies current interpreter state)
46
    
47
    Raises:
48
    - UnpicklingError: when session cannot be deserialized
49
    - IOError: when file operations fail
50
    """
51
```
52

53
### Individual Module Management
54

55
```python { .api }
56
def dump_module(filename=None, module=None, refimported=False, **kwds):
57
    """
58
    Save a specific module to a file.
59
    
60
    Serializes a module's complete state including all attributes,
61
    functions, classes, and internal variables while preserving
62
    cross-module references.
63
    
64
    Parameters:
65
    - filename: str or PathLike, output filename for module dump
66
    - module: module or str, specific module object to save (default: __main__)
67
    - refimported: bool, save imported modules by reference when possible
68
    - **kwds: additional keyword arguments passed to Pickler
69
    
70
    Returns:
71
    None
72
    
73
    Raises:
74
    - PicklingError: when module cannot be serialized
75
    - IOError: when file operations fail
76
    """
77

78
def load_module(name=None, module=None, main=None, **kwds):
79
    """
80
    Load a module from a file.
81
    
82
    Restores a module's complete state and integrates it into the
83
    current interpreter environment with proper reference resolution.
84
    
85
    Parameters:
86
    - name: str, input filename containing module dump
87
    - module: str, name for the restored module in sys.modules
88
    - main: module, main module context for integration
89
    - **kwds: additional keyword arguments passed to Unpickler
90
    
91
    Returns:
92
    module: loaded module object
93
    
94
    Raises:
95
    - UnpicklingError: when module cannot be deserialized
96
    - IOError: when file operations fail
97
    """
98

99
def load_module_asdict(name=None, main=None, **kwds):
100
    """
101
    Load a module from a file as a dictionary.
102
    
103
    Restores module contents as a dictionary rather than a module object,
104
    useful for inspecting module contents without side effects.
105
    
106
    Parameters:
107
    - name: str, input filename containing module dump
108
    - main: module, main module context for reference resolution
109
    - **kwds: additional keyword arguments passed to load_module
110
    
111
    Returns:
112
    dict: module contents as dictionary
113
    
114
    Raises:
115
    - UnpicklingError: when module cannot be deserialized
116
    - IOError: when file operations fail
117
    """
118
```
119

120
## Usage Examples
121

122
### Interactive Session Persistence
123

124
```python
125
import dill
126

127
# During interactive session, define some variables and functions
128
x = 42
129
data = [1, 2, 3, 4, 5]
130

131
def process_data(items):
132
    return [item * 2 for item in items]
133

134
class DataProcessor:
135
    def __init__(self, multiplier=1):
136
        self.multiplier = multiplier
137
    
138
    def process(self, data):
139
        return [x * self.multiplier for x in data]
140

141
processor = DataProcessor(3)
142

143
# Save entire session
144
dill.dump_session('my_analysis_session.pkl')
145

146
# Later, in a new Python session:
147
import dill
148
dill.load_session('my_analysis_session.pkl')
149

150
# All variables and functions are now available
151
result = process_data(data)  # [2, 4, 6, 8, 10]
152
processed = processor.process(data)  # [3, 6, 9, 12, 15]
153
```
154

155
### Module-specific Operations
156

157
```python
158
import dill
159
import mymodule
160

161
# Save specific module
162
dill.dump_module('mymodule_backup.pkl', module=mymodule)
163

164
# Modify module during development
165
mymodule.some_function = lambda x: x * 10
166

167
# Restore original module state
168
original_module = dill.load_module('mymodule_backup.pkl')
169
```
170

171
### Development Workflow Integration
172

173
```python
174
import dill
175
import sys
176

177
# Save current development state
178
def save_checkpoint(name):
179
    """Save current session as a development checkpoint."""
180
    filename = f'checkpoint_{name}.pkl'
181
    dill.dump_session(filename)
182
    print(f"Session saved to {filename}")
183

184
def load_checkpoint(name):
185
    """Load a development checkpoint."""
186
    filename = f'checkpoint_{name}.pkl'
187
    dill.load_session(filename)
188
    print(f"Session loaded from {filename}")
189

190
# Usage in development
191
save_checkpoint('before_experiment')
192

193
# Run experiments, make changes...
194

195
# Restore if needed
196
load_checkpoint('before_experiment')
197
```
198

199
### Module Inspection
200

201
```python
202
import dill
203

204
# Load module as dictionary for inspection
205
module_dict = dill.load_module_asdict('saved_module.pkl')
206

207
# Inspect contents without side effects
208
print("Module contents:")
209
for name, obj in module_dict.items():
210
    if not name.startswith('_'):
211
        print(f"  {name}: {type(obj)}")
212

213
# Selectively restore specific items
214
my_function = module_dict.get('my_function')
215
if my_function:
216
    # Use the function without restoring entire module
217
    result = my_function(input_data)
218
```
219

220
## Advanced Features
221

222
### Session Filtering
223

224
```python
225
import dill
226

227
# Custom session dumping with filtering
228
def dump_filtered_session(filename, exclude_patterns=None):
229
    """Dump session excluding certain patterns."""
230
    import __main__
231
    
232
    # Get current main module
233
    main_dict = __main__.__dict__.copy()
234
    
235
    # Filter out unwanted items
236
    if exclude_patterns:
237
        filtered_dict = {}
238
        for name, obj in main_dict.items():
239
            if not any(pattern in name for pattern in exclude_patterns):
240
                filtered_dict[name] = obj
241
        
242
        # Temporarily replace main dict
243
        original_dict = __main__.__dict__
244
        __main__.__dict__ = filtered_dict
245
        
246
        try:
247
            dill.dump_session(filename)
248
        finally:
249
            __main__.__dict__ = original_dict
250
    else:
251
        dill.dump_session(filename)
252

253
# Usage
254
dump_filtered_session('clean_session.pkl', exclude_patterns=['_temp', 'debug_'])
255
```
256

257
### Cross-Environment Session Transfer
258

259
```python
260
import dill
261
import sys
262
import os
263

264
# Save session with environment info
265
def save_portable_session(filename):
266
    """Save session with environment metadata."""
267
    # Save session
268
    dill.dump_session(filename)
269
    
270
    # Save environment info
271
    env_info = {
272
        'python_version': sys.version,
273
        'platform': sys.platform,
274
        'path': sys.path.copy(),
275
        'modules': list(sys.modules.keys()),
276
        'cwd': os.getcwd()
277
    }
278
    
279
    env_filename = filename.replace('.pkl', '_env.pkl')
280
    with open(env_filename, 'wb') as f:
281
        dill.dump(env_info, f)
282

283
def load_portable_session(filename):
284
    """Load session with environment validation."""
285
    # Load environment info
286
    env_filename = filename.replace('.pkl', '_env.pkl')
287
    
288
    try:
289
        with open(env_filename, 'rb') as f:
290
            env_info = dill.load(f)
291
        
292
        # Validate compatibility
293
        if env_info['python_version'] != sys.version:
294
            print(f"Warning: Python version mismatch")
295
            print(f"  Saved: {env_info['python_version']}")
296
            print(f"  Current: {sys.version}")
297
        
298
        # Load session
299
        dill.load_session(filename)
300
        
301
    except FileNotFoundError:
302
        print("Environment info not found, loading session anyway...")
303
        dill.load_session(filename)
304
```
305

306
## Integration with Development Tools
307

308
### Jupyter Notebook Integration
309

310
```python
311
# In Jupyter notebook cells
312
import dill
313

314
# Save notebook state
315
def save_notebook_session():
316
    """Save current notebook session."""
317
    dill.dump_session('notebook_session.pkl')
318
    print("Notebook session saved")
319

320
def load_notebook_session():
321
    """Load notebook session."""
322
    dill.load_session('notebook_session.pkl')
323
    print("Notebook session loaded")
324

325
# Magic command integration (requires IPython)
326
from IPython.core.magic import register_line_magic
327

328
@register_line_magic
329
def save_dill(line):
330
    """Magic command to save session."""
331
    filename = line.strip() or 'session.pkl'
332
    dill.dump_session(filename)
333
    print(f"Session saved to {filename}")
334

335
@register_line_magic  
336
def load_dill(line):
337
    """Magic command to load session."""
338
    filename = line.strip() or 'session.pkl'
339
    dill.load_session(filename)
340
    print(f"Session loaded from {filename}")
341

342
# Usage: %save_dill my_session.pkl
343
```
344

345
## Best Practices
346

347
### Session Management Guidelines
348

349
- **Regular Checkpoints**: Save session state before major experiments or changes
350
- **Descriptive Naming**: Use meaningful filenames that describe the session state
351
- **Environment Documentation**: Include metadata about the environment when sharing sessions
352
- **Selective Restoration**: Use `load_module_asdict` to inspect before full restoration
353
- **Clean-up**: Remove temporary variables before saving to reduce file size
354

355
### Performance Considerations
356

357
- **Large Sessions**: Break down large sessions into smaller, focused modules
358
- **Memory Usage**: Be aware that session files can be large for complex environments
359
- **Loading Time**: Session restoration can take time for environments with many dependencies
360
- **Cross-platform**: Test session files across different platforms if portability is needed