Traceback With Variables

2.2.1 · active · verified Wed Apr 15

traceback-with-variables is a Python library that enhances standard tracebacks by adding local variable contexts for each frame in a stacktrace. It helps in debugging by showing variable values at the point of an exception, offering features like colorful output, configurable formatting, and integration with Jupyter/IPython. Currently at version 2.2.1, it receives active maintenance with minor releases.

Warnings

gotcha Activating `traceback-with-variables` globally via `activate()` or `activate_by_import` sets `sys.excepthook`. This can interfere with other libraries (e.g., logging frameworks, error reporting tools) that also modify the global exception handler, potentially overriding or being overridden.
Fix: If encountering conflicts, consider selectively applying `add_variables_to_traceback` as a decorator or context manager, or manually integrating `dump_traceback()` with your existing exception handling. Ensure `activate()` is called after other handlers if `traceback-with-variables` output is preferred.
gotcha Enabling variable capturing globally in production environments can introduce performance overhead, especially for deep stack traces or large variable objects. Additionally, logging local variable values might expose sensitive data (e.g., API keys, user credentials) in logs.
Fix: Use `traceback-with-variables` primarily in development/testing environments. In production, configure carefully, using `exclude_regex` for sensitive variables or applying it selectively (e.g., `add_variables_to_traceback` decorator) only to critical functions, or disable it entirely.
breaking The transition to v2.0.0 (and subsequent minor versions like v2.0.4) was not extensively documented with explicit breaking changes. However, major version bumps often imply potential changes to `activate()` parameters, default output formatting (e.g., with the introduction of `default_format`), or internal behavior. Users upgrading from v1.x should thoroughly test their implementations.
Fix: Review the GitHub repository's commit history around v2.0.0 for specific changes. Pay close attention to how `activate()` is configured and any custom formatting options used. Test existing error handling and output for regressions.
gotcha Earlier versions (e.g., v1.1.1) introduced `activate_by_import` which could lead to global activation simply by importing the library. While the current recommendation is explicit `tb_with_vars.activate()`, users might mistakenly rely on or accidentally trigger global activation if `activate_by_import` is still enabled by default or via configuration in their environment.
Fix: Always explicitly call `tb_with_vars.activate()` when global activation is desired to ensure predictable behavior. If auto-activation is not intended, verify that no configuration or old import patterns are implicitly enabling it. Use `tb_with_vars.deactivate()` when global activation is no longer needed.

Install

pip install traceback-with-variables Install traceback-with-variables

Imports

activate

wrong:

import traceback-with-variables

correct:

import traceback_with_variables as tb_with_vars
tb_with_vars.activate()

The PyPI package name uses hyphens, but the Python import name uses underscores.

add_variables_to_traceback

from traceback_with_variables import add_variables_to_traceback

Quickstart

This quickstart demonstrates how to globally activate `traceback-with-variables` and then trigger an error. When the `ZeroDivisionError` occurs, the enhanced traceback (including local variable values for each frame) will be printed to the console.

import traceback_with_variables as tb_with_vars

tb_with_vars.activate() # Globally activate the enhanced traceback

def f(a, b):
    # This function will cause a ZeroDivisionError
    return a / b

def g(x):
    y = x * 2
    # If x is 0, y will be 0, leading to ZeroDivisionError in f
    if x == 0:
        z = 1 # Avoid division by zero here just to show other vars
    else:
        z = x / y
    return f(z, 0) # This division by zero will be caught

try:
    g(1) # Call with a non-zero to trace normal flow then crash
except Exception as e:
    print(f"Caught exception: {e}")
    # The activate() call ensures sys.excepthook is set
    # The standard traceback will now include variable values
    # No explicit print_exc needed here for global hook

print("Check console for enhanced traceback.")

tb_with_vars.deactivate() # Optionally deactivate when done

view raw JSON →