Overview

docs tests package ——— ———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————–

Serialization library for Exceptions and Tracebacks.

• Free software: BSD license

It allows you to:

• Pickle tracebacks and raise exceptions with pickled tracebacks in different processes. This allows better error handling when running code over multiple processes (imagine multiprocessing, billiard, futures, celery etc).
• Create traceback objects from strings (the from_string method). No pickling is used.
• Serialize tracebacks to/from plain dicts (the from_dict and to_dict methods). No pickling is used.
• Raise the tracebacks created from the aforementioned sources.
• Pickle an Exception together with its traceback and exception chain (raise ... from ...) (Python 3 only)

Again, note that using the pickle support is completely optional. You are solely responsible for security problems should you decide to use the pickle support.

Installation

pip install tblib

Documentation

::: {.contents local=””} :::

Pickling tracebacks

Note: The traceback objects that come out are stripped of some attributes (like variables). But you'll be able to raise exceptions with those tracebacks or print them - that should cover 99% of the usecases.

>>> from tblib import pickling_support
>>> pickling_support.install()
>>> import pickle, sys
>>> def inner_0():
...     raise Exception('fail')
...
>>> def inner_1():
...     inner_0()
...
>>> def inner_2():
...     inner_1()
...
>>> try:
...     inner_2()
... except:
...     s1 = pickle.dumps(sys.exc_info())
...
>>> len(s1) > 1
True
>>> try:
...     inner_2()
... except:
...     s2 = pickle.dumps(sys.exc_info(), protocol=pickle.HIGHEST_PROTOCOL)
...
>>> len(s2) > 1
True

>>> try:
...     import cPickle
... except ImportError:
...     import pickle as cPickle
>>> try:
...     inner_2()
... except:
...     s3 = cPickle.dumps(sys.exc_info(), protocol=pickle.HIGHEST_PROTOCOL)
...
>>> len(s3) > 1
True

Unpickling tracebacks

>>> pickle.loads(s1)
(<...Exception'>, Exception('fail'...), <traceback object at ...>)

>>> pickle.loads(s2)
(<...Exception'>, Exception('fail'...), <traceback object at ...>)

>>> pickle.loads(s3)
(<...Exception'>, Exception('fail'...), <traceback object at ...>)

Raising

>>> from six import reraise
>>> reraise(*pickle.loads(s1))

File truncated at 100 lines see the full file

Changelog

3.1.0 (2025-03-31)

• Improved performance of as_traceback by a large factor. Contributed by Haoyu Weng in #81.
• Dropped support for now-EOL Python 3.8 and added 3.13 in the test grid.

3.0.0 (2023-10-22)

• Added support for __context__, __suppress_context__ and __notes__. Contributed by Tim Maxwell in #72.
• Added the get_locals argument to tblib.pickling_support.install(), tblib.Traceback and tblib.Frame. Fixes #41.
• Dropped support for now-EOL Python 3.7 and added 3.12 in the test grid.

2.0.0 (2023-06-22)

• Removed support for legacy Pythons (2.7 and 3.6) and added Python 3.11 in the test grid.
• Some cleanups and refactors (mostly from ruff).

1.7.0 (2020-07-24)

• Add more attributes to Frame and Code objects for pytest compatibility. Contributed by Ivanq in #58.

1.6.0 (2019-12-07)

• When pickling an Exception, also pickle its traceback and the Exception chain (raise ... from ...). Contributed by Guido Imperiale in #53.

1.5.0 (2019-10-23)

• Added support for Python 3.8. Contributed by Victor Stinner in #42.
• Removed support for end of life Python 3.4.
• Few CI improvements and fixes.

1.4.0 (2019-05-02)

• Removed support for end of life Python 3.3.
• Fixed tests for Python 3.7. Contributed by Elliott Sales de Andrade in #36.
• Fixed compatibility issue with Twised (twisted.python.failure.Failure expected a co_code attribute).

1.3.2 (2017-04-09)

• Add support for PyPy3.5-5.7.1-beta. Previously AttributeError: 'Frame' object has no attribute 'clear' could be raised. See PyPy issue #2532.

1.3.1 (2017-03-27)

• Fixed handling for tracebacks due to exceeding the recursion limit. Fixes #15.

1.3.0 (2016-03-08)

• Added Traceback.from_string.

1.2.0 (2015-12-18)

• Fixed handling for tracebacks from generators and other internal improvements and optimizations. Contributed by DRayX in #10 and #11.

1.1.0 (2015-07-27)

• Added support for Python 2.6. Contributed by Arcadiy Ivanov in #8.

1.0.0 (2015-03-30)

• Added to_dict method and from_dict classmethod on Tracebacks. Contributed by beckjake in #5.