From 69e9e8bd514717f74e19ba97a644ef47f0150534 Mon Sep 17 00:00:00 2001 From: Jeremy Hylton Date: Wed, 21 Mar 2001 19:09:31 +0000 Subject: [PATCH] Reformat and edit docstrings to follow modern conventions. Single line summary followed by blank line and description. --- Lib/traceback.py | 118 +++++++++++++++++++++++++++-------------------- 1 file changed, 68 insertions(+), 50 deletions(-) diff --git a/Lib/traceback.py b/Lib/traceback.py index 89ecb615d54..f887c058739 100644 --- 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.