Replace "on_trait_change" decorator with "observe" decorator (#371)

* DEV : Replace on_trait_change decorator with observe

This commit replaces the on_trait_change decorator with the observe
decorator. The changes have been made in the documentation, the
testsuite and the package itself.

Note that the new decorator requires a change to the api of the
decorated method - which now needs to accept a single "event" argument
instead of the earlier signature.

* CLN : Make black recommended changes

	modified:   traits_futures/tests/i_message_router_tests.py
	modified:   traits_futures/wrappers.py

docs/source/guide/examples/pi_iterations.py

@@ -27,7 +27,7 @@
     Instance,
     Int,
     List,
-    on_trait_change,
+    observe,
     Property,
     Tuple,
 )
@@ -130,12 +130,13 @@ def _approximate_fired(self):
     def _cancel_fired(self):
         self.future.cancel()
 
-    @on_trait_change("future")
-    def _reset_results(self):
+    @observe("future")
+    def _reset_results(self, event):
         self.results = []
 
-    @on_trait_change("future:result_event")
-    def _record_result(self, result):
+    @observe("future:result_event")
+    def _record_result(self, event):
+        result = event.new
         self.results.append(result)
         self._update_plot_data()
 

docs/source/guide/examples/prime_counting.py

@@ -21,7 +21,7 @@
     HasStrictTraits,
     Instance,
     Int,
-    on_trait_change,
+    observe,
     Property,
     Str,
 )
@@ -97,37 +97,41 @@ def _create_progress_bar(self, dialog, layout):
         self._progress_bar = QtGui.QProgressBar(dialog)
         return self._progress_bar
 
-    @on_trait_change("message")
-    def _update_message(self, message):
+    @observe("message")
+    def _update_message(self, event):
+        message = event.new
         if self._message_control is not None:
             self._message_control.setText(message)
 
-    @on_trait_change("maximum")
-    def _update_progress_bar_maximum(self, maximum):
+    @observe("maximum")
+    def _update_progress_bar_maximum(self, event):
+        maximum = event.new
         if self._progress_bar is not None:
             self._progress_bar.setMaximum(maximum)
 
-    @on_trait_change("value")
-    def _update_progress_bar_value(self, value):
+    @observe("value")
+    def _update_progress_bar_value(self, event):
+        value = event.new
         if self._progress_bar is not None:
             self._progress_bar.setValue(value)
 
-    @on_trait_change("future:progress")
-    def _report_progress(self, progress_info):
+    @observe("future:progress")
+    def _report_progress(self, event):
+        progress_info = event.new
         current_step, max_steps, count_so_far = progress_info
         self.maximum = max_steps
         self.value = current_step
         self.message = "{} of {} chunks processed. {} primes found".format(
             current_step, max_steps, count_so_far
         )
 
-    @on_trait_change("closing")
-    def _cancel_future_if_necessary(self):
+    @observe("closing")
+    def _cancel_future_if_necessary(self, event):
         if self.future is not None and self.future.cancellable:
             self.future.cancel()
 
-    @on_trait_change("future:done")
-    def _respond_to_completion(self):
+    @observe("future:done")
+    def _respond_to_completion(self, event):
         self.future = None
         self.close()
 
@@ -224,8 +228,9 @@ def _count_fired(self):
     def _get_count_enabled(self):
         return self.future is None or self.future.done
 
-    @on_trait_change("future:done")
-    def _report_result(self, future, name, done):
+    @observe("future:done")
+    def _report_result(self, event):
+        future = event.object
         if future.state == COMPLETED:
             self.result_message = "There are {} primes smaller than {}".format(
                 future.result,

docs/source/guide/examples/quick_start.py

@@ -16,7 +16,7 @@
     HasStrictTraits,
     Instance,
     Int,
-    on_trait_change,
+    observe,
     Property,
     Str,
 )
@@ -52,8 +52,8 @@ class QuickStartExample(HasStrictTraits):
     #: Boolean used to decide whether to enable the "calculate" button.
     no_running_future = Property(Bool(), observe="future:done")
 
-    @on_trait_change("calculate")
-    def _submit_background_call(self):
+    @observe("calculate")
+    def _submit_background_call(self, event):
         # Returns immediately.
         input = self.input
         self.input_for_calculation = self.input
@@ -62,8 +62,9 @@ def _submit_background_call(self):
         # Keep a record so that we can present messages accurately.
         self.input_for_calculation = input
 
