0
# Core Formatting and Display
1
2
Central formatting engine that processes Python tracebacks and displays variable contexts. Provides low-level functions for creating formatted traceback strings and iterating through traceback lines with comprehensive variable information.
3
4
## Capabilities
5
6
### Exception Formatting
7
8
Format complete exception tracebacks as strings with variable contexts for each frame.
9
10
```python { .api }
11
def format_exc(
12
e: Optional[Exception] = None,
13
num_skipped_frames: int = 0,
14
fmt: Optional[Format] = None,
15
for_file: Optional[TextIO] = None,
16
) -> str:
17
"""
18
Format exception traceback as a string with variable contexts.
19
20
Parameters:
21
- e: Exception to format (uses current exception if None)
22
- num_skipped_frames: Number of frames to skip from the bottom of the stack
23
- fmt: Format configuration (uses default_format if None)
24
- for_file: Target file for color detection (uses stderr if None)
25
26
Returns:
27
Complete formatted traceback string with variables
28
"""
29
```
30
31
### Current Traceback Formatting
32
33
Format the current call stack as a traceback string with variable contexts.
34
35
```python { .api }
36
def format_cur_tb(
37
num_skipped_frames: int = 0,
38
fmt: Optional[Format] = None,
39
for_file: Optional[TextIO] = None,
40
) -> str:
41
"""
42
Format current traceback as a string with variable contexts.
43
44
Parameters:
45
- num_skipped_frames: Number of frames to skip from the bottom of the stack
46
- fmt: Format configuration (uses default_format if None)
47
- for_file: Target file for color detection (uses stderr if None)
48
49
Returns:
50
Complete formatted traceback string with variables
51
"""
52
```
53
54
### Exception Line Iteration
55
56
Iterate through formatted exception traceback lines for streaming or custom processing.
57
58
```python { .api }
59
def iter_exc_lines(
60
e: Optional[Exception] = None,
61
num_skipped_frames: int = 0,
62
fmt: Optional[Format] = None,
63
for_file: Optional[TextIO] = None,
64
) -> Iterator[str]:
65
"""
66
Iterate through exception traceback lines with variable contexts.
67
68
Parameters:
69
- e: Exception to format (uses current exception if None)
70
- num_skipped_frames: Number of frames to skip from the bottom of the stack
71
- fmt: Format configuration (uses default_format if None)
72
- for_file: Target file for color detection (uses stderr if None)
73
74
Yields:
75
Individual formatted traceback lines with variables
76
"""
77
```
78
79
### Current Traceback Line Iteration
80
81
Iterate through current call stack lines for streaming or custom processing.
82
83
```python { .api }
84
def iter_cur_tb_lines(
85
num_skipped_frames: int = 0,
86
fmt: Optional[Format] = None,
87
for_file: Optional[TextIO] = None,
88
) -> Iterator[str]:
89
"""
90
Iterate through current traceback lines with variable contexts.
91
92
Parameters:
93
- num_skipped_frames: Number of frames to skip from the bottom of the stack
94
- fmt: Format configuration (uses default_format if None)
95
- for_file: Target file for color detection (uses stderr if None)
96
97
Yields:
98
Individual formatted traceback lines with variables
99
"""
100
```
101
102
### Variable Display Control
103
104
Functions to control how variables are displayed in tracebacks.
105
106
```python { .api }
107
def skip(obj: Any) -> Optional[str]:
108
"""
109
Variable printer that skips displaying the variable.
110
111
Parameters:
112
- obj: Variable object (ignored)
113
114
Returns:
115
None (variable will not be displayed)
116
"""
117
118
def hide(obj: Any) -> Optional[str]:
119
"""
120
Variable printer that hides variable value with placeholder.
121
122
Parameters:
123
- obj: Variable object (ignored)
124
125
Returns:
126
String '...hidden...' as placeholder
127
"""
128
129
def show(obj: Any) -> Optional[str]:
130
"""
131
Default variable printer marker (never called directly).
132
133
Parameters:
134
- obj: Variable object (ignored)
135
136
Raises:
137
NotImplementedError (used only for comparison)
138
"""
139
```
140
141
### Default Format Configuration
142
143
Global default format instance with sensible defaults and security-conscious variable filtering.
144
145
```python { .api }
146
default_format: Format
147
```
148
149
The `default_format` is a pre-configured Format instance used when no explicit format is provided. It includes built-in security filtering to hide sensitive variables like passwords, tokens, and API keys.
150
151
## Usage Examples
152
153
### Basic Exception Formatting
154
155
```python
156
from traceback_with_variables import format_exc
157
158
try:
159
x = 42
160
y = "hello"
161
result = x / 0
162
except Exception as e:
163
formatted = format_exc(e)
164
print(formatted)
165
```
166
167
### Custom Formatting with Configuration
168
169
```python
170
from traceback_with_variables import format_exc, Format, ColorSchemes
171
172
# Create custom format
173
fmt = Format(
174
max_value_str_len=500,
175
color_scheme=ColorSchemes.synthwave,
176
before=2, # Show 2 lines before error
177
after=1 # Show 1 line after error
178
)
179
180
try:
181
data = {"key": "value", "number": 123}
182
result = data["missing_key"]
183
except Exception as e:
184
formatted = format_exc(e, fmt=fmt)
185
print(formatted)
186
```
187
188
### Streaming Traceback Processing
189
190
```python
191
from traceback_with_variables import iter_exc_lines
192
193
try:
194
items = [1, 2, 3]
195
index = 5
196
value = items[index]
197
except Exception as e:
198
# Process traceback line by line
199
for line in iter_exc_lines(e):
200
# Custom processing (e.g., logging, filtering)
201
if "items" in line:
202
print(f"IMPORTANT: {line}")
203
else:
204
print(line)
205
```
206
207
### Current Traceback Capture
208
209
```python
210
from traceback_with_variables import format_cur_tb
211
212
def debug_function():
213
local_var = "debug_value"
214
nested_data = {"a": 1, "b": [1, 2, 3]}
215
216
# Capture current call stack
217
traceback_str = format_cur_tb(num_skipped_frames=0)
218
print("Current call stack:")
219
print(traceback_str)
220
221
debug_function()
222
```