<type>documentation</type>
<domain>debug</domain>
<id>managing-exceptions</id>
<title>Managing Exceptions</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

By default, Wing's debugger stops at exceptions when they would be printed by the Python
interpreter or when they are logged with ``logging.exception``. Wing will also stop on all
``AssertionError`` exceptions, whether or not they are printed or logged, since these
usually indicate a program error even if they are handled.  These behaviors can be
altered with the ``Debugger > Exceptions`` preference group, as described below.

**Ignoring Exceptions**

Individual exceptions can be ignored by checking the ``Ignore this exception location``
check box in the debugger's `Exceptions <script:show-panel-debug-exceptions>`__ tool and
continuing debug.

This is useful in ignoring non-critical exceptions that are being raised by code that
is not currently of interest, in order to be able to work on other problems.

Ignored exceptions are remembered in the project and may be cleared with ``Clear Ignored
Exceptions`` in the ``Debug`` menu.

Ignored exceptions are still reported if they actually lead to program termination.

**Exception Reporting Mode**

The overall strategy for identifying and reporting exceptions is configured with the
`Debugger > Exceptions > Report Exceptions
<script:show_preferences_gui#prefname="debug.exception-mode">`__ preference. The following
choices are available:

* **When Printed** stops on exceptions at the time that they would have been printed out by
  the Python interpreter. This is the default.
  
  For code with catch-all exceptions written in Python, Wing may fail to report unexpected
  exceptions if the handlers do not print the exception. In this case, it is best to rewrite
  the catch-all handlers as described in `Trouble-shooting Failure to Stop on Exceptions
  <ref:install/trouble-debug-nostop-exceptions>`__.
  
  Note that in this exception handling mode, any code in ``finally`` clauses, ``except``
  clauses that reraise the exception, and ``with`` statement cleanup routines will be
  executed before the debugger stops because they execute before the traceback is printed.

* **Always Immediately** stops at every single exception immediately when it is raised. In
  most code this will be very often, since exceptions may be used internally to handle
  normal, acceptible runtime conditions. As a result, this option is usually only useful
  after already running close to code that requires further examination.

  In Python 3.12+, StopIteration exceptions will not be reported in the **Always Immediately**
  mode because of optimizations in the interpreter.

* **At Process Termination** makes a best effort to stop and report exceptions that actually
  lead to process termination. This occurs just before or sometimes just after the process
  is terminated. The exception is also printed to ``stderr``, as it would be when running
  outside of the debugger.
  
  When working with an `Externally Launched Debug Process
  <ref:debug/debugging-externally-launched-code>`__ , this mode may not be able to stop
  the debug process before it exits, and in some cases may even fail to show any post-mortem
  traceback at all, except as printed to ``stderr`` by the debug process.

**Reporting Logged Exceptions**

The `Debugger > Exceptions > Report Logged Exceptions in When Printed Mode
<script:show_preferences_gui#prefname="debug.stop-on-logged-exception">`__ preference
controls whether exceptions that are not printed but that are logged with a call to
``logging.exception`` will be reported by the default ``When Printed`` exception reporting
mode. This preference is ignored in other exception reporting modes.

**Exception Type Filters**

The `Debugger > Exceptions > Never Report
<script:show_preferences_gui#prefname="debug.never-stop-exceptions">`__ and `Debugger >
Exceptions > Always Report
<script:show_preferences_gui#prefname="debug.always-stop-exceptions">`__ preferences can
be used to specify that certain exception types should never be reported at all, or always
reported regardless of whether they are printed or logged. For example, by default Wing
will never stop on ``SystemExit`` or ``GeneratorExit`` since these occur during normal
program behavior, and Wing will always stop on ``AssertionError`` since this usually
indicates a bug in code even if it is handled.

In some code, adding ``NameError`` or ``AttributeError`` to the ``Always Report`` list may
help to uncover bugs that are being masked by overly broad exception handlers. However,
this will not work if these are treated as normal expected exceptions. This is common
enough that they are not included in Wing's default ``Always Report`` list.

