python · mangrisano · May 16, 2019 · Jun 23, 2019
diff --git 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
@@ -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,16 +169,32 @@ 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):
    """Like print_exc() but return a string."""
    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
@@ -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
@@ -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.
Original file line number	Diff line number	Diff line change
		@@ -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.