<type>documentation</type>
<domain>debug</domain>
<id>problems-handling-values</id>
<title>Problems Handling Values</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

Wing's debugger tries to handle debug process data as gently as possible, in order to avoid
entering into lengthy computations or triggering errors in the debug process. Even so, not
all debug data can be shown on the display. This section describes each of the reasons why
this may happen.

**Huge Values**

Wing may consider values too large to handle if it thinks that packaging the value for
transfer to the IDE would hang up the debug process. These values are displayed in the form
``<huge type 0x803ca872>`` in the ``Stack Data`` tool.

Some values that are too large for display in the ``Stack Data`` tool may still be viewed as
arrays by right-clicking on the value and selecting ``Show Value as Array``. Arrays are
loaded incrementally according to what is visible on screen, and thus are less subject to
size thresholds.

~~~if WINGPRO:
An alternative available in Wing Pro for viewing large data values is to enter expressions
into the `Watch <ref:debug/evaluating-expressions>`__ tool or `Debug Console
<ref:debug/debug-console>`__, in order to view parts of the data without
transferring the whole value to the IDE.
~~~

The thresholds that are used to determine whether a value is too large to display may be
set in the `Debug > Data Display > Huge List Threshold
<script:show_preferences_gui#prefname="debug.huge-list-threshold">`__ and `Debug > Data
Display > Huge String Threshold
<script:show_preferences_gui#prefname="debug.huge-string-threshold">`__ preferences. The
former controls how large ``len(value)`` may be and the latter controls how long a string
may be. Setting these preferences higher may increase data transfer times and may require
also increasing the `Debugger > Network > Network Timeout
<script:show_preferences_gui#prefname="debug.network-timeout">`__ preference to prevent
timeouts.

**Data Handling Errors**

Wing may encounter errors during data handling because the inspection and packaging
process may call special methods such as ``__cmp__`` and ``__str__`` in your code. If
these methods have bugs in them, the debugger may reveal those bugs at times when you would
otherwise not see them.

The rare worst case scenario is crashing of the debug process if flawed C or C++ extension
module code is invoked. In this case, the debug session is ended.

More common, but still rare, are cases where Wing encounters an unexpected Python
exception while handling a debug data value. When this happens, the value is displayed as
``<error handling value>``.

These errors are not reported in the ``Exceptions`` tool. However, extra output containing 
the exception being raised can be obtained by setting the `Debugger > Diagnostics
> Debug Internals Log File <script:show_preferences_gui#prefname="debug.logfile">`__ 
preference.
~~~if WINGPRO:
Or, in Wing Pro, try inspecting the value with the `Debug Console <ref:debug/debug-console>`__.
~~~

Options that can prevent some types of data handling errors are documented in 
`Advanced Data Display <ref:debug/advanced-data-display>`__.

**Opaque Values**

Wing may treat values as opaque if they cannot be converted into a form
that can be displayed in the IDE. This happens only rarely for data types defined
within C/C++ code, or if a value contains certain Python language internals.  Opaque 
values are denoted in the form ``<opaque 0x80ce784>`` and cannot be expanded further.
~~~if WINGPRO:
In Wing Pro you may be able to use the `Debug Console <ref:debug/debug-console>`__
to access them (for example try typing ``dir(varname)``).
~~~

**Value Timeouts**

Wing may time out handling a value when packaging it hangs up the debug process. The debugger
tries to avoid this by carefully probing a value's size before packing it up. In some
cases, this does not work, causing the debugger to wait for the duration set by the `Debugger >
Network > Network Timeout
<script:show_preferences_gui#prefname="debug.network-timeout">`__ preference and then
displaying the value as ``<network timeout during evaluate>``.

Managing Value Errors
---------------------

Wing remembers all debug data handling errors that it encounters and stores them in the
project file. These values will not be refetched during subsequent debugging, even if Wing
is quit and restarted.

To override this behavior for an individual value, use ``Force Reload`` in the
right-click context menu on the value.

To clear the list of all errors previously encountered, so that all values are reloaded,
use ``Clear Stored Value Errors`` in the ``Debug`` menu. This operates only on the list of
errors known for the current debug main entry point, if a debug session is active, or for
the main entry point, if any, when no debug process is running.

To avoid reoccurrence of more severe data value handling errors after clearing stored
value errors, see `Filtering Value Display <ref:debug/filtering-value-display>`__.
