cs-py-stack 20250724
Convenience functions for the python execution stack.
Keywords: python2, python3

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:
- <a name="caller"></a>`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`.
- <a name="frames"></a>`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.
- <a name="stack_dump"></a>`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 `Frame`s to write,
    default obtained from the current stack
  * `skip`: the number of `Frame`s to trim from the end of `summary`;
    if `summary` is `None` this defaults to `2` to trim the `Frame`s
    for the `stack_dump` function and its call to `frames()`,
    otherwise the default is `0` to use the supplied `Frame`s 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.