Merge remote-tracking branch 'origin/master' into waitsignal-multiple

Conflicts:
	pytestqt/_tests/test_wait_signal.py
	pytestqt/plugin.py

Author: nicoddemus

.project

@@ -92,16 +92,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if on_rtd:
-    html_theme = 'default'
-else:
-    #html_theme = 'agogo'
-    html_theme = 'sphinxdoc'
-    #html_theme = 'scrolls'
-    #html_theme = 'nature'
-    #html_theme = 'haiku'
-    #html_theme = 'pyramid'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

.pydevproject

@@ -163,6 +163,11 @@ ensuring the results are correct::
         assert_application_results(app)
 
 
+.. versionadded:: 1.4
+
+Additionally, you can pass ``raising=True`` to raise a
+:class:`SignalTimeoutError` if the timeout is reached.
+
 Exceptions in virtual methods
 =============================
 
@@ -238,6 +243,8 @@ SignalBlocker
 
 .. autoclass:: SignalBlocker
 
+.. autoclass:: SignalTimeoutError
+
 Versioning
 ==========
 

docs/conf.py

@@ -19,40 +19,55 @@ def test_signal_blocker_exception(qtbot):
         qtbot.waitSignal(None, None).wait()
 
 
-def explicit_wait(qtbot, signal, timeout, multiple):
+def explicit_wait(qtbot, signal, timeout, multiple, raising, raises):
     """
     Explicit wait for the signal using blocker API.
     """
     func = qtbot.waitSignals if multiple else qtbot.waitSignal
-    blocker = func(signal, timeout)
+    blocker = func(signal, timeout, raising=raising)    
     assert not blocker.signal_triggered
-    blocker.wait()
+    if raises:
+        with pytest.raises(qtbot.SignalTimeoutError):
+            blocker.wait()
+    else:
+        blocker.wait()
     return blocker
 
 
-def context_manager_wait(qtbot, signal, timeout, multiple):
+def context_manager_wait(qtbot, signal, timeout, multiple, raising, raises):
     """
     Waiting for signal using context manager API.
     """
-    func = qtbot.waitSignals if multiple else qtbot.waitSignal
-    with func(signal, timeout) as blocker:
-        pass
+    func = qtbot.waitSignals if multiple else qtbot.waitSignal    
+    if raises:
+        with pytest.raises(qtbot.SignalTimeoutError):
+            with func(signal, timeout, raising=raising) as blocker:
+                pass
+    else:
+        with func(signal, timeout, raising=raising) as blocker:
+            pass
     return blocker
 
 
 @pytest.mark.parametrize(
-    ('wait_function', 'emit_delay', 'timeout', 'expected_signal_triggered'),
+    ('wait_function', 'emit_delay', 'timeout', 'expected_signal_triggered',
+     'raising'),
     [
-        (explicit_wait, 500, 2000, True),
-        (explicit_wait, 500, None, True),
-        (context_manager_wait, 500, 2000, True),
-        (context_manager_wait, 500, None, True),
-        (explicit_wait, 2000, 500, False),
-        (context_manager_wait, 2000, 500, False),
-    ] * 2  # Running all tests twice to catch a QTimer segfault, see #42/#43.
+        (explicit_wait, 500, 2000, True, False),
+        (explicit_wait, 500, None, True, False),
+        (context_manager_wait, 500, 2000, True, False),
+        (context_manager_wait, 500, None, True, False),
+        (explicit_wait, 2000, 500, False, False),
+        (context_manager_wait, 2000, 500, False, False),
+
+        (explicit_wait, 2000, 500, False, True),
+        (context_manager_wait, 2000, 500, False, True),
+        (explicit_wait, 2000, 500, False, True),
+        (context_manager_wait, 2000, 500, False, True),
+    ]
 )
 def test_signal_triggered(qtbot, wait_function, emit_delay, timeout,
-                          expected_signal_triggered):
+                          expected_signal_triggered, raising):
     """
     Testing for a signal in different conditions, ensuring we are obtaining
     the expected results.
@@ -64,9 +79,11 @@ def test_signal_triggered(qtbot, wait_function, emit_delay, timeout,
     timer.timeout.connect(signaller.signal.emit)
     timer.start(emit_delay)
 
-    # block signal until either signal is emitted or timeout is reached
     start_time = time.time()
-    blocker = wait_function(qtbot, signaller.signal, timeout, multiple=False)
+    raises = raising and not expected_signal_triggered
+
+    blocker = wait_function(qtbot, signaller.signal, timeout, raising=raising,
+                            raises=raises, multiple=False)    
 
     # Check that event loop exited.
     assert not blocker._loop.isRunning()
@@ -84,23 +101,23 @@ def test_signal_triggered(qtbot, wait_function, emit_delay, timeout,
 
 @pytest.mark.parametrize(
     ('wait_function', 'emit_delay_1', 'emit_delay_2', 'timeout',
-     'expected_signal_triggered'),
+     'expected_signal_triggered', 'raising'),
     [
-        (explicit_wait, 500, 600, 2000, True),
-        (explicit_wait, 500, 600, None, True),
-        (context_manager_wait, 500, 600, 2000, True),
-        (context_manager_wait, 500, 600, None, True),
-        (explicit_wait, 2000, 2000, 500, False),
-        (explicit_wait, 500, 2000, 1000, False),
-        (explicit_wait, 2000, 500, 1000, False),
-        (context_manager_wait, 2000, 2000, 500, False),
-        (context_manager_wait, 500, 2000, 1000, False),
-        (context_manager_wait, 2000, 500, 1000, False),
+        (explicit_wait, 500, 600, 2000, True, False),
+        (explicit_wait, 500, 600, None, True, False),
+        (context_manager_wait, 500, 600, 2000, True, False),
+        (context_manager_wait, 500, 600, None, True, False),
+        (explicit_wait, 2000, 2000, 500, False, False),
+        (explicit_wait, 500, 2000, 1000, False, False),
+        (explicit_wait, 2000, 500, 1000, False, False),
+        (context_manager_wait, 2000, 2000, 500, False, False),
+        (context_manager_wait, 500, 2000, 1000, False, False),
+        (context_manager_wait, 2000, 500, 1000, False, False),
     ]
 )
 def test_signal_triggered_multiple(qtbot, wait_function, emit_delay_1,
                                    emit_delay_2, timeout,
-                                   expected_signal_triggered):
+                                   expected_signal_triggered, raising):
     """
     Testing for a signal in different conditions, ensuring we are obtaining
     the expected results.
