> If we copy all the params from TracebackException (and it will be all params, why only this one?)

Why expose the internal machinery at all?
If all additional parameters (and unless I'm miscounting we're talking about 2) were exposed on the convenience functions why add to the developers mental load with the underlying implementation?

> more documentation and a higher cognitive load for someone reading the documentation to learn the API.

I would agree if the API in question was ergonomic and the documentation easy to read in the first place. I think neither is true for the traceback module and its documentation.

Another example from today where I helped a coworker who was unable to figure out on his own how to print the current stack with locals:


  from traceback import StackSummary, walk_stack
  
  print("".join(StackSummary.extract(walk_stack(None), capture_locals=True).format()))

There are multiple things that make this API non-intuitive:
- Why does walk_stack() need an explicit None argument?
- Why is StackSummary created via the extract() classmethod instead of having a regular __init__?
- Why can't extract() be smart if no iterator is passed and figure out on it's own if we're in an exception context or not and call walk_stack / walk_tb accordingly?
- Why is the result a list if each item can contain multiple internal newlines?