0
# tblib
1

2
A traceback serialization library that enables pickling tracebacks and raising exceptions with pickled tracebacks in different processes. Ideal for multiprocessing, distributed computing, celery, and any scenario requiring traceback preservation across process boundaries.
3

4
## Package Information
5

6
- **Package Name**: tblib
7
- **Language**: Python
8
- **Installation**: `pip install tblib`
9

10
## Core Imports
11

12
```python
13
from tblib import Traceback, Code, Frame, TracebackParseError
14
```
15

16
For pickling support:
17

18
```python
19
from tblib import pickling_support
20
```
21

22
For decorators and error handling:
23

24
```python
25
from tblib.decorators import return_error, Error, reraise
26
```
27

28
## Basic Usage
29

30
```python
31
from tblib import Traceback
32
import pickle
33

34
# Serialize a traceback to dictionary (no pickling)
35
try:
36
    raise ValueError("example error")
37
except Exception:
38
    import sys
39
    tb = Traceback(sys.exc_info()[2])
40
    dict_repr = tb.as_dict()
41
    
42
# Restore traceback from dictionary
43
restored_tb = Traceback.from_dict(dict_repr)
44
traceback_obj = restored_tb.as_traceback()
45

46
# Enable pickle support for all exceptions
47
from tblib import pickling_support
48
pickling_support.install()
49
```
50

51
## Capabilities
52

53
### Traceback Serialization
54

55
Core functionality for serializing and deserializing traceback objects without pickle, using dictionary representations that are JSON-safe.
56

57
```python { .api }
58
class Traceback:
59
    def __init__(self, tb, *, get_locals=None):
60
        """
61
        Wrap builtin traceback objects for serialization.
62
        
63
        Parameters:
64
        - tb: builtin traceback object
65
        - get_locals: function that takes frame and returns dict of locals
66
        """
67
    
68
    def as_dict(self):
69
        """
70
        Convert to dictionary representation with only builtin types.
71
        
72
        Returns:
73
        dict: Serializable representation of traceback
74
        """
75
    
76
    def as_traceback(self):
77
        """
78
        Convert to builtin Traceback object for raising or rendering.
79
        
80
        Returns:
81
        traceback: Usable builtin traceback object
82
        """
83
    
84
    @classmethod
85
    def from_dict(cls, dct):
86
        """
87
        Create instance from dictionary with same structure as as_dict().
88
        
89
        Parameters:
90
        - dct: dict, dictionary representation from as_dict()
91
        
92
        Returns:
93
        Traceback: New traceback instance
94
        """
95
    
96
    @classmethod
97
    def from_string(cls, string, strict=True):
98
        """
99
        Create instance by parsing a stacktrace string.
100
        
101
        Parameters:
102
        - string: str, stacktrace string to parse
103
        - strict: bool, whether parsing stops at non-indented lines
104
        
105
        Returns:
106
        Traceback: New traceback instance
107
        """
108

109
# Aliases for convenience
110
Traceback.to_dict = Traceback.as_dict
111
Traceback.to_traceback = Traceback.as_traceback
112
```
113

114
### Frame and Code Objects
115

116
Supporting classes that replicate builtin frame and code objects for serialization compatibility.
117

118
```python { .api }
119
class Frame:
120
    def __init__(self, frame, *, get_locals=None):
121
        """
122
        Replicate builtin Frame object for serialization.
123
        
124
        Parameters:
125
        - frame: builtin frame object
126
        - get_locals: function that takes frame and returns dict of locals
127
        """
128
    
129
    def clear(self):
130
        """Compatibility method for PyPy 3.5"""
131

132
class Code:
133
    def __init__(self, code):
134
        """
135
        Replicate builtin Code object for serialization.
136
        
137
        Parameters:
138
        - code: builtin code object
139
        """
140
```
141

142
### Error Handling Decorators
143

144
Decorators and utilities for capturing exceptions and their tracebacks in a serializable form.
145

146
```python { .api }
147
def return_error(func, exc_type=Exception):
148
    """
149
    Decorator that catches exceptions and returns Error objects instead.
150
    
151
    Parameters:
152
    - func: function to wrap
153
    - exc_type: exception type to catch (default: Exception)
154
    
155
    Returns:
156
    function: Wrapped function that returns Error on exception
157
    """
158

159
class Error:
160
    def __init__(self, exc_type, exc_value, traceback):
161
        """
162
        Wrapper for exceptions with preserved tracebacks.
163
        
164
        Parameters:
165
        - exc_type: type of exception
166
        - exc_value: exception instance
167
        - traceback: traceback object
168
        """
169
    
170
    @property
171
    def traceback(self):
172
        """Get traceback object."""
173
    
174
    def reraise(self):
175
        """Reraise the original exception with traceback."""
176

177
def reraise(tp, value, tb=None):
178
    """
179
    Reraise exception with given traceback (similar to six.reraise).
180
    
181
    Parameters:
182
    - tp: exception type
183
    - value: exception instance or None
184
    - tb: traceback object or None
185
    """
186

187
def apply_with_return_error(args):
188
    """
189
    Apply function with arguments, returning Error on exception.
190
    
191
    Parameters:
192
    - args: tuple where first element is callable, rest are arguments
193
    
194
    Returns:
195
    Any or Error: Function result or Error instance on exception
196
    """
197

198
# Convenience aliases
199
returns_error = return_error
200
return_errors = return_error
201
returns_errors = return_error
202
```
203