@@ -117,10 +134,10 @@ def test_signal_triggered_multiple(qtbot, wait_function, emit_delay_1,
     timer2.timeout.connect(signaller.signal_2.emit)
     timer2.start(emit_delay_2)
 
-    # block signal until either signal is emitted or timeout is reached
+    raises = raising and not expected_signal_triggered
     start_time = time.time()
     blocker = wait_function(qtbot, [signaller.signal, signaller.signal_2],
-                            timeout, multiple=True)
+                            timeout, multiple=True, raising=raising, raises=raises)
 
     # Check that event loop exited.
     assert not blocker._loop.isRunning()

docs/index.rst

@@ -234,7 +234,7 @@ def stopForInteraction(self):
 
     stop = stopForInteraction
 
-    def waitSignal(self, signal=None, timeout=1000):
+    def waitSignal(self, signal=None, timeout=1000, raising=False):
         """
         .. versionadded:: 1.2
 
@@ -256,25 +256,31 @@ def waitSignal(self, signal=None, timeout=1000):
            long_function_that_calls_signal()
            blocker.wait()
 
+        .. versionadded:: 1.4
+           The *raising* parameter.
+
         :param Signal signal:
             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 bool raising:
+            If :class:`QtBot.SignalTimeoutError <pytestqt.plugin.SignalTimeoutError>`
+            should be raised if a timeout occurred.
         :returns:
             ``SignalBlocker`` object. Call ``SignalBlocker.wait()`` to wait.
 
         .. note::
            Cannot have both ``signals`` and ``timeout`` equal ``None``, or
            else you will block indefinitely. We throw an error if this occurs.
         """
-        blocker = SignalBlocker(timeout=timeout)
+        blocker = SignalBlocker(timeout=timeout, raising=raising)
         if signal is not None:
             blocker.connect(signal)
         return blocker
 
     wait_signal = waitSignal  # pep-8 alias
 
-    def waitSignals(self, signals=None, timeout=1000):
+    def waitSignals(self, signals=None, timeout=1000, raising=False):
         """
         .. versionadded:: 1.4
 
@@ -302,6 +308,9 @@ def waitSignals(self, signals=None, timeout=1000):
             timeout.
         :param int timeout:
             How many milliseconds to wait before resuming control flow.
+        :param bool raising:
+            If :class:`QtBot.SignalTimeoutError <pytestqt.plugin.SignalTimeoutError>`
+            should be raised if a timeout occurred.
         :returns:
             ``MultiSignalBlocker`` object. Call ``MultiSignalBlocker.wait()``
             to wait.
@@ -310,7 +319,7 @@ def waitSignals(self, signals=None, timeout=1000):
            Cannot have both ``signals`` and ``timeout`` equal ``None``, or
            else you will block indefinitely. We throw an error if this occurs.
         """
-        blocker = MultiSignalBlocker(timeout=timeout)
+        blocker = MultiSignalBlocker(timeout=timeout, raising=raising)
         if signals is not None:
             for signal in signals:
                 blocker.add_signal(signal)
@@ -335,15 +344,19 @@ class AbstractSignalBlocker(object):
         be changed before :meth:`wait` is called.
 
     :ivar bool signal_triggered: set to ``True`` if a signal (or all signals in
-        case of :class:MultipleSignalBlocker:) was triggered, or ``False`` if
-        timeout was reached instead. Until :meth:`wait` is called, this is set
-        to ``None``.
+        case of :class:MultipleSignalBlocker:) was triggered, or
+        ``False`` if timeout was reached instead. Until :meth:`wait` is called,
+        this is set to ``None``.
+
+    :ivar bool raising:
+        If :class:`SignalTimeoutError` should be raised if a timeout occurred.
     """
 
-    def __init__(self, timeout=1000):
+    def __init__(self, timeout=1000, raising=False):
         self._loop = QtCore.QEventLoop()
         self.timeout = timeout
         self.signal_triggered = False
+        self.raising = raising
 
     def wait(self):
         """
@@ -359,6 +372,9 @@ def wait(self):
         if self.timeout is not None:
             QtCore.QTimer.singleShot(self.timeout, self._loop.quit)
         self._loop.exec_()
+        if not self.signal_triggered and self.raising:
+            raise SignalTimeoutError("Didn't get signal after %sms." %
+                                      self.timeout)
 
     def __enter__(self):
         return self
@@ -377,14 +393,17 @@ class SignalBlocker(AbstractSignalBlocker):
 
     """
 
-    def __init__(self, timeout=1000):
-        super(SignalBlocker, self).__init__(timeout)
+    def __init__(self, timeout=1000, raising=False):
+        super(SignalBlocker, self).__init__(timeout, raising=raising)
         self._signals = []
 
     def connect(self, signal):
         """
-        Connects to the given signal, making :meth:`wait()` return once this signal
-        is emitted.
+        Connects to the given signal, making :meth:`wait()` return once
+        this signal is emitted.
+
+        More than one signal can be connected, in which case **any** one of
+        them will make ``wait()`` return.
 
         :param signal: QtCore.Signal
         """
@@ -408,8 +427,8 @@ class MultiSignalBlocker(AbstractSignalBlocker):
     .. automethod:: add_signal
     """
 
-    def __init__(self, timeout=1000):
-        super(MultiSignalBlocker, self).__init__(timeout)
+    def __init__(self, timeout=1000, raising=False):
+        super(MultiSignalBlocker, self).__init__(timeout, raising=raising)
         self._signals = {}
 
     def add_signal(self, signal):
@@ -435,6 +454,19 @@ def _signal_emitted(self, signal):
             self._loop.quit()
 
 
+class SignalTimeoutError(Exception):
+    """
+    .. versionadded:: 1.4
+
+    The exception thrown by :meth:`QtBot.waitSignal` if the *raising*
+    parameter has been given and there was a timeout.
+    """
+    pass
+
+# provide easy access to SignalTimeoutError to qtbot fixtures
+QtBot.SignalTimeoutError = SignalTimeoutError
+
+
 @contextmanager
 def capture_exceptions():
     """

pytestqt/_tests/test_wait_signal.py

@@ -98,8 +98,10 @@ def __call__(self, *args, **kwargs):
         def __getattr__(cls, name):
             if name in ('__file__', '__path__'):
                 return '/dev/null'
-            elif name == '__name__':
+            elif name in ('__name__', '__qualname__'):
                 return name
+            elif name == '__annotations__':
+                return {}
             else:
                 return Mock()