diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 462a6a5566e201d..9a7ece7662aec10 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -65,13 +65,29 @@ The module defines the following functions: .. function:: print_exc(limit=None, file=None, chain=True) - This is a shorthand for ``print_exception(*sys.exc_info(), limit, file, + Print exception up to *limit* stack trace entries from *tb* to *file*. + + The optional argument *limit* defines how many entries are printed. If it + is omitted or ``None``, all the entries are printed. + If the optional argument *file* is omitted or ``None``, the outuput goes to + ``sys.stderr``; otherwise *file* should be an open file or file-like object + with a write() method. + + It is a shorthand for ``print_exception(*sys.exc_info(), limit, file, chain)``. .. function:: print_last(limit=None, file=None, chain=True) - This is a shorthand for ``print_exception(sys.last_type, sys.last_value, + Print the last exception and the stack trace. + + The optional argument *limit* defines how many entries are printed. If it + is omitted or ``None``, all the entries are printed. + If the optional argument *file* is omitted or ``None``, the output goes to + ``sys.stderr``; otherwise *file* should be an open file or file-like object + with a write() method. + + It is a shorthand for ``print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain)``. In general it will work only after an exception has reached an interactive prompt (see :data:`sys.last_type`). @@ -152,12 +168,27 @@ The module defines the following functions: .. function:: format_tb(tb, limit=None) - A shorthand for ``format_list(extract_tb(tb, limit))``. + Return an :func:`extract_tb` object which returns a list of pre-processed + entries from *tb*. + + The argument *tb* is the traceback to be foramtted. + The optional argument *limit* defines how many entries are formatted. + If it is omitted or ``None``, all entries are formatted ready to be + printed. + + It is a shorthand for ``format_list(extract_tb(tb, limit))``. .. function:: format_stack(f=None, limit=None) - A shorthand for ``format_list(extract_stack(f, limit))``. + Return a :func:`format_list` object which is a list of strings with the + messages of the traceback formatted ready to be printed. + + The optional argument *f* is the stack frame from which to start. + The optional argument *limit* defines how many entries are formatted. + If it is omitted or ``None``, all entries are formatted. + + It is a shorthand for ``format_list(extract_stack(f, limit))``. .. function:: clear_frames(tb) diff --git a/Lib/traceback.py b/Lib/traceback.py index ab35da94b51eabe..0997e6b95d37174 100644 --- a/Lib/traceback.py +++ b/Lib/traceback.py @@ -53,7 +53,17 @@ def print_tb(tb, limit=None, file=None): print_list(extract_tb(tb, limit=limit), file=file) def format_tb(tb, limit=None): - """A shorthand for 'format_list(extract_tb(tb, limit))'.""" + """Return an 'extract_tb' object which returns a list of pre-processed + entries from 'tb'. + + The argument 'tb' is the traceback to be foramtted. + The optional argument 'limit' defines how many entries are formatted. + If it is omitted or None, then all entries are formatted ready to be + printed. + + It is 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() def extract_tb(tb, limit=None): @@ -159,7 +169,15 @@ def _some_str(value): # -- def print_exc(limit=None, file=None, chain=True): - """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'.""" + """Print exception up to 'limit' stack trace entries from 'tb' to 'file'. + + The optional argument 'limit' defines how many entries are printed. + If the optional argument 'file' is omitted or None, the output goes to + sys.stderr; otherwise 'file' should be an open file or file-like object + with a write() method. + + It is a shorthand for 'print_exception(*sys.exc_info(), limit, file)'. + """ print_exception(*sys.exc_info(), limit=limit, file=file, chain=chain) def format_exc(limit=None, chain=True): @@ -167,8 +185,16 @@ def format_exc(limit=None, chain=True): return "".join(format_exception(*sys.exc_info(), limit=limit, chain=chain)) def print_last(limit=None, file=None, chain=True): - """This is a shorthand for 'print_exception(sys.last_type, - sys.last_value, sys.last_traceback, limit, file)'.""" + """Print the last exception and the stack trace. + + The optional argument 'limit' defines how many entries are printed. + If the optional argument 'file' is omitted or None, the oputput goes to + sys.stderr; otherwise 'file' should be an open file or file-like object + with a write() method. + + It is a shorthand for 'print_exception(sys.last_type, + sys.last_value, sys.last_traceback, limit, file)'. + """ if not hasattr(sys, "last_type"): raise ValueError("no last exception") print_exception(sys.last_type, sys.last_value, sys.last_traceback, @@ -191,7 +217,15 @@ def print_stack(f=None, limit=None, file=None): def format_stack(f=None, limit=None): - """Shorthand for 'format_list(extract_stack(f, limit))'.""" + """Return a 'format_list' object which is a list of strings with the + messages of the traceback formatted ready to be printed. + + The optional argument 'f' is the stack frame from which to start. + The optional argument 'limit' defines how many entries are formatted. + If it is omitted or None, then all entries are formatted. + + It is a shorthand for 'format_list(extract_stack(f, limit))'. + """ if f is None: f = sys._getframe().f_back return format_list(extract_stack(f, limit=limit)) diff --git a/Misc/ACKS b/Misc/ACKS index 06e288dfcb2f18c..6fea3a5f1e4471b 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -55,6 +55,7 @@ Juancarlo Añez Chris Angelico Jérémy Anger Jon Anglin +Michele Angrisano Ankur Ankan Heidi Annexstad Ramchandra Apte diff --git a/Misc/NEWS.d/next/Documentation/2019-05-16-14-51-15.bpo-36927.piw21p.rst b/Misc/NEWS.d/next/Documentation/2019-05-16-14-51-15.bpo-36927.piw21p.rst new file mode 100644 index 000000000000000..3a0b757bd8277a8 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-05-16-14-51-15.bpo-36927.piw21p.rst @@ -0,0 +1,2 @@ +Make the docstring of :meth:`format_tb` more clean than the previous one. +Now it's clear that :meth:`format_tb` returns a list of strings.