-    @on_trait_change("future:done")
-    def _report_result(self, future, name, done):
+    @observe("future:done")
+    def _report_result(self, event):
+        future = event.object
         self.message = "The square of {} is {}.".format(
             self.input_for_calculation, future.result
         )

docs/source/guide/intro.rst

@@ -176,8 +176,9 @@ expect to return a result. Once the state of the corresponding future reaches
 Assuming that your calculation future is stored in a trait called ``future``,
 you might use this as follows::
 
-    @on_trait_change('future:done')
-    def _update_result(self, future, name, done):
+    @observe('future:done')
+    def _update_result(self, event):
+        future = event.object
         self.my_results.append(future.result)
 
 Any attempt to access ``future.result`` before the future completes
@@ -189,8 +190,9 @@ A |ProgressFuture| object also receives progress information send by the
 background task via its ``progress`` event trait. You might use that
 trait like this::
 
-    @on_trait_change('future:progress')
-    def _report_progress(self, progress_info):
+    @observe('future:progress')
+    def _report_progress(self, event):
+        progress_info = event.new
         current_step, max_steps, matches = progress_info
         self.message = "{} of {} chunks processed. {} matches so far".format(
             current_step, max_steps, matches)
@@ -200,8 +202,9 @@ on each iteration, but doesn't necessarily give a final result. Its
 ``result_event`` trait is an ``Event`` that you can hook listeners up to in
 order to receive the iteration results. For example::
 
-    @on_trait_change('future:result_event')
-    def _record_result(self, result):
+    @observe('future:result_event')
+    def _record_result(self, event):
+        result = event.new
         self.results.append(result)
         self.update_plot_data()
 

traits_futures/tests/background_call_tests.py

@@ -8,7 +8,7 @@
 #
 # Thanks for using Enthought open source!
 
-from traits.api import HasStrictTraits, Instance, List, on_trait_change
+from traits.api import HasStrictTraits, Instance, List, observe
 
 from traits_futures.api import (
     CallFuture,
@@ -57,8 +57,9 @@ class CallFutureListener(HasStrictTraits):
     #: List of states of that future.
     states = List(FutureState)
 
-    @on_trait_change("future:state")
-    def record_state_change(self, obj, name, old_state, new_state):
+    @observe("future:state")
+    def record_state_change(self, event):
+        old_state, new_state = event.old, event.new
         if not self.states:
             # On the first state change, record the initial state as well as
             # the new one.

traits_futures/tests/background_iteration_tests.py

@@ -13,7 +13,7 @@
 """
 import weakref
 
-from traits.api import Any, HasStrictTraits, Instance, List, on_trait_change
+from traits.api import Any, HasStrictTraits, Instance, List, observe
 
 from traits_futures.api import (
     CANCELLED,
@@ -127,16 +127,18 @@ class IterationFutureListener(HasStrictTraits):
     #: List of results from the future.
     results = List(Any())
 
-    @on_trait_change("future:state")
-    def record_state_change(self, obj, name, old_state, new_state):
+    @observe("future:state")
+    def record_state_change(self, event):
+        old_state, new_state = event.old, event.new
         if not self.states:
             # On the first state change, record the initial state as well as
             # the new one.
             self.states.append(old_state)
         self.states.append(new_state)
 
-    @on_trait_change("future:result_event")
-    def record_iteration_result(self, result):
+    @observe("future:result_event")
+    def record_iteration_result(self, event):
+        result = event.new
         self.results.append(result)
 
 

traits_futures/tests/background_progress_tests.py

@@ -8,7 +8,7 @@
 #
 # Thanks for using Enthought open source!
 
-from traits.api import Any, HasStrictTraits, Instance, List, on_trait_change
+from traits.api import Any, HasStrictTraits, Instance, List, observe
 
 from traits_futures.api import (
     CANCELLED,
@@ -119,16 +119,18 @@ class ProgressFutureListener(HasStrictTraits):
     #: List of progress messages received.
     progress = List(Any())
 
-    @on_trait_change("future:state")
-    def record_state_change(self, obj, name, old_state, new_state):
+    @observe("future:state")
+    def record_state_change(self, event):
+        old_state, new_state = event.old, event.new
         if not self.states:
             # On the first state change, record the initial state as well as
             # the new one.
             self.states.append(old_state)
         self.states.append(new_state)
 
-    @on_trait_change("future:progress")
-    def record_progress(self, progress_info):
+    @observe("future:progress")
+    def record_progress(self, event):
+        progress_info = event.new
         self.progress.append(progress_info)
 
 

traits_futures/tests/common_future_tests.py

@@ -11,7 +11,7 @@
 """
 Test methods run for all future types.
 """
-from traits.api import Any, Bool, HasStrictTraits, List, on_trait_change, Tuple
+from traits.api import Any, Bool, HasStrictTraits, List, observe, Tuple
 
 from traits_futures.api import IFuture
 from traits_futures.base_future import _StateTransitionError
@@ -37,12 +37,14 @@ class FutureListener(HasStrictTraits):
     #: Changes to the 'done' trait.
     done_changes = List(Tuple(Bool(), Bool()))
 
-    @on_trait_change("future:cancellable")
-    def _record_cancellable_change(self, object, name, old, new):
+    @observe("future:cancellable")
+    def _record_cancellable_change(self, event):
+        old, new = event.old, event.new
         self.cancellable_changes.append((old, new))
 
-    @on_trait_change("future:done")
-    def _record_done_change(self, object, name, old, new):
+    @observe("future:done")
+    def _record_done_change(self, event):
+        old, new = event.old, event.new
         self.done_changes.append((old, new))
 
 

traits_futures/tests/i_event_loop_helper_tests.py

@@ -14,7 +14,7 @@
 
 import contextlib
 
-from traits.api import Bool, Event, HasStrictTraits, Int, on_trait_change
+from traits.api import Bool, Event, HasStrictTraits, Int, observe
 
 from traits_futures.i_event_loop_helper import IEventLoopHelper
 
@@ -29,8 +29,8 @@ class HasFlag(HasStrictTraits):
     #: Counter for number of pings received.
     ping_count = Int()
 
-    @on_trait_change("ping")
-    def increment_ping_count(self):
+    @observe("ping")
+    def increment_ping_count(self, event):
         self.ping_count += 1
 
 

traits_futures/tests/i_message_router_tests.py

@@ -16,14 +16,7 @@
 import logging
 import threading
 
-from traits.api import (
-    Any,
-    HasStrictTraits,
-    Instance,
-    List,
-    on_trait_change,
-    Str,
-)
+from traits.api import Any, HasStrictTraits, Instance, List, observe, Str
 
 from traits_futures.i_message_router import IMessageReceiver
 from traits_futures.i_parallel_context import IParallelContext
@@ -63,8 +56,9 @@ class ReceiverListener(HasStrictTraits):
     #: Received messages
     messages = List(Any())
 
-    @on_trait_change("receiver:message")
-    def _record_message(self, message):
+    @observe("receiver:message")
+    def _record_message(self, event):
+        message = event.new
         self.messages.append(message)
 
 

traits_futures/tests/traits_executor_tests.py

@@ -22,7 +22,7 @@
     HasStrictTraits,
     Instance,
     List,
-    on_trait_change,
+    observe,
     Property,
     Tuple,
 )
@@ -101,20 +101,23 @@ class ExecutorListener(HasStrictTraits):
     #: Changes to the 'stopped' trait value.
     stopped_changes = List(Tuple(Bool(), Bool()))
 
-    @on_trait_change("executor:state")
-    def _record_state_change(self, obj, name, old_state, new_state):
+    @observe("executor:state")
+    def _record_state_change(self, event):
+        old_state, new_state = event.old, event.new
         if not self.states:
             # On the first state change, record the initial state as well as
             # the new one.
             self.states.append(old_state)
         self.states.append(new_state)
 
-    @on_trait_change("executor:running")
-    def _record_running_change(self, object, name, old, new):
+    @observe("executor:running")
+    def _record_running_change(self, event):
+        old, new = event.old, event.new
         self.running_changes.append((old, new))
 
-    @on_trait_change("executor:stopped")
-    def _record_stopped_change(self, object, name, old, new):
+    @observe("executor:stopped")
+    def _record_stopped_change(self, event):
+        old, new = event.old, event.new
         self.stopped_changes.append((old, new))
 
 

traits_futures/traits_executor.py

@@ -23,7 +23,7 @@
     Enum,
     HasStrictTraits,
     Instance,
-    on_trait_change,
+    observe,
     Property,
     Set,
 )
@@ -500,8 +500,9 @@ def __context_default(self):
         self._own_context = True
         return context
 
-    @on_trait_change("_wrappers:done")
-    def _untrack_future(self, wrapper, name, is_done):
+    @observe("_wrappers:items:done")
+    def _untrack_future(self, event):
+        wrapper = event.object
         self._message_router.close_pipe(wrapper.receiver)
         self._wrappers.remove(wrapper)
         logger.debug(