From 5a087031bad323a3c8a8bffbac2ae8052c47ea6a Mon Sep 17 00:00:00 2001 From: Michele Angrisano Date: Thu, 16 May 2019 20:49:12 +0200 Subject: [PATCH 1/2] Update the docstring of traceback.format_tb() function --- Doc/library/traceback.rst | 3 ++- Lib/traceback.py | 4 +++- Misc/ACKS | 1 + .../Documentation/2019-05-16-14-51-15.bpo-36927.piw21p.rst | 2 ++ 4 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2019-05-16-14-51-15.bpo-36927.piw21p.rst diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 462a6a5566e201d..0986209b5c68f16 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -152,7 +152,8 @@ The module defines the following functions: .. function:: format_tb(tb, limit=None) - A shorthand for ``format_list(extract_tb(tb, limit))``. + A shorthand for ``format_list(extract_tb(tb, limit))``, + which returns a list of strings ready for printing. .. function:: format_stack(f=None, limit=None) diff --git a/Lib/traceback.py b/Lib/traceback.py index ab35da94b51eabe..178a22d015fbac3 100644 --- a/Lib/traceback.py +++ b/Lib/traceback.py @@ -53,7 +53,9 @@ 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))'.""" + """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): 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. From a60f317cb2ec3cb0115398be04b20b6770c60dca Mon Sep 17 00:00:00 2001 From: Michele Angrisano Date: Sun, 23 Jun 2019 13:25:17 +0200 Subject: [PATCH 2/2] bpo-36927: Improve the docstring and Doc of traceback module. * The methods updated: * print_exc() * print_last() * format_tb() * format_stack() --- Doc/library/traceback.rst | 40 ++++++++++++++++++++++++++++++++----- Lib/traceback.py | 42 ++++++++++++++++++++++++++++++++++----- 2 files changed, 72 insertions(+), 10 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 0986209b5c68f16..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,13 +168,27 @@ The module defines the following functions: .. function:: format_tb(tb, limit=None) - A shorthand for ``format_list(extract_tb(tb, limit))``, - which returns a list of strings ready for printing. + 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 178a22d015fbac3..0997e6b95d37174 100644 --- a/Lib/traceback.py +++ b/Lib/traceback.py @@ -53,7 +53,15 @@ 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() @@ -161,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): @@ -169,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, @@ -193,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))