EventHandler: reinstate ev_error and ev_timeout (as deprecated)

Both EventHandler.ev_error() and EventHandler.ev_timeout() methods were
mistakenly removed from 1.8.0, leading to possible issues with
EventHandler subclasses. This patch reinstates both methods to improve
backward compatibility but add DEPRECATED notes in the documentation.

Closes #377

Change-Id: I1d12e3ab6b190e91dca32745d83145d7fe5bb75b

Author: thiell

lib/ClusterShell/Event.py

@@ -72,6 +72,20 @@ def ev_read(self, worker, node, sname, msg):
         :param msg: message
         """
 
+    def ev_error(self, worker):
+        """
+        Called to indicate that a worker has error to read on stderr from
+        a specific node (or key).
+
+        [DEPRECATED] use ev_read instead and test if sname is 'stderr'
+
+        :param worker: :class:`.Worker` object
+
+        Available worker attributes:
+        * :attr:`.Worker.current_node` - node (or key)
+        * :attr:`.Worker.current_errmsg` - read error message
+        """
+
     def ev_written(self, worker, node, sname, size):
         """
         Called to indicate that some writing has been done by the worker to a
@@ -106,6 +120,15 @@ def ev_hup(self, worker, node, rc):
             command return codes)
         """
 
+    def ev_timeout(self, worker):
+        """
+        Called to indicate that a worker has timed out (worker timeout only).
+
+        [DEPRECATED] use ev_close instead and check if timedout is True
+
+        :param worker: :class:`.Worker` object
+        """
+
     def ev_close(self, worker, timedout):
         """
         Called to indicate that a worker has just finished.

lib/ClusterShell/Worker/Exec.py

@@ -376,6 +376,7 @@ def _check_fini(self):
         self._close_count += 1
         assert self._close_count <= len(self._clients)
         if self._close_count == len(self._clients) and self.eh is not None:
+            # also use hasattr check because ev_timeout was missing in 1.8.0
             if self._has_timeout and hasattr(self.eh, 'ev_timeout'):
                 # Legacy ev_timeout event
                 self.eh.ev_timeout(self)

lib/ClusterShell/Worker/Tree.py

@@ -462,6 +462,7 @@ def _check_fini(self, gateway=None):
         if self._close_count >= self._target_count:
             handler = self.eh
             if handler:
+                # also use hasattr check because ev_timeout was missing in 1.8.0
                 if self._has_timeout and hasattr(handler, 'ev_timeout'):
                     handler.ev_timeout(self)
                 _eh_sigspec_invoke_compat(handler.ev_close, 2, self,

lib/ClusterShell/Worker/Worker.py

@@ -51,6 +51,10 @@ def _eh_sigspec_invoke_compat(method, argc_legacy, *args):
         # Assume new signature (2.x)
         return method(*args)
 
+def _eh_sigspec_ev_read_17(ev_read):
+    """Helper function to check whether ev_read has the old 1.7 signature."""
+    return len(getfullargspec(ev_read)[0]) == 2
+
 
 class WorkerException(Exception):
     """Generic worker exception."""
@@ -252,19 +256,18 @@ def _on_node_msgline(self, node, msg, sname):
         if sname == self.SNAME_STDERR:
             self.current_errmsg = msg
             if self.eh is not None:
-                # check for deprecated ev_error (< 1.8)
-                if hasattr(self.eh, 'ev_error'):
+                # call old ev_error for compat (default is no-op)
+                if hasattr(self.eh, 'ev_error'):  # missing in 1.8.0!
                     self.eh.ev_error(self)
-                else:
-                    # ev_read: ignore old signature (< 1.8)
-                    if len(getfullargspec(self.eh.ev_read)[0]) != 2:
-                        ### FUTURE (2.x) ###
-                        self.eh.ev_read(self, node, sname, msg)
+                # /!\ NOT elif
+                if not _eh_sigspec_ev_read_17(self.eh.ev_read):
+                    ### FUTURE (2.x) ###
+                    self.eh.ev_read(self, node, sname, msg)
         else:
             self.current_msg = msg
             if self.eh is not None:
                 # ev_read: check for old signature first (< 1.8)
-                if len(getfullargspec(self.eh.ev_read)[0]) == 2:
+                if _eh_sigspec_ev_read_17(self.eh.ev_read):
                     self.eh.ev_read(self)
                 else:
                     ### FUTURE (2.x) ###
@@ -574,20 +577,18 @@ def _on_msgline(self, key, msg, sname):
         if sname == 'stderr':
             self.current_errmsg = msg
             if self.eh is not None:
-                # this part is tricky to support backward compatibility...
-                # check for deprecated ev_error (< 1.8)
-                if hasattr(self.eh, 'ev_error'):
+                # call old ev_error for compat (default is no-op)
+                if hasattr(self.eh, 'ev_error'):  # missing in 1.8.0!
                     self.eh.ev_error(self)
-                else:
-                    # ev_read: ignore old signature (< 1.8)
-                    if len(getfullargspec(self.eh.ev_read)[0]) != 2:
-                        ### FUTURE (2.x) ###
-                        self.eh.ev_read(self, key, sname, msg)
+                # /!\ NOT elif
+                if not _eh_sigspec_ev_read_17(self.eh.ev_read):
+                    ### FUTURE (2.x) ###
+                    self.eh.ev_read(self, key, sname, msg)
         else:
             self.current_msg = msg
             if self.eh is not None:
                 # ev_read: check for old signature first (< 1.8)
-                if len(getfullargspec(self.eh.ev_read)[0]) == 2:
+                if _eh_sigspec_ev_read_17(self.eh.ev_read):
                     self.eh.ev_read(self)
                 else:
                     ### FUTURE (2.x) ###
@@ -598,6 +599,7 @@ def _on_timeout(self, key):
         self.task._timeout_add(self, key)
 
         # trigger timeout event (deprecated in 1.8+)
+        # also use hasattr check because ev_timeout was missing in 1.8.0
         if self.eh and hasattr(self.eh, 'ev_timeout'):
             self.eh.ev_timeout(self)