The third and final doc-string sweep by Ka-Ping Yee.
The attached patches update the standard library so that all modules
have docstrings beginning with one-line summaries.
A new docstring was added to formatter. The docstring for os.py
was updated to mention nt, os2, ce in addition to posix, dos, mac.
diff --git a/Lib/traceback.py b/Lib/traceback.py
index 70d3230..61c07ff 100644
--- a/Lib/traceback.py
+++ b/Lib/traceback.py
@@ -1,4 +1,4 @@
-# Format and print Python stack traces
+"""Extract, format and print information about Python stack traces."""
import linecache
import string
@@ -10,6 +10,8 @@
def print_list(extracted_list, file=None):
+ """Print the list of tuples as returned by extract_tb() or
+ extract_stack() as a formatted stack trace to the given file."""
if not file:
file = sys.stderr
for filename, lineno, name, line in extracted_list:
@@ -19,6 +21,12 @@
_print(file, ' %s' % string.strip(line))
def format_list(extracted_list):
+ """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."""
list = []
for filename, lineno, name, line in extracted_list:
item = ' File "%s", line %d, in %s\n' % (filename,lineno,name)
@@ -29,6 +37,10 @@
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 not file:
file = sys.stderr
if limit is None:
@@ -49,9 +61,18 @@
n = n+1
def format_tb(tb, limit = None):
+ """A shorthand for 'format_list(extract_stack(f, limit))."""
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."""
if limit is None:
if hasattr(sys, 'tracebacklimit'):
limit = sys.tracebacklimit
@@ -73,6 +94,14 @@
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 (innermost 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."""
if not file:
file = sys.stderr
if tb:
@@ -84,6 +113,12 @@
_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
+ ending in a newline and some containing internal newlines. When
+ these lines are contatenated and printed, exactly the same text is
+ printed as does print_exception()."""
if tb:
list = ['Traceback (innermost last):\n']
list = list + format_tb(tb, limit)
@@ -93,6 +128,14 @@
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."""
list = []
if type(etype) == types.ClassType:
stype = etype.__name__
@@ -128,6 +171,10 @@
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)'.
+ (In fact, it uses sys.exc_info() to retrieve the same information
+ in a thread-safe way.)"""
if not file:
file = sys.stderr
try:
@@ -137,6 +184,8 @@
etype = value = tb = None
def print_last(limit=None, file=None):
+ """This is a shorthand for 'print_exception(sys.last_type,
+ sys.last_value, sys.last_traceback, limit, file)'."""
if not file:
file = sys.stderr
print_exception(sys.last_type, sys.last_value, sys.last_traceback,
@@ -144,6 +193,10 @@
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()."""
if f is None:
try:
raise ZeroDivisionError
@@ -152,6 +205,7 @@
print_list(extract_stack(f, limit), file)
def format_stack(f=None, limit=None):
+ """A shorthand for 'format_list(extract_stack(f, limit))'."""
if f is None:
try:
raise ZeroDivisionError
@@ -160,6 +214,12 @@
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 outermost
+ to innermost stack frame."""
if f is None:
try:
raise ZeroDivisionError
@@ -184,13 +244,14 @@
list.reverse()
return list
-# Calculate the correct line number of the traceback given in tb (even
-# 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.
-
def tb_lineno(tb):
+ """Calculate the correct line number of the traceback given in tb
+ (even 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.
+
c = tb.tb_frame.f_code
if not hasattr(c, 'co_lnotab'):
return tb.tb_lineno