Reformat and edit docstrings to follow modern conventions. Single
line summary followed by blank line and description.
diff --git a/Lib/traceback.py b/Lib/traceback.py
index 89ecb61..f887c05 100644
--- a/Lib/traceback.py
+++ b/Lib/traceback.py
@@ -25,12 +25,15 @@
_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 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 @@
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 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 @@
_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 @@
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 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_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 @@
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 @@
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 @@
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.