I've written three (or more) answers on Stack Overflow about how to use the functions in the traceback module, and I code Python all day long.

Embarrassing confession: I just recommended the wrong traceback function in email to fix the incorrect usage of another of these functions after pulling up the docs because. I corrected myself before anyone else could correct me, but I find these docstrings incredibly frustrating and problematic.

May I please give them a little more verbiage about their return values?

e.g.:

def format_tb(tb, limit=None):
    """A shorthand for 'format_list(extract_tb(tb, limit))'."""
    return extract_tb(tb, limit=limit).format()

should be:

def format_tb(tb, limit=None):
    """A shorthand for 'format_list(extract_tb(tb, limit))',
    which returns a list of strings ready for printing'.
    """
    return extract_tb(tb, limit=limit).format()


In fact, perhaps the "shorthand" part is an implementation detail that may not even be correct (it doesn't immediately seem to be) and should be removed.

The doc strings were never updated in #17911. Would you like to submit a PR for these changes? (guidelines are available at https://devguide.python.org/pullrequest/) Perhaps, you could include similar changes in Doc/library/traceback.rst ?

If Aaron can't working on it, I can do it. Just tell me.

Thanks.

messages: + msg342589

type: behavior
stage: needs patch