Module

utils.traceback_config

Centralized configuration for traceback formatting and rendering.

Provides a simple configuration object with a style (full/compact/minimal/off), and utilities to install Rich's global exception hook based on the active style.

MVP: Sources configuration from CLI-provided env var (BENGAL_TRACEBACK) → defaults. Future: Extend to read from site config and config files.

View source
2 Classes 3 Functions

Classes

TracebackStyle
0
Inherits from Enum
TracebackConfig dataclass
Configuration for traceback display and rich install options.
3

Configuration for traceback display and rich install options.

Attributes

Name Type Description
style TracebackStyle
show_locals bool
max_frames int
suppress tuple[str, ...]

Methods 3

from_environment classmethod
Load configuration from environment variables (MVP). Precedence: BENGAL_TRACEB…
0 TracebackConfig 
def from_environment(cls) -> TracebackConfig

Load configuration from environment variables (MVP).

Precedence: BENGAL_TRACEBACK → defaults.

Returns

TracebackConfig

install
Install Rich traceback handler according to config and environment. - If style…
0 None 
def install(self) -> None

Install Rich traceback handler according to config and environment.

  • If style == OFF: do not install rich hook (use standard Python)
  • If in CI or non-TTY, rely on rich_console.should_use_rich to skip
get_renderer
0 TracebackRenderer 
def get_renderer(self) -> TracebackRenderer
Returns

TracebackRenderer

Functions

set_effective_style_from_cli
Helper to set the process env for traceback style from a CLI flag. This allows downstream code tha…
1 None 
def set_effective_style_from_cli(style_value: str | None) -> None

Helper to set the process env for traceback style from a CLI flag.

This allows downstream code that calls TracebackConfig.from_environment() to see the user choice consistently.

Parameters 1

Name Type Default Description
style_value str | None —
map_debug_flag_to_traceback
Map legacy --debug flag to traceback=full unless user explicitly set one.
2 None 
def map_debug_flag_to_traceback(debug: bool, current: str | None = None) -> None

Map legacy --debug flag to traceback=full unless user explicitly set one.

Parameters 2

Name Type Default Description
debug bool —
current str | None None
apply_file_traceback_to_env
Apply file-based traceback config ([dev.traceback]) to environment. Precedence: existing env vars …
1 None 
def apply_file_traceback_to_env(site_config: dict[str, Any] | None) -> None

Apply file-based traceback config ([dev.traceback]) to environment.

Precedence: existing env vars win. Only set if not already present.

Expected structure:

site_config["dev"]["traceback"] = {
    "style": "compact|full|minimal|off",
    "show_locals": bool,
    "max_frames": int,
    "suppress": ["click", "jinja2"],
}

Parameters 1

Name Type Default Description
site_config dict[str, Any] | None —