def format_thread(thread, add_summary=False, **kwargs):
try:
fr = sys._current_frames()[thread.ident]
except KeyError:
return "%r: no frames found" % thread
else:
if 'suppressed_paths' not in kwargs:
kwargs['suppressed_paths'] = []
kwargs['suppressed_paths'] += [r"lib/python.*/threading\.py"]
msg = fmt.format_stack_from_frame(fr, **kwargs)
msg_indented = ' ' + '\n '.join(msg.split('\n')).strip()
return "%r\n\n%s" % (thread, msg_indented)
def format(thing=None, **kwargs):
"""
Render the traceback of an exception or a frame's call stack
Call this without arguments inside an `except` block to get a traceback for
the currently handled exception:
```
try:
something()
except:
logger.err(stackprinter.format(**kwargs))
```
Explicitly pass an exception (or a triple as returned by `sys.exc_info()`)
to handle that particular exception anywhere, also outside an except block.
```
try:
something()
except Exception as e:
last_exc = e
if last_exc:
logger.err(stackprinter.format(last_exc, **kwargs))
```
Pass a frame object to see the call stack leading up to that frame:
```
stack = stackprinter.format(sys._getframe(2), **kwargs))
```
Pass a thread object to see its current call stack:
```
thread = threading.Thread(target=something)
thread.start()
# (...)
stack = stackprinter.format(thread, **kwargs))
```
Note:
This displays variable values as they are _at the time of formatting_. In
multi-threaded programs, variables can change while we're busy walking
the stack & printing them. So, if nothing seems to make sense, consider that
your exception and the traceback messages are from slightly different times.
Sadly, there is no responsible way to freeze all other threads as soon
as we want to inspect some thread's call stack (...or is there?)
Params
---
thing: (optional) exception, sys.exc_info() tuple, frame or thread
What to format. Defaults to the currently handled exception or current
stack frame.
style: string
'plaintext' (default): Output just text
'darkbg', 'darkbg2', 'darkbg3', 'lightbg', 'lightbg2', 'lightbg3':
Enable colors, for use in terminals that support 256 ansi
colors or in jupyter notebooks (or even with `ansi2html`)
source_lines: int or 'all'
Select how much source code context will be shown.
int 0: Don't include a source listing.
int n > 0: Show n lines of code. (default: 5)
string 'all': Show the whole scope of the frame.
show_signature: bool (default True)
Always include the function header in the source code listing.
show_vals: str or None
Select which variable values will be shown.
'line': Show only the variables on the highlighted line.
'like_source' (default): Show only those visible in the source listing
'all': Show every variable in the scope of the frame.
None: Don't show any variable values.
truncate_vals: int
Maximum number of characters to be used for each variable value.
Default: 500
suppressed_paths: list of regex patterns
Set less verbose formatting for frames whose code lives in certain paths
(e.g. library code). Files whose path matches any of the given regex
patterns will be considered boring. The first call to boring code is
rendered with fewer code lines (but with argument values still visible),
while deeper calls within boring code get a single line and no variable
values.
Example: To hide numpy internals from the traceback, set
`suppressed_paths=[r"lib/python.*/site-packages/numpy"]`
reverse: bool
List the innermost frame first.
add_summary: True, False, 'auto'
Append a compact list of involved files and source lines, similar
to the built-in traceback message.
'auto' (default): do that if the main traceback is longer than 50 lines.
"""
if isinstance(thing, types.FrameType):
return fmt.format_stack_from_frame(thing, **kwargs)
elif isinstance(thing, Thread):
return format_thread(thing, **kwargs)
elif isinstance(thing, Exception):
exc_info = (thing.__class__, thing, thing.__traceback__)
return format(exc_info, **kwargs)
elif _is_exc_info(thing):
return fmt.format_exc_info(*thing, **kwargs)
else:
raise ValueError("Can't format %s. "\
"Expected an exception instance, sys.exc_info() tuple,"\
"a frame or a thread object." % repr(thing))
