pyppin.threading.stack_trace_internals¶

The actual meat of stack tracing.

This file contains the “advanced” API which most users won’t need, as well as the implementation details; it lets you do things like examine and programmatically manipulate the threads of all stacks. Most users can stick to pyppin.threading.stack_trace instead.

Warning

The non-public methods in this library are non-public for a reason; they are subtle and quick to anger. Do not mess with them unless you understand Python’s GC system quite well.

Functions

`all_stacks`([limit, daemons])	Return the stack summaries for all active threads.
`format_stacks`(stacks[, group])	Format a list of stacks neatly for printing.
`print_stacks`(stacks[, output, group])	Print a collection of thread stacks.
`print_trace`(lines[, output])	Print a list of trace lines.

Classes

`ThreadStack`(thread, stack, exception)	A ThreadStack represents a single thread and its stack info.
`TraceLine`(line, line_type)	One logical "line" of the stack trace, including a trailing newline.
`TraceLineType`(value)	The different kinds of line in a trace that may require different visual representation.

class pyppin.threading.stack_trace_internals.TraceLineType(value)[source]¶

Bases: Enum

The different kinds of line in a trace that may require different visual representation.

THREAD_TITLE = 0[source]¶: The “intro” block for a thread

TRACE_LINE = 1[source]¶: A part of the stack trace

EXCEPTION = 2[source]¶: An exception warning

class pyppin.threading.stack_trace_internals.TraceLine(line: str, line_type: TraceLineType)[source]¶

Bases: NamedTuple

One logical “line” of the stack trace, including a trailing newline.

It’s only a logical line; this may also include internal newlines.

line: str[source]¶: The actual text of the line.

line_type: TraceLineType[source]¶: How the line should be rendered.

prepend(data: str) → TraceLine[source]¶: Create a new TraceLine by prepending text to this one.

classmethod as_trace(lines: Iterable[str], line_type: TraceLineType = TraceLineType.TRACE_LINE, prefix: str = '') → Iterator[TraceLine][source]¶: Convert a sequence of lines of text to a sequence of TraceLines.

classmethod blank() → TraceLine[source]¶: A blank TraceLine.

class pyppin.threading.stack_trace_internals.ThreadStack(thread: Optional[Thread], stack: Optional[StackSummary], exception: Optional[BaseException])[source]¶

Bases: object

A ThreadStack represents a single thread and its stack info.

You generally acquire these objects with functions like all_stacks, below.

NB that self.exception is going to be a TracebackException object, not the original exception, in order to avoid all sorts of exciting reference counting cycles and other things that can make your life unpleasant. Net is that it’s safe to keep one of these objects around, you don’t need to do magical “dear-gods-delete-this-quickly” magic like with frame objects.

property thread_unknown: bool[source]¶: Returns true if we don’t actually know what thread this is.

property is_started: bool[source]¶: Returns true if the thread is active.

property thread_id: Optional[int][source]¶: The Python ID of this thread, if it’s started.

property native_thread_id: Optional[int][source]¶: The native thread ID of this thread, if it’s started.

property is_daemon: bool[source]¶: Whether this is a daemon thread.

property formatted: List[TraceLine][source]¶: This thread’s stack, formatted as a list of TraceLines.

property cluster_id: int[source]¶

A “similarity identifier” for this thread’s stack trace.

If two threads have the same cluster ID, then their stack traces are effectively identical and (if grouping is turned on) should be merged in rendering.

This is especially useful if you have a bunch of “listener” or “worker” threads in your program which may be doing the same thing; it greatly simplifies the stack trace without losing data.

property name: str[source]¶: A name for this thread, suitable for use as a title in a trace.

pyppin.threading.stack_trace_internals.all_stacks(limit: Optional[int] = None, daemons: bool = True) → List[ThreadStack][source]¶

Return the stack summaries for all active threads.

Parameters

limit – If given, this is the maximum number of stack trace entries to return for each thread. (This is the same meaning as the argument of the same name used in the traceback module)
daemons – If True, include daemon threads.

Returns

All the active threads, in no particular order.

pyppin.threading.stack_trace_internals.format_stacks(stacks: List[ThreadStack], group: bool = True) → List[TraceLine][source]¶

Format a list of stacks neatly for printing.

Parameters

stacks – The stacks to format.
group – If True, group together threads with identical traces.

pyppin.threading.stack_trace_internals.print_trace(lines: List[TraceLine], output: Optional[TextIOBase] = None) → None[source]¶

Print a list of trace lines.

Parameters

lines – The lines to print.
output – Where to write them to, defaulting to stderr.

pyppin.threading.stack_trace_internals.print_stacks(stacks: List[ThreadStack], output: Optional[TextIOBase] = None, group: bool = True) → None[source]¶

Print a collection of thread stacks.

Parameters

stacks – The stacks to print.
output – Where to write them to, defaulting to stderr.
group – If True, group together threads with identical traces.