pyppin.threading.stack_trace

[View Source]

A library to dump stack traces from all threads, not just the current one.

This library contains the “simple” API, which is all 99% of users will ever need. Its main functions are print_all_stacks(), which does what it says on the tin, and print_all_stacks_on_failure(), which you can call during program initialization to make printing all stack traces be the default behavior whenever there’s an uncaught exception.

Another useful API is in pyppin.testing.trace_on_failure, which contains a decorator that you can attach to functions, methods, or entire unittest cases to make them print all stacks whenever there’s an uncaught exception. (Note that if you do that, “an uncaught exception” includes KeyboardInterrupt, so you can ctrl-C out of a deadlock and see what’s going on!)

If you want a more low-level API that lets you directly grab these stacks and manipulate them programmatically, that’s found in pyppin.threading.stack_trace_internals.

Note

If you’re printing out a stack trace when there’s an exception being handled, in Python 3.9 or earlier the exception will be printed out after the stack trace, because there’s no way to tie an exception to the thread that raised it. In Python 3.10 or later, this is fixed, and exceptions are shown with the offending threads.

Functions

print_all_stacks([output, limit, daemons, group])

Print the stack traces of all active threads.

print_all_stacks_on_failure()

Change the handling of uncaught exceptions to print all stacks.
pyppin.threading.stack_trace.print_all_stacks(output: Optional[TextIOBase] = None, limit: Optional[int] = None, daemons: bool = True, group: bool = True) → None[source]

Print the stack traces of all active threads.

Parameters

  • output – Where to write the output; defaults to stderr.

  • limit – If set, the maximum number of stack trace entries to return per thread. (This has the same meaning as the argument of the same name used in the traceback module)

  • daemons – Whether to include daemon threads.

  • group – If True, group together threads with identical traces.

pyppin.threading.stack_trace.print_all_stacks_on_failure() → None[source]

Change the handling of uncaught exceptions to print all stacks.

This is usually something you call from main() or otherwise during program initialization, if you want any uncaught exceptions to dump all the thread stacks.

If you want to apply this logic just to a single function or method call, check out pyppin.testing.trace_on_failure instead.