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 tblib.decorators import reraise
>>> reraise(*pickle.loads(s1))

File truncated at 100 lines see the full file

Changelog

3.2.0 (2025-10-21)

• Changed tblib.pickling_support.install to support exceptions with __init__ that does match the default BaseException.__reduce__ (as it expects the positional arguments to __init__ to match the args attribute).

  Special handling for OSError (and subclasses) is also included. The errno, strerror, winerror, filename and filename2 attributes will be added in the reduce structure (if set).

  This will support exception subclasses that do this without defining a custom __reduce__:

    def __init__(self):
        super().__init__('mistery argument')

    def __init__(self, mistery_argument):
        super().__init__()
        self.mistery_argument = mistery_argument
    

Tests and POC contributed by Oldřich Jedlička in
[#73](https://github.com/ionelmc/python-tblib/pull/73).

• Fixed some doctest and coverage config. Contributed by Colin Watson in #79.

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.

File truncated at 100 lines see the full file