Skip to content

Commit

Permalink
pythongh-102011: use sys.exception() instead of sys.exc_info() in doc…
Browse files Browse the repository at this point in the history
…s where possible (python#102012)
  • Loading branch information
iritkatriel authored Feb 20, 2023
1 parent 36854bb commit 4d3bc89
Show file tree
Hide file tree
Showing 6 changed files with 29 additions and 32 deletions.
2 changes: 1 addition & 1 deletion Doc/library/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ The following exceptions are used mostly as base classes for other exceptions.
try:
...
except SomeException:
tb = sys.exc_info()[2]
tb = sys.exception().__traceback__
raise OtherException(...).with_traceback(tb)

.. method:: add_note(note)
Expand Down
21 changes: 10 additions & 11 deletions Doc/library/traceback.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@ interpreter.

.. index:: object: traceback

The module uses traceback objects --- this is the object type that is stored in
the :data:`sys.last_traceback` variable and returned as the third item from
:func:`sys.exc_info`.
The module uses traceback objects --- these are objects of type :class:`types.TracebackType`,
which are assigned to the ``__traceback__`` field of :class:`BaseException` instances.

.. seealso::

Expand Down Expand Up @@ -81,7 +80,7 @@ The module defines the following functions:

.. function:: print_exc(limit=None, file=None, chain=True)

This is a shorthand for ``print_exception(*sys.exc_info(), limit, file,
This is a shorthand for ``print_exception(sys.exception(), limit, file,
chain)``.


Expand Down Expand Up @@ -444,24 +443,24 @@ exception and traceback:
try:
lumberjack()
except IndexError:
exc_type, exc_value, exc_traceback = sys.exc_info()
exc = sys.exception()
print("*** print_tb:")
traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
print("*** print_exception:")
traceback.print_exception(exc_value, limit=2, file=sys.stdout)
traceback.print_exception(exc, limit=2, file=sys.stdout)
print("*** print_exc:")
traceback.print_exc(limit=2, file=sys.stdout)
print("*** format_exc, first and last line:")
formatted_lines = traceback.format_exc().splitlines()
print(formatted_lines[0])
print(formatted_lines[-1])
print("*** format_exception:")
print(repr(traceback.format_exception(exc_value)))
print(repr(traceback.format_exception(exc)))
print("*** extract_tb:")
print(repr(traceback.extract_tb(exc_traceback)))
print(repr(traceback.extract_tb(exc.__traceback__)))
print("*** format_tb:")
print(repr(traceback.format_tb(exc_traceback)))
print("*** tb_lineno:", exc_traceback.tb_lineno)
print(repr(traceback.format_tb(exc.__traceback__)))
print("*** tb_lineno:", exc.__traceback__.tb_lineno)

The output for the example would look similar to this:

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ Standard names are defined for the following types:

.. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

The type of traceback objects such as found in ``sys.exc_info()[2]``.
The type of traceback objects such as found in ``sys.exception().__traceback__``.

See :ref:`the language reference <traceback-objects>` for details of the
available attributes and operations, and guidance on creating tracebacks
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/wsgiref.rst
Original file line number Diff line number Diff line change
Expand Up @@ -674,7 +674,7 @@ input, output, and error streams.
This method is a WSGI application to generate an error page for the user. It is
only invoked if an error occurs before headers are sent to the client.

This method can access the current error information using ``sys.exc_info()``,
This method can access the current error using ``sys.exception()``,
and should pass that information to *start_response* when calling it (as
described in the "Error Handling" section of :pep:`3333`).

Expand Down
33 changes: 15 additions & 18 deletions Doc/reference/compound_stmts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -301,31 +301,28 @@ keeping all locals in that frame alive until the next garbage collection occurs.
object: traceback

Before an :keyword:`!except` clause's suite is executed,
details about the exception are
stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
:func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
exception instance and a traceback object (see section :ref:`types`) identifying
the point in the program where the exception occurred. The details about the
exception accessed via :func:`sys.exc_info` are restored to their previous values
when leaving an exception handler::

>>> print(sys.exc_info())
(None, None, None)
the exception is stored in the :mod:`sys` module, where it can be accessed
from within the body of the :keyword:`!except` clause by calling
:func:`sys.exception`. When leaving an exception handler, the exception
stored in the :mod:`sys` module is reset to its previous value::

>>> print(sys.exception())
None
>>> try:
... raise TypeError
... except:
... print(sys.exc_info())
... print(repr(sys.exception()))
... try:
... raise ValueError
... except:
... print(sys.exc_info())
... print(sys.exc_info())
... print(repr(sys.exception()))
... print(repr(sys.exception()))
...
(<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
(<class 'ValueError'>, ValueError(), <traceback object at 0x10efad040>)
(<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
>>> print(sys.exc_info())
(None, None, None)
TypeError()
ValueError()
TypeError()
>>> print(sys.exception())
None


.. index::
Expand Down
1 change: 1 addition & 0 deletions Doc/reference/datamodel.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1122,6 +1122,7 @@ Internal types
single: exc_info (in module sys)
single: last_traceback (in module sys)
single: sys.exc_info
single: sys.exception
single: sys.last_traceback

Traceback objects represent a stack trace of an exception. A traceback object
Expand Down

0 comments on commit 4d3bc89

Please sign in to comment.