204
### Pickle Support
205

206
Enable pickle support for tracebacks and exceptions, allowing them to be serialized and deserialized across process boundaries.
207

208
```python { .api }
209
def install(*exc_classes_or_instances, get_locals=None):
210
    """
211
    Install pickle support for tracebacks and exceptions.
212
    
213
    Parameters:
214
    - *exc_classes_or_instances: specific exception classes/instances to enable
215
    - get_locals: function to get local variables from frames
216
    
217
    Usage:
218
    - install() - enable for all exception types
219
    - install(ValueError, TypeError) - enable for specific types
220
    - Can be used as decorator for exception classes
221
    """
222
```
223

224
### Utility Functions
225

226
Helper functions for working with local variables and traceback data.
227

228
```python { .api }
229
def get_all_locals(frame):
230
    """
231
    Get all local variables from a frame.
232
    
233
    Parameters:
234
    - frame: frame object
235
    
236
    Returns:
237
    dict: All local variables in frame
238
    """
239
```
240

241
## Exceptions
242

243
```python { .api }
244
class TracebackParseError(Exception):
245
    """Raised when traceback parsing fails during from_string()."""
246
```
247

248
## Usage Examples
249

250
### Dictionary Serialization (Pickle-Free)
251

252
```python
253
from tblib import Traceback
254
import json
255

256
try:
257
    1 / 0
258
except:
259
    import sys
260
    tb = Traceback(sys.exc_info()[2])
261
    
262
    # Serialize to JSON-safe dict
263
    tb_dict = tb.as_dict()
264
    json_str = json.dumps(tb_dict)
265
    
266
    # Deserialize from dict
267
    restored_dict = json.loads(json_str)
268
    restored_tb = Traceback.from_dict(restored_dict)
269
    usable_tb = restored_tb.as_traceback()
270
```
271

272
### Pickle Support for Multiprocessing
273

274
```python
275
from tblib import pickling_support
276
import pickle
277
import multiprocessing
278

279
# Enable pickle support
280
pickling_support.install()
281

282
def worker():
283
    try:
284
        raise ValueError("Error in worker process")
285
    except Exception as e:
286
        # Exception and traceback can now be pickled
287
        return pickle.dumps(e)
288

289
def main():
290
    with multiprocessing.Pool() as pool:
291
        result = pool.apply(worker)
292
        # Unpickle the exception with full traceback
293
        exc = pickle.loads(result)
294
        raise exc  # Will show full traceback including worker process
295
```
296

297
### Custom Local Variable Handling
298

299
```python
300
from tblib import Traceback
301

302
def get_safe_locals(frame):
303
    """Only return simple, serializable locals"""
304
    safe_locals = {}
305
    for key, value in frame.f_locals.items():
306
        if isinstance(value, (str, int, float, bool, type(None))):
307
            safe_locals[key] = value
308
    return safe_locals
309

310
try:
311
    local_var = "sensitive_data"
312
    raise ValueError("error")
313
except:
314
    import sys
315
    tb = Traceback(sys.exc_info()[2], get_locals=get_safe_locals)
316
    tb_dict = tb.as_dict()  # Contains only safe local variables
317
```
318

319
### Error Handling Decorators
320

321
```python
322
from tblib.decorators import return_error, Error
323

324
@return_error
325
def risky_function(x):
326
    if x < 0:
327
        raise ValueError("Negative value not allowed")
328
    return x * 2
329

330
# Usage
331
result = risky_function(-5)
332
if isinstance(result, Error):
333
    print(f"Error occurred: {result.exc_value}")
334
    result.reraise()  # Re-raise with full traceback
335
else:
336
    print(f"Success: {result}")
337
```
338

339
### String-Based Traceback Creation
340

341
```python
342
from tblib import Traceback
343

344
# Parse a traceback from string format
345
stacktrace_text = """
346
Traceback (most recent call last):
347
  File "script.py", line 10, in main
348
  File "script.py", line 5, in helper
349
"""
350

351
try:
352
    tb = Traceback.from_string(stacktrace_text)
353
    usable_tb = tb.as_traceback()
354
except TracebackParseError as e:
355
    print(f"Failed to parse traceback: {e}")
356
```