Fixed various smaller issues:

* placed new parameters at the end
* renamed "force_order" to "order"
* renamed "callback" to "check_params_cb" and "callbacks" to "check_params_cbs"
* improved various parts of the documentation
* replaced assert with raising a ValueError

Author: MShekow

pytestqt/qtbot.py

@@ -234,7 +234,7 @@ def stopForInteraction(self):
 
     stop = stopForInteraction
 
-    def waitSignal(self, signal=None, timeout=1000, callback=None, raising=None):
+    def waitSignal(self, signal=None, timeout=1000, raising=None, check_params_cb=None):
         """
         .. versionadded:: 1.2
 
@@ -265,13 +265,15 @@ def waitSignal(self, signal=None, timeout=1000, callback=None, raising=None):
             A signal to wait for. Set to ``None`` to just use timeout.
         :param int timeout:
             How many milliseconds to wait before resuming control flow.
-        :param Callable callback:
-            Optional callable(*args) that returns True if the parameters are as expected, or False otherwise.
         :param bool raising:
             If :class:`QtBot.SignalTimeoutError <pytestqt.plugin.SignalTimeoutError>`
             should be raised if a timeout occurred.
             This defaults to ``True`` unless ``qt_wait_signal_raising = false``
             is set in the config.
+        :param Callable check_params_cb:
+            Optional callable(*parameters) that compares the provided signal parameters to some expected parameters.
+            It has to match the signature of ``signal`` (just like a slot function would) and return ``True`` if
+            parameters match, ``False`` otherwise.
         :returns:
             ``SignalBlocker`` object. Call ``SignalBlocker.wait()`` to wait.
 
@@ -287,14 +289,14 @@ def waitSignal(self, signal=None, timeout=1000, callback=None, raising=None):
                 raising = True
             else:
                 raising = _parse_ini_boolean(raising_val)
-        blocker = SignalBlocker(timeout=timeout, raising=raising, callback=callback)
+        blocker = SignalBlocker(timeout=timeout, raising=raising, check_params_cb=check_params_cb)
         if signal is not None:
             blocker.connect(signal)
         return blocker
 
     wait_signal = waitSignal  # pep-8 alias
 
-    def waitSignals(self, signals=None, timeout=1000, force_order = "none", callbacks = None, raising=None):
+    def waitSignals(self, signals=None, timeout=1000, raising=None, check_params_cbs=None, order="none"):
         """
         .. versionadded:: 1.4
 
@@ -317,24 +319,28 @@ def waitSignals(self, signals=None, timeout=1000, force_order = "none", callback
            blocker.wait()
 
         :param list signals:
-            A list of :class:`Signal`s objects to wait for. Set to ``None`` to just use
+            A list of :class:`Signal` objects to wait for. Set to ``None`` to just use
             timeout.
         :param int timeout:
             How many milliseconds to wait before resuming control flow.
-        :param str force_order:
-            "none": no order is enforced
-            "strict": the signals have to be emitted in the provided order (and no intermediate signals may be emitted)
-            "simple": like "strict", but signals may be emitted inbetween the provided ones, e.g. suppose
-            signals=[a, b, c] and the tested object emits the signals a, a, b, a, c, the test will pass with "simple"
-            but not with "strict"
-        :param list callbacks:
-            optional list of Callable functions that evaluate the parameters of the signal. Each element of the list
-            can be a callable or None. Make sure that the number of callbacks matches the number of signals.
         :param bool raising:
             If :class:`QtBot.SignalTimeoutError <pytestqt.plugin.SignalTimeoutError>`
             should be raised if a timeout occurred.
             This defaults to ``True`` unless ``qt_wait_signal_raising = false``
             is set in the config.
+        :param list check_params_cbs:
+            optional list of callables that compare the provided signal parameters to some expected parameters.
+            Each callable has to match the signature of the corresponding signal in ``signals`` (just like a slot
+            function would) and return ``True`` if parameters match, ``False`` otherwise.
+            Instead of a specific callable, ``None`` can be provided, to disable parameter checking for the
+            corresponding signal.
+            If the number of callbacks doesn't match the number of signals ``ValueError`` will be raised.
+        :param str order: determines the order in which to expect signals
+            * ``"none"``: no order is enforced
+            * ``"strict"``: signals have to be emitted strictly in the provided order
+                (e.g. fails when expecting signals [a, b] and [a, a, b] is emitted)
+            * ``"simple"``: like "strict", but signals may be emitted in-between the provided ones, e.g. expected
+                ``signals`` == [a, b, c] and actually emitted signals = [a, a, b, a, c] works (would fail with "strict")
         :returns:
             ``MultiSignalBlocker`` object. Call ``MultiSignalBlocker.wait()``
             to wait.
@@ -345,16 +351,17 @@ def waitSignals(self, signals=None, timeout=1000, force_order = "none", callback
 
         .. note:: This method is also available as ``wait_signals`` (pep-8 alias)
         """
-        assert force_order in ["none", "simple", "strict"], "force_order has to be set to 'none', 'simple' or 'strict'"
+        if order not in ["none", "simple", "strict"]:
+            raise ValueError("order has to be set to 'none', 'simple' or 'strict'")
 
         if raising is None:
             raising = self._request.config.getini('qt_wait_signal_raising')
 
-        if callbacks:
-            if len(callbacks) != len(signals):
+        if check_params_cbs:
+            if len(check_params_cbs) != len(signals):
                 raise ValueError("Number of callbacks ({}) does not "
-                                 "match number of signals ({})!".format(len(callbacks), len(signals)))
-        blocker = MultiSignalBlocker(timeout=timeout, raising=raising, force_order=force_order, callbacks=callbacks)
+                                 "match number of signals ({})!".format(len(check_params_cbs), len(signals)))
+        blocker = MultiSignalBlocker(timeout=timeout, raising=raising, order=order, check_params_cbs=check_params_cbs)
         if signals is not None:
             blocker.add_signals(signals)
         return blocker

pytestqt/wait_signal.py

@@ -99,11 +99,11 @@ class SignalBlocker(_AbstractSignalBlocker):
     .. automethod:: connect
     """
 
-    def __init__(self, timeout=1000, raising=True, callback=None):
+    def __init__(self, timeout=1000, raising=True, check_params_cb=None):
         super(SignalBlocker, self).__init__(timeout, raising=raising)
         self._signals = []
         self.args = None
-        self.callback = callback
+        self.check_params_callback = check_params_cb
 
     def connect(self, signal):
         """
@@ -122,8 +122,8 @@ def _quit_loop_by_signal(self, *args):
         """
         quits the event loop and marks that we finished because of a signal.
         """
-        if self.callback:
-            if not self.callback(*args):
+        if self.check_params_callback:
+            if not self.check_params_callback(*args):
                 return  # parameter check did not pass
         try:
             self.signal_triggered = True
@@ -152,10 +152,10 @@ class MultiSignalBlocker(_AbstractSignalBlocker):
     .. automethod:: wait
     """
 
-    def __init__(self, timeout=1000, force_order="none", callbacks=None, raising=True):
+    def __init__(self, timeout=1000, raising=True, check_params_cbs=None, order="none"):
         super(MultiSignalBlocker, self).__init__(timeout, raising=raising)
-        self.force_order = force_order
-        self.callbacks = callbacks
+        self.order = order
+        self.check_params_callbacks = check_params_cbs
         self._signals_emitted = []  # list of booleans, indicates whether the signal was already emitted
         self._signals_map = {}  # maps from a unique Signal to a list of indices where to expect signal instance emits
         self._signals = []  # list of all Signals (for compatibility with _AbstractSignalBlocker)
@@ -171,7 +171,7 @@ def add_signals(self, signals):
         :param list signals: list of QtCore.Signal`s
         """
         # determine uniqueness of signals, creating a map that maps from a unique signal to a list of indices
-        # (positions) where this signal is expected (in case force_order matters)
+        # (positions) where this signal is expected (in case order matters)
         signals_as_str = [str(signal) for signal in signals]
         signal_str_to_signal = {}  # maps from a signal-string to one of the signal instances (the first one found)
         for index, signal_str in enumerate(signals_as_str):
@@ -200,7 +200,7 @@ def _signal_emitted(self, signal, *args):
         If all expected signals have been emitted, quits the event loop and
         marks that we finished because signals.
         """
-        if self.force_order == "none":
+        if self.order == "none":
             # perform the test for every matching index (stop after the first one that matches)
             successfully_emitted = False
             successful_index = -1
@@ -213,14 +213,14 @@ def _signal_emitted(self, signal, *args):
 
             if successfully_emitted:
                 self._signals_emitted[successful_index] = True
-        elif self.force_order == "simple":
+        elif self.order == "simple":
             potential_indices = self._get_unemitted_signal_indices(signal)
             if potential_indices:
                 if self._signal_expected_index == potential_indices[0]:
                     if self._check_callback(self._signal_expected_index, *args):
                         self._signals_emitted[self._signal_expected_index] = True
                         self._signal_expected_index += 1
-        else:  # self.force_order == "strict"
+        else:  # self.order == "strict"
             if not self._strict_order_violated:
                 # only do the check if the strict order has not been violated yet
                 self._strict_order_violated = True  # assume the order has been violated this time
@@ -244,8 +244,8 @@ def _check_callback(self, index, *args):
         Checks if there's a callback that evaluates the validity of the parameters. Returns False if there is one
         and its evaluation revealed that the parameters were invalid. Returns True otherwise.
         """
-        if self.callbacks:
-            callback_func = self.callbacks[index]
+        if self.check_params_callbacks:
+            callback_func = self.check_params_callbacks[index]
             if callback_func:
                 if not callback_func(*args):
                     return False

tests/test_wait_signal.py

@@ -396,29 +396,29 @@ def test_signal_identity(signaller):
     assert str(x) != str(z)
 
 
-def get_waitsignals_cases_all(force_order):
+def get_waitsignals_cases_all(order):
     """
     Returns the list of tuples (emitted-signal-list, expected-signal-list, expect_signal_triggered) for the
-    given force_order parameter of waitSignals().
+    given order parameter of waitSignals().
     """
-    cases = get_waitsignals_cases(force_order, working=True)
-    cases.extend(get_waitsignals_cases(force_order, working=False))
+    cases = get_waitsignals_cases(order, working=True)
+    cases.extend(get_waitsignals_cases(order, working=False))
     return cases
 
 
-def get_waitsignals_cases(force_order, working):
+def get_waitsignals_cases(order, working):
     """
     Builds combinations for signals to be emitted and expected for working cases (i.e. blocker.signal_triggered == True)
-    and non-working cases, depending on the force_order.
+    and non-working cases, depending on the order.
 
     Note:
-    The force_order ("none", "simple", "strict") becomes stricter from left to right.
+    The order ("none", "simple", "strict") becomes stricter from left to right.
     Working cases of stricter cases also work in less stricter cases.
     Non-working cases in less stricter cases also are non-working in stricter cases.
     """
-    if force_order == "none":
+    if order == "none":
         if working:
-            cases = get_waitsignals_cases(force_order="simple", working=True)
+            cases = get_waitsignals_cases(order="simple", working=True)
             cases.extend([
                 # allow even out-of-order signals
                 (('A1', 'A2'), ('A2', 'A1'), True),
@@ -440,9 +440,9 @@ def get_waitsignals_cases(force_order, working):
                 (('A1', 'B1'), ('B1', 'B1'), False),
                 (('A1', 'B1', 'B1'), ('A1', 'A1', 'B1'), False),
             ]
-    elif force_order == "simple":
+    elif order == "simple":
         if working:
-            cases = get_waitsignals_cases(force_order="strict", working=True)
+            cases = get_waitsignals_cases(order="strict", working=True)
             cases.extend([
                 # allow signals that occur in-between, before or after the expected signals
                 (('B1', 'A1', 'A1', 'B1', 'A1'), ('A1', 'B1'), True),
@@ -452,7 +452,7 @@ def get_waitsignals_cases(force_order, working):
             ])
             return cases
         else:
-            cases = get_waitsignals_cases(force_order="none", working=False)
+            cases = get_waitsignals_cases(order="none", working=False)
             cases.extend([
                 # don't allow out-of-order signals
                 (('A1', 'B1'), ('B1', 'A1'), False),
@@ -461,7 +461,7 @@ def get_waitsignals_cases(force_order, working):
                 (('A1', 'B1', 'B1'), ('B1', 'B1', 'A1'), False),
             ])
             return cases
-    elif force_order == "strict":
+    elif order == "strict":
         if working:
             return [
                 # only allow exactly the same signals to be emitted that were also expected
@@ -479,7 +479,7 @@ def get_waitsignals_cases(force_order, working):
                 (('A1', 'B1', 'A1'), ('Ax', 'A1'), True),
             ]
         else:
-            cases = get_waitsignals_cases(force_order="simple", working=False)
+            cases = get_waitsignals_cases(order="simple", working=False)
             cases.extend([
                 # don't allow in-between signals
                 (('A1', 'A1', 'A2', 'B1'), ('A1', 'A2', 'B1'), False),
@@ -573,47 +573,47 @@ def test_wait_signal(self, qtbot, signaller, emitted_signal_codes, expected_sign
                          expected_signal_triggered):
         """Tests that waitSignal() correctly checks the signal parameters using the provided callback"""
         signals_to_expect, callbacks = TestCallback.get_signals_and_callbacks(signaller, expected_signal_codes)
-        with qtbot.waitSignal(signal=signals_to_expect[0], callback=callbacks[0], timeout=200,
+        with qtbot.waitSignal(signal=signals_to_expect[0], check_params_cb=callbacks[0], timeout=200,
                               raising=False) as blocker:
             TestCallback.emit_parametrized_signals(signaller, emitted_signal_codes)
 
         assert blocker.signal_triggered == expected_signal_triggered
 
     @pytest.mark.parametrize(
         ('emitted_signal_codes', 'expected_signal_codes', 'expected_signal_triggered'),
-        get_waitsignals_cases_all(force_order="none")
+        get_waitsignals_cases_all(order="none")
     )
     def test_wait_signals_none_order(self, qtbot, signaller, emitted_signal_codes, expected_signal_codes,
                                      expected_signal_triggered):
-        """Tests waitSignals() with force_order="none"."""
+        """Tests waitSignals() with order="none"."""
         self._test_wait_signals(qtbot, signaller, emitted_signal_codes, expected_signal_codes,
-                                expected_signal_triggered, force_order="none")
+                                expected_signal_triggered, order="none")
 
     @pytest.mark.parametrize(
         ('emitted_signal_codes', 'expected_signal_codes', 'expected_signal_triggered'),
-        get_waitsignals_cases_all(force_order="simple")
+        get_waitsignals_cases_all(order="simple")
     )
     def test_wait_signals_simple_order(self, qtbot, signaller, emitted_signal_codes, expected_signal_codes,
                                        expected_signal_triggered):
-        """Tests waitSignals() with force_order="simple"."""
+        """Tests waitSignals() with order="simple"."""
         self._test_wait_signals(qtbot, signaller, emitted_signal_codes, expected_signal_codes,
-                                expected_signal_triggered, force_order="simple")
+                                expected_signal_triggered, order="simple")
 
     @pytest.mark.parametrize(
         ('emitted_signal_codes', 'expected_signal_codes', 'expected_signal_triggered'),
-        get_waitsignals_cases_all(force_order="strict")
+        get_waitsignals_cases_all(order="strict")
     )
     def test_wait_signals_strict_order(self, qtbot, signaller, emitted_signal_codes, expected_signal_codes,
                                        expected_signal_triggered):
-        """Tests waitSignals() with force_order="strict"."""
+        """Tests waitSignals() with order="strict"."""
         self._test_wait_signals(qtbot, signaller, emitted_signal_codes, expected_signal_codes,
-                                expected_signal_triggered, force_order="strict")
+                                expected_signal_triggered, order="strict")
 
     @staticmethod
     def _test_wait_signals(qtbot, signaller, emitted_signal_codes, expected_signal_codes,
-                           expected_signal_triggered, force_order):
+                           expected_signal_triggered, order):
         signals_to_expect, callbacks = TestCallback.get_signals_and_callbacks(signaller, expected_signal_codes)
-        with qtbot.waitSignals(signals=signals_to_expect, force_order=force_order, callbacks=callbacks,
+        with qtbot.waitSignals(signals=signals_to_expect, order=order, check_params_cbs=callbacks,
                                timeout=200, raising=False) as blocker:
             TestCallback.emit_parametrized_signals(signaller, emitted_signal_codes)
 
@@ -628,7 +628,7 @@ def test_signals_and_callbacks_length_mismatch(self, qtbot, signaller):
         signals_to_expect, callbacks = TestCallback.get_signals_and_callbacks(signaller, expected_signal_codes)
         callbacks.append(None)
         with pytest.raises(ValueError):
-            with qtbot.waitSignals(signals=signals_to_expect, force_order="none", callbacks=callbacks,
+            with qtbot.waitSignals(signals=signals_to_expect, order="none", check_params_cbs=callbacks,
                                    raising=False):
                 pass