mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 19:12:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 14

Issue #17911: Tweak traceback documentation.

Browse source 
Changes:

* Fixed reSt markup
* Fixed cross references
* Fixed a couple of typos
This commit is contained in:
Berker Peksag 2015-03-06 12:18:06 +02:00
parent 4a13cb94d3
commit 49f373bf66
1 changed files with 95 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

166
Doc/library/traceback.rst
View file

@ -138,16 +138,16 @@ The module defines the following functions:
.. function:: walk_stack(f) .. function:: walk_stack(f)
Walk a stack following f.f_back from the given frame, yielding the frame and Walk a stack following ``f.f_back`` from the given frame, yielding the frame
line number for each frame. If f is None, the current stack is used. and line number for each frame. If *f* is ``None``, the current stack is
This helper is used with *Stack.extract*. used. This helper is used with :meth:`StackSummary.extract`.
.. versionadded:: 3.5 .. versionadded:: 3.5
.. function:: walk_tb(tb) .. function:: walk_tb(tb)
Walk a traceback following tb_next yielding the frame and line number for Walk a traceback following ``tb_next`` yielding the frame and line number
each frame. This helper is used with *Stack.extract*. for each frame. This helper is used with :meth:`StackSummary.extract`.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -156,118 +156,142 @@ The module also defines the following classes:
:class:`TracebackException` Objects :class:`TracebackException` Objects
----------------------------------- -----------------------------------
:class:`.TracebackException` objects are created from actual exceptions to .. 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 in a lightweight fashion.
.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False) .. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)
Capture an exception for later rendering. limit, lookup_lines and Capture an exception for later rendering. *limit*, *lookup_lines* and
capture_locals=False are as for the :class:`.StackSummary` class. *capture_locals* are as for the :class:`StackSummary` class.
Note that when locals are captured, they are also shown in the traceback. Note that when locals are captured, they are also shown in the traceback.
.. versionadded:: 3.5 .. attribute:: __cause__
.. classmethod:: `.from_exception`(exc, *, limit=None, lookup_lines=True, capture_locals=False) A :class:`TracebackException` of the original ``__cause__``.
Capture an exception for later rendering. limit, lookup_lines and .. attribute:: __context__
capture_locals=False are as for the :class:`.StackSummary` class.
Note that when locals are captured, they are also shown in the traceback. A :class:`TracebackException` of the original ``__context__``.
.. versionadded:: 3.5 .. attribute:: __suppress_context__
.. attribute:: `.__cause__` A TracebackException of the original *__cause__*. The ``__suppress_context__`` value from the original exception.
.. attribute:: `.__context__` A TracebackException of the original *__context__*. .. attribute:: stack
.. attribute:: `.__suppress_context__` The *__suppress_context__* value from the
original exception.
.. attribute:: `.stack` A `StackSummary` representing the traceback.
.. attribute:: `.exc_type` The class of the original traceback.
.. attribute:: `.filename` For syntax errors - the filename where the error
occured.
.. attribute:: `.lineno` For syntax errors - the linenumber where the error
occured.
.. attribute:: `.text` For syntax errors - the text where the error
occured.
.. attribute:: `.offset` For syntax errors - the offset into the text where the
error occured.
.. attribute:: `.msg` For syntax errors - the compiler error message.
.. method:: TracebackException.format(*, chain=True) A :class:`StackSummary` representing the traceback.
Format the exception. .. attribute:: exc_type
If chain is not *True*, *__cause__* and *__context__* will not be formatted. The class of the original traceback.
The return value is a generator of strings, each ending in a newline and .. attribute:: filename
some containing internal newlines. `print_exception` is a wrapper around
this method which just prints the lines to a file.
The message indicating which exception occurred is always the last For syntax errors - the file name where the error occurred.
string in the output.
.. versionadded:: 3.5 .. attribute:: lineno
.. method:: TracebackException.format_exception_only() For syntax errors - the line number where the error occurred.
Format the exception part of the traceback. .. attribute:: text
The return value is a generator of strings, each ending in a newline. For syntax errors - the text where the error occurred.
Normally, the generator emits a single string; however, for .. attribute:: offset
SyntaxError exceptions, it emites several lines that (when
printed) display detailed information about where the syntax
error occurred.
The message indicating which exception occurred is always the last For syntax errors - the offset into the text where the error occurred.
string in the output.
.. versionadded:: 3.5 .. attribute:: msg
For syntax errors - the compiler error message.
.. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)
Capture an exception for later rendering. *limit*, *lookup_lines* and
*capture_locals* are as for the :class:`StackSummary` class.
Note that when locals are captured, they are also shown in the traceback.
.. method:: format(*, chain=True)
Format the exception.
If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not
be formatted.
The return value is a generator of strings, each ending in a newline and
some containing internal newlines. :func:`~traceback.print_exception`
is a wrapper around this method which just prints the lines to a file.
The message indicating which exception occurred is always the last
string in the output.
.. method:: format_exception_only()
Format the exception part of the traceback.
The return value is a generator of strings, each ending in a newline.
Normally, the generator emits a single string; however, for
:exc:`SyntaxError` exceptions, it emits several lines that (when
printed) display detailed information about where the syntax
error occurred.
The message indicating which exception occurred is always the last
string in the output.
:class:`StackSummary` Objects :class:`StackSummary` Objects
----------------------------- -----------------------------
:class:`.StackSummary` objects represent a call stack ready for formatting. .. versionadded:: 3.5
.. classmethod:: StackSummary.extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False) :class:`StackSummary` objects represent a call stack ready for formatting.
Construct a StackSummary object from a frame generator (such as is returned by .. class:: StackSummary
`walk_stack` or `walk_tb`.
If limit is supplied, only this many frames are taken from frame_gen. .. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
If lookup_lines is False, the returned FrameSummary objects will not have read
their lines in yet, making the cost of creating the StackSummary cheaper (which
may be valuable if it may not actually get formatted).
If capture_locals is True the local variables in each *FrameSummary* are
captured as object representations.
.. versionadded:: 3.5 Construct a :class:`StackSummary` object from a frame generator (such as
is returned by :func:`~traceback.walk_stack` or
:func:`~traceback.walk_tb`).
.. classmethod:: StackSummary.from_list(a_list) If *limit* is supplied, only this many frames are taken from *frame_gen*.
If *lookup_lines* is ``False``, the returned :class:`FrameSummary`
objects will not have read their lines in yet, making the cost of
creating the :class:`StackSummary` cheaper (which may be valuable if it
may not actually get formatted). If *capture_locals* is ``True`` the
local variables in each :class:`FrameSummary` are captured as object
representations.
Construct a StackSummary object from a supplied old-style list of tuples. Each .. classmethod:: from_list(a_list)
tuple should be a 4-tuple with filename, lineno, name, line as the elements.
Construct a :class:`StackSummary` object from a supplied old-style list
of tuples. Each tuple should be a 4-tuple with filename, lineno, name,
line as the elements.
.. versionadded:: 3.5
:class:`FrameSummary` Objects :class:`FrameSummary` Objects
----------------------------- -----------------------------
FrameSummary objects represent a single frame in a traceback. .. versionadded:: 3.5
:class:`FrameSummary` objects represent a single frame in a traceback.
.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None) .. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
:noindex:
Represent a single frame in the traceback or stack that is being formatted Represent a single frame in the traceback or stack that is being formatted
or printed. It may optionally have a stringified version of the frames or printed. It may optionally have a stringified version of the frames
locals included in it. If *lookup_line* is False, the source code is not locals included in it. If *lookup_line* is ``False``, the source code is not
looked up until the FrameSummary has the :attr:`line` attribute accessed (which looked up until the :class:`FrameSummary` has the :attr:`~FrameSummary.line`
also happens when casting it to a tuple). *line* may be directly provided, and attribute accessed (which also happens when casting it to a tuple).
will prevent line lookups happening at all. *locals* is an optional local variable :attr:`~FrameSummary.line` may be directly provided, and will prevent line
dictionary, and if supplied the variable representations are stored in the summary lookups happening at all. *locals* is an optional local variable
for later display. dictionary, and if supplied the variable representations are stored in the
summary for later display.
.. _traceback-example: .. _traceback-example: