cs-py-stack 20250306

Convenience functions for the python execution stack.

I find the supplied python traceback facilities quite awkward. These functions provide convenient facilities.

Latest release 20250306: frame: accept an optional traceback object or exception as a source from which to obtain the stack, add optional limit to crop the stack.

caller(frame_index=-3)

Return the Frame of the caller's caller. Returns None if frame_index is out of range.

Useful frame_index values:

• -1: caller, this function
• -2: invoker, who wants to know the caller
• -3: the calling function of the invoker

The default from_index value is -3.

frames(source=None, limit=None)

Return the current stack as a StackSummary instance, a list of FrameSummary instances. Crop the returned list at limit if it is not None.

If source is omitted or None, obtain the source stack from traceback.extract_stack(). Otherwise if source has a .tb_frame attribute (like a traceback object) or source has a .__traceback__ attribute (like an exception), call traceback.extract_stack with that to obtain the source stack.

stack_dump(f=None, indent=0, summary=None, skip=None, select=None, format_frame=None)

Recite current or supplied stack to f, default sys.stderr.

Parameters:

• f: the output file object, default sys.stderr
• indent: how many spaces to indent the stack lines, default 0
• summary: the stack Frames to write, default obtained from the current stack
• skip: the number of Frames to trim from the end of summary; if summary is None this defaults to 2 to trim the Frames for the stack_dump function and its call to frames(), otherwise the default is 0 to use the supplied Frames as is
• select: if not None, select particular frames; if select is a str it must be present in the frame filename; otherwise select(frame) must be true

Release Log

Release 20250306: frame: accept an optional traceback object or exception as a source from which to obtain the stack, add optional limit to crop the stack.

Release 20240630:

• The fallback StackSummary: add format_frame_summary(frame) static method.
• stack_dump: updates to avoid a name conflict, expect to work off a StackSummary or a list of frames.

Release 20240519: Drop Frame.funcname property.

Release 20240412:

• stack_dump: new select parameter to pick interesting frames for the listing.
• Provide StackSummary and FrameSummary if Python too old.

Release 20220918: caller(): return None if the frame offset is out of range.

Release 20220429: caller: return None if the stack index is out of range.

Release 20190812: stack_dump(): trim the last 2 frames from the listing by default (they are part of stack_dump's implementation).

Release 20190101:

• _Frame: rename .functionname to .funcname; caller: turn raw frames into Frames.
• caller(): accept optional frame_index, default -3.

Release 20160827: Add stack_dump().

Release 20150115: PyPI metadata fixups.

Release 20150111: Tag for initial PyPI release of cs.py.stack.