Debian Codegraph @

docs/source/traits_user_manual/debugging.rst

raw
1 .. index:: debugging, exceptions, trace trait change events
2
3 =========================
4 Tips for debugging Traits
5 =========================
6
7
8 Re-raising exceptions in change handlers
9 ========================================
10
11 Traits will typically log (instead of raise) exceptions when an exception is
12 encountered in a trait-change handler. This behavior is often preferred in
13 applications, since you usually want to avoid critical failures in
14 applications. However, when debugging these errors, the
15 ``logging.Logger.exception`` only displays the tip of the traceback. For example,
16 the following code changes a ``constant``:
17
18 .. code-block:: python
19
20 from traits.api import HasTraits, Int
21
22 class Curmudgeon(HasTraits):
23 constant = Int(1)
24 def _constant_changed(self):
25 raise ValueError()
26
27 c = Curmudgeon()
28 c.constant = 42
29
30 The ``constant`` trait-change handler raises an exception that is caught and
31 logged::
32
33 Exception occurred in traits notification handler.
34 Please check the log file for details.
35 Exception occurred in traits notification handler for object:
36 <__main__.Curmudgeon object at 0x107603050>, trait: constant, old value: 0, new value: 42
37 ...
38 File "curmudgeon.py", line 12, in _constant_changed
39 raise ValueError()
40 ValueError
41
42 This logged exception, however, only contains the tip of the traceback. This
43 makes debugging a bit difficult. You can force exceptions to be re-raised
44 by adding a custom exception handler:
45
46 .. code-block:: python
47
48 from traits.api import push_exception_handler
49 push_exception_handler(reraise_exceptions=True)
50
51 (For example, you could add this to the top of the original code block.)
52
53 Re-running the original code example with this custom handler will now raise
54 the following traceback::
55
56 Traceback (most recent call last):
57 File "curmudgeon.py", line 15, in <module>
58 c.constant = 42
59 ...
60 File "curmudgeon.py", line 12, in _constant_changed
61 raise ValueError()
62 ValueError
63
64 Notice that this traceback has information about *where* we changed
65 ``constant``. Note: This is a toy example; use ``Constant`` from
66 ``traits.api`` if you actually want a constant trait.
67
68
69 Tracing Traits Change Events
70 ============================
71
72 Occasionally it is necessary to find the chain of event dispatches in traits
73 classes. To help with debugging, a |record_events| context manager is provided
74 in :mod:`traits.util.event_tracer`. Trait change events taking place inside the
75 context block will be recorded in a change event container (see example below)
76 and can be saved to files (a file for each thread) for further inspection.
77
78
79 Example:
80
81 .. code-block:: python
82
83 from traits.api import *
84 from traits.util.event_tracer import record_events
85
86
87 class MyModel(HasTraits):
88
89 number = Float(2.0)
90 list_of_numbers = List(Float())
91 count = Int(0)
92
93 @on_trait_change('number')
94 def _add_number_to_list(self, value):
95 self.list_of_numbers.append(value)
96
97 @on_trait_change('list_of_numbers[]')
98 def _count_items(self):
99 self.count = len(self.list_on_numbers)
100
101 def add_to_number(self, value):
102 self.number += value
103
104
105 my_model = MyModel()
106
107 with record_events() as change_event_container:
108 my_model.number = 4.7
109 my_model.number = 3
110
111 # save files locally
112 change_event_container.save_to_directory('./')
113
114
115 Running the above example will write a file named MAinThread.trace in the
116 local folder. The file contents will be similar to the lines below::
117
118 2014-03-21 14:11:20.779000 -> 'number' changed from 2.0 to 4.7 in 'MyModel'
119 2014-03-21 14:11:20.779000 CALLING: '_add_number_to_list' in example.py
120 2014-03-21 14:11:20.780000 ---> 'list_of_numbers_items' changed from <undefined> to <traits.trait_handlers.TraitListEvent object at 0x03C85AF0> in 'MyModel'
121 2014-03-21 14:11:20.780000 CALLING: 'handle_list_items_special' in C:\Users\itziakos\Projects\traits\traits\traits_listener.py
122 2014-03-21 14:11:20.780000 -----> 'list_of_numbers_items' changed from [] to [4.7] in 'MyModel'
123 2014-03-21 14:11:20.780000 CALLING: '_count_items' in exampler.py
124 2014-03-21 14:11:20.780000 -------> 'trait_added' changed from <undefined> to 'list_on_numbers' in 'MyModel'
125 2014-03-21 14:11:20.780000 CALLING: '_trait_added_changed' in C:\Users\itziakos\Projects\traits\traits\has_traits.py
126 2014-03-21 14:11:20.780000 <------- EXIT: '_trait_added_changed'
127 2014-03-21 14:11:20.780000 <----- EXIT: '_count_items' [EXCEPTION: 'MyModel' object has no attribute 'list_on_numbers']
128 2014-03-21 14:11:20.780000 <--- EXIT: 'handle_list_items_special'
129 2014-03-21 14:11:20.781000 <- EXIT: '_add_number_to_list'
130
131 2014-03-21 14:11:20.781000 -> 'number' changed from 4.7 to 3.0 in 'MyModel'
132 2014-03-21 14:11:20.781000 CALLING: '_add_number_to_list' in example.py
133 2014-03-21 14:11:20.781000 ---> 'list_of_numbers_items' changed from <undefined> to <traits.trait_handlers.TraitListEvent object at 0x03C85A30> in 'MyModel'
134 2014-03-21 14:11:20.781000 CALLING: 'handle_list_items_special' in C:\Users\itziakos\Projects\traits\traits\traits_listener.py
135 2014-03-21 14:11:20.781000 -----> 'list_of_numbers_items' changed from [] to [3.0] in 'MyModel'
136 2014-03-21 14:11:20.781000 CALLING: '_count_items' in example.py
137 2014-03-21 14:11:20.781000 <----- EXIT: '_count_items' [EXCEPTION: 'MyModel' object has no attribute 'list_on_numbers']
138 2014-03-21 14:11:20.782000 <--- EXIT: 'handle_list_items_special'
139 2014-03-21 14:11:20.782000 <- EXIT: '_add_number_to_list'
140
141
142 .. |record_events| replace:: :func:`~traits.util.event_tracer.record_events`