cs-py-stack 20250724

Convenience functions for the python execution stack.

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

Latest release 20250724: frames: tweak the exception frame access.

Short summary:

• caller: Return the Frame of the caller's caller. Returns None if frame_index is out of range.
• frames: Return the current stack as a StackSummary instance, a list of FrameSummary instances.
• stack_dump: Recite current or supplied stack to f, default sys.stderr.

Module contents:

• 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 20250724: frames: tweak the exception frame access.

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.