Warn on a bad signature for an 'observe'-decorated function

traits/has_traits.py

@@ -839,8 +839,31 @@ def observe_decorator(handler):
         Parameters
         ----------
         handler : callable
-            Method of a subclass of HasTraits
+            Method of a subclass of HasTraits, with signature of the form
+            ``my_method(self, event)``.
         """
+        # Warn on a dubious handler signature. The handler should accept a call
+        # that passes a single positional argument (conventionally named
+        # "event") in addition to the usual "self".
+        try:
+            handler_signature = inspect.signature(handler)
+        except (ValueError, TypeError):
+            pass
+        else:
+            try:
+                handler_signature.bind("self", "event")
+            except TypeError:
+                warnings.warn(
+                    (
+                        "Dubious signature for observe-decorated method. "
+                        "The decorated method should be callable with a "
+                        "single positional argument in addition to 'self'. "
+                        "Did you forget to add an 'event' parameter?"
+                    ),
+                    UserWarning,
+                    stacklevel=2,
+                )
+
         try:
             observe_inputs = handler._observe_inputs
         except AttributeError:

traits/tests/test_observe.py

@@ -37,6 +37,63 @@
 )
 
 
+class TestObserveDecorator(unittest.TestCase):
+    """ General tests for the observe decorator. """
+
+    def test_warning_on_handler_with_bad_signature(self):
+        message_regex = "should be callable with a single positional argument"
+
+        with self.assertWarnsRegex(UserWarning, message_regex):
+            class A(HasTraits):
+                foo = Int()
+
+                @observe("foo")
+                def _do_something_when_foo_changes(self):
+                    pass
+
+        with self.assertWarnsRegex(UserWarning, message_regex):
+            class B(HasTraits):
+                foo = Int()
+
+                @observe("foo")
+                def _do_something_when_foo_changes(self, **kwargs):
+                    pass
+
+    def test_decorated_method_signatures(self):
+        # Test different handler signatures for compatibility with
+        # observe decorator.
+
+        class A(HasTraits):
+            foo = Int()
+
+            call_count = Int(0)
+
+            @observe("foo")
+            def _the_usual_signature(self, event):
+                self.call_count += 1
+
+            @observe("foo")
+            def _method_with_extra_optional_args(self, event, frombicate=True):
+                self.call_count += 1
+
+            @observe("foo")
+            def _method_with_star_args(self, *args):
+                self.call_count += 1
+
+            @observe("foo")
+            def _method_with_alternative_name(self, foo_change_event):
+                self.call_count += 1
+
+            @observe("foo")
+            def _optional_second_argument(self, event=None):
+                self.call_count += 1
+
+        a = A()
+        self.assertEqual(a.call_count, 0)
+        a.foo = 23
+        self.assertEqual(a.call_count, 5)
+
+
 class Student(HasTraits):
     """ Model for testing list + post_init (enthought/traits#275) """