--------------
-This module provides a standard interface to extract, format and print stack
-traces of Python programs. It exactly mimics the behavior of the Python
-interpreter when it prints a stack trace. This is useful when you want to print
-stack traces under program control, such as in a "wrapper" around the
-interpreter.
+This module provides a standard interface to extract, format and print
+stack traces of Python programs. It is more flexible than the
+interpreter's default traceback display, and therefore makes it
+possible to configure certain aspects of the output. Finally,
+it contains a utility for capturing enough information about an
+exception to print it later, without the need to save a reference
+to the actual exception. Since exceptions can be the roots of large
+objects graph, this utility can significantly improve
+memory management.
.. index:: pair: object; traceback
Module :mod:`pdb`
Interactive source code debugger for Python programs.
-The module defines the following functions:
+The module's API can be divided into two parts:
+
+* Module-level functions offering basic functionality, which are useful for interactive
+ inspection of exceptions and tracebacks.
+
+* :class:`TracebackException` class and its helper classes
+ :class:`StackSummary` and :class:`FrameSummary`. These offer both more
+ flexibility in the output generated and the ability to store the information
+ necessary for later formatting without holding references to actual exception
+ and traceback objects.
+
+
+Module-Level Functions
+----------------------
.. function:: print_tb(tb, limit=None, file=None)
.. versionadded:: 3.5
-The module also defines the following classes:
:class:`!TracebackException` Objects
------------------------------------
.. versionadded:: 3.5
:class:`!TracebackException` objects are created from actual exceptions to
-capture data for later printing in a lightweight fashion.
+capture data for later printing. They offer a more lightweight method of
+storing this information by avoiding holding references to
+:ref:`traceback<traceback-objects>` and :ref:`frame<frame-objects>` objects
+In addition, they expose more options to configure the output compared to
+the module-level functions described above.
.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)
- Capture an exception for later rendering. *limit*, *lookup_lines* and
- *capture_locals* are as for the :class:`StackSummary` class.
+ Capture an exception for later rendering. The meaning of *limit*,
+ *lookup_lines* and *capture_locals* are as for the :class:`StackSummary`
+ class.
If *compact* is true, only data that is required by
:class:`!TracebackException`'s :meth:`format` method
.. _traceback-example:
-Traceback Examples
-------------------
+Examples of Using the Module-Level Functions
+--------------------------------------------
This simple example implements a basic read-eval-print loop, similar to (but
less useful than) the standard Python interactive interpreter loop. For a more
try:
lumberjack()
- except IndexError:
- exc = sys.exception()
+ except IndexError as exc:
print("*** print_tb:")
traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
print("*** print_exception:")
[' File "spam.py", line 3, in <module>\n spam.eggs()\n',
' File "eggs.py", line 42, in eggs\n return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
- >>> traceback.format_exception_only(type(an_error), an_error)
+ >>> traceback.format_exception_only(an_error)
['IndexError: tuple index out of range\n']
+
+
+Examples of Using :class:`TracebackException`
+---------------------------------------------
+
+With the helper class, we have more options::
+
+ >>> import sys
+ >>> from traceback import TracebackException
+ >>>
+ >>> def lumberjack():
+ ... bright_side_of_life()
+ ...
+ >>> def bright_side_of_life():
+ ... t = "bright", "side", "of", "life"
+ ... return t[5]
+ ...
+ >>> try:
+ ... lumberjack()
+ ... except IndexError as e:
+ ... exc = e
+ ...
+ >>> try:
+ ... try:
+ ... lumberjack()
+ ... except:
+ ... 1/0
+ ... except Exception as e:
+ ... chained_exc = e
+ ...
+ >>> # limit works as with the module-level functions
+ >>> TracebackException.from_exception(exc, limit=-2).print()
+ Traceback (most recent call last):
+ File "<python-input-1>", line 6, in lumberjack
+ bright_side_of_life()
+ ~~~~~~~~~~~~~~~~~~~^^
+ File "<python-input-1>", line 10, in bright_side_of_life
+ return t[5]
+ ~^^^
+ IndexError: tuple index out of range
+
+ >>> # capture_locals adds local variables in frames
+ >>> TracebackException.from_exception(exc, limit=-2, capture_locals=True).print()
+ Traceback (most recent call last):
+ File "<python-input-1>", line 6, in lumberjack
+ bright_side_of_life()
+ ~~~~~~~~~~~~~~~~~~~^^
+ File "<python-input-1>", line 10, in bright_side_of_life
+ return t[5]
+ ~^^^
+ t = ("bright", "side", "of", "life")
+ IndexError: tuple index out of range
+
+ >>> # The *chain* kwarg to print() controls whether chained
+ >>> # exceptions are displayed
+ >>> TracebackException.from_exception(chained_exc).print()
+ Traceback (most recent call last):
+ File "<python-input-19>", line 4, in <module>
+ lumberjack()
+ ~~~~~~~~~~^^
+ File "<python-input-8>", line 7, in lumberjack
+ bright_side_of_life()
+ ~~~~~~~~~~~~~~~~~~~^^
+ File "<python-input-8>", line 11, in bright_side_of_life
+ return t[5]
+ ~^^^
+ IndexError: tuple index out of range
+
+ During handling of the above exception, another exception occurred:
+
+ Traceback (most recent call last):
+ File "<python-input-19>", line 6, in <module>
+ 1/0
+ ~^~
+ ZeroDivisionError: division by zero
+
+ >>> TracebackException.from_exception(chained_exc).print(chain=False)
+ Traceback (most recent call last):
+ File "<python-input-19>", line 6, in <module>
+ 1/0
+ ~^~
+ ZeroDivisionError: division by zero
+
projects / thirdparty / Python / cpython.git / commitdiff
