Reformat and edit docstrings to follow modern conventions. Single

jeremyhylton · jeremyhylton · commit 69e9e8bd5147 · 2001-03-21T19:09:31.000Z
line summary followed by blank line and description.
diff --git a/Lib/traceback.py b/Lib/traceback.py
@@ -25,12 +25,15 @@ def print_list(extracted_list, file=None):
             _print(file, '    %s' % line.strip())
 
 def format_list(extracted_list):
-    """Given a list of tuples as returned by extract_tb() or
+    """Format a list of traceback entry tuples for printing.
+
+    Given a list of tuples as returned by extract_tb() or
     extract_stack(), return a list of strings ready for printing.
-    Each string in the resulting list corresponds to the item with
-    the same index in the argument list.  Each string ends in a
-    newline; the strings may contain internal newlines as well, for
-    those items whose source text line is not None."""
+    Each string in the resulting list corresponds to the item with the
+    same index in the argument list.  Each string ends in a newline;
+    the strings may contain internal newlines as well, for those items
+    whose source text line is not None.
+    """
     list = []
     for filename, lineno, name, line in extracted_list:
         item = '  File "%s", line %d, in %s\n' % (filename,lineno,name)
@@ -42,9 +45,12 @@ def format_list(extracted_list):
 
 def print_tb(tb, limit=None, file=None):
     """Print up to 'limit' stack trace entries from the traceback 'tb'.
-    If 'limit' is omitted or None, all entries are printed.  If '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."""
+
+    If 'limit' is omitted or None, all entries are printed.  If '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.
+    """
     if not file:
         file = sys.stderr
     if limit is None:
@@ -69,14 +75,16 @@ def format_tb(tb, limit = None):
     return format_list(extract_tb(tb, limit))
 
 def extract_tb(tb, limit = None):
-    """Return a list of up to 'limit' pre-processed stack trace entries
-    extracted from the traceback object 'traceback'.  This is useful for
-    alternate formatting of stack traces.  If 'limit' is omitted or None,
-    all entries are extracted.  A pre-processed stack trace entry is a
-    quadruple (filename, line number, function name, text) representing
-    the information that is usually printed for a stack trace.  The text
-    is a string with leading and trailing whitespace stripped; if the
-    source is not available it is None."""
+    """Return list of up to limit pre-processed entries from traceback.
+
+    This is useful for alternate formatting of stack traces.  If
+    'limit' is omitted or None, all entries are extracted.  A
+    pre-processed stack trace entry is a quadruple (filename, line
+    number, function name, text) representing the information that is
+    usually printed for a stack trace.  The text is a string with
+    leading and trailing whitespace stripped; if the source is not
+    available it is None.
+    """
     if limit is None:
         if hasattr(sys, 'tracebacklimit'):
             limit = sys.tracebacklimit
@@ -98,14 +106,16 @@ def extract_tb(tb, limit = None):
 
 
 def print_exception(etype, value, tb, limit=None, file=None):
-    """Print exception information and up to 'limit' stack trace entries
-    from the traceback 'tb' to 'file'.  This differs from print_tb() in
-    the following ways: (1) if traceback is not None, it prints a header
-    "Traceback (most recent call last):"; (2) it prints the exception type and
-    value after the stack trace; (3) if type is SyntaxError and value has
-    the appropriate format, it prints the line where the syntax error
+    """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
+
+    This differs from print_tb() in the following ways: (1) if
+    traceback is not None, it prints a header "Traceback (most recent
+    call last):"; (2) it prints the exception type and value after the
+    stack trace; (3) if type is SyntaxError and value has the
+    appropriate format, it prints the line where the syntax error
     occurred with a caret on the next line indicating the approximate
-    position of the error."""
+    position of the error.
+    """
     if not file:
         file = sys.stderr
     if tb:
@@ -117,12 +127,14 @@ def print_exception(etype, value, tb, limit=None, file=None):
     _print(file, lines[-1], '')
 
 def format_exception(etype, value, tb, limit = None):
-    """Format a stack trace and the exception information.  The arguments
-    have the same meaning as the corresponding arguments to
-    print_exception().  The return value is a list of strings, each
+    """Format a stack trace and the exception information.
+
+    The arguments have the same meaning as the corresponding arguments
+    to print_exception().  The return value is a list of strings, each
     ending in a newline and some containing internal newlines.  When
     these lines are concatenated and printed, exactly the same text is
-    printed as does print_exception()."""
+    printed as does print_exception().
+    """
     if tb:
         list = ['Traceback (most recent call last):\n']
         list = list + format_tb(tb, limit)
@@ -132,14 +144,16 @@ def format_exception(etype, value, tb, limit = None):
     return list
 
 def format_exception_only(etype, value):
-    """Format the exception part of a traceback.  The arguments are the
-    exception type and value such as given by sys.last_type and
-    sys.last_value. The return value is a list of strings, each ending
-    in a newline.  Normally, the list contains a single string;
-    however, for SyntaxError exceptions, it contains several lines that
-    (when printed) display detailed information about where the syntax
-    error occurred.  The message indicating which exception occurred is
-    the always last string in the list."""
+    """Format the exception part of a traceback.
+
+    The arguments are the exception type and value such as given by
+    sys.last_type and sys.last_value. The return value is a list of
+    strings, each ending in a newline.  Normally, the list contains a
+    single string; however, for SyntaxError exceptions, it contains
+    several lines that (when printed) display detailed information
+    about where the syntax error occurred.  The message indicating
+    which exception occurred is the always last string in the list.
+    """
     list = []
     if type(etype) == types.ClassType:
         stype = etype.__name__
@@ -184,8 +198,7 @@ def _some_str(value):
 
 
 def print_exc(limit=None, file=None):
-    """This is a shorthand for 'print_exception(sys.exc_type,
-    sys.exc_value, sys.exc_traceback, limit, file)'.
+    """Shorthand for 'print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)'.
     (In fact, it uses sys.exc_info() to retrieve the same information
     in a thread-safe way.)"""
     if not file:
@@ -206,10 +219,12 @@ def print_last(limit=None, file=None):
 
 
 def print_stack(f=None, limit=None, file=None):
-    """This function prints a stack trace from its invocation point.
-    The optional 'f' argument can be used to specify an alternate stack
-    frame at which to start. The optional 'limit' and 'file' arguments
-    have the same meaning as for print_exception()."""
+    """Print a stack trace from its invocation point.
+    
+    The optional 'f' argument can be used to specify an alternate
+    stack frame at which to start. The optional 'limit' and 'file'
+    arguments have the same meaning as for print_exception().
+    """
     if f is None:
         try:
             raise ZeroDivisionError
@@ -218,7 +233,7 @@ def print_stack(f=None, limit=None, file=None):
     print_list(extract_stack(f, limit), file)
 
 def format_stack(f=None, limit=None):
-    """A shorthand for 'format_list(extract_stack(f, limit))'."""
+    """Shorthand for 'format_list(extract_stack(f, limit))'."""
     if f is None:
         try:
             raise ZeroDivisionError
@@ -227,12 +242,14 @@ def format_stack(f=None, limit=None):
     return format_list(extract_stack(f, limit))
 
 def extract_stack(f=None, limit = None):
-    """Extract the raw traceback from the current stack frame.  The
-    return value has the same format as for extract_tb().  The optional
-    'f' and 'limit' arguments have the same meaning as for print_stack().
-    Each item in the list is a quadruple (filename, line number,
-    function name, text), and the entries are in order from oldest
-    to newest stack frame."""
+    """Extract the raw traceback from the current stack frame.
+
+    The return value has the same format as for extract_tb().  The
+    optional 'f' and 'limit' arguments have the same meaning as for
+    print_stack().  Each item in the list is a quadruple (filename,
+    line number, function name, text), and the entries are in order
+    from oldest to newest stack frame.
+    """
     if f is None:
         try:
             raise ZeroDivisionError
@@ -258,9 +275,10 @@ def extract_stack(f=None, limit = None):
     return list
 
 def tb_lineno(tb):
-    """Calculate the correct line number of the traceback given in tb
-    (even with -O on)."""
+    """Calculate correct line number of traceback given in tb.
 
+    Even works with -O on.
+    """
     # Coded by Marc-Andre Lemburg from the example of PyCode_Addr2Line()
     # in compile.c.
     # Revised version by Jim Hugunin to work with JPython too.
