Added docs for waitSignal and example

Author: nicoddemus

docs/index.rst

@@ -116,14 +116,32 @@ created earlier::
     assert window.filesTable.item(0, 0).text() == 'video1.avi'
     assert window.filesTable.item(1, 0).text() == 'video2.avi'    
     
-        
-And that's it for this quick tutorial!    
+
+
+Waiting for threads, processes, etc.
+====================================
+
+If your program has long running cumputations running in other threads or
+processes, you can use :meth:`qtbot.waitSignal <pytestqt.plugin.QtBot.waitSignal>`
+to block a test until a signal is emitted (such as ``QThread.finished``) or a
+timeout is reached. This makes it easy to write tests that wait until a
+computation running in another thread or process is completed before
+ensuring the results are correct::
+
+    def test_long_computation(qtbot):
+        app = Application()
+        app.worker.start()
+
+        with qtbot.waitSignal(app.worker.finished, timeout=10000):
+            assert_application_results(app)
+
 
 QtBot
 =====
 
 .. module:: pytestqt.plugin
 .. autoclass:: QtBot
+.. autoclass:: SignalBlocker
 
 Versioning
 ==========

pytestqt/_tests/test_wait_signal.py

@@ -53,7 +53,7 @@ def test_signal_triggered(qtbot, wait_function, emit_delay, timeout):
     """
     signaller = Signaller()
     QtCore.QTimer.singleShot(emit_delay, signaller.signal.emit)
-    
+
     # block signal until either signal is emitted or timeout is reached
     loop, start_time = wait_function(qtbot, signaller.signal, timeout)
 

pytestqt/plugin.py

@@ -224,7 +224,8 @@ def waitSignal(self, signal=None, timeout=1000):
            with qtbot.waitSignal(signal, timeout=1000):
                long_function_that_calls_signal()
 
-        Can also be used to return blocker object::
+        Also, you can use the :class:`SignalBlocker` directly if the context
+        manager form is not convenient::
 
            blocker = qtbot.waitSignal(signal, timeout=1000)
            blocker.connect(other_signal)
@@ -249,21 +250,43 @@ def waitSignal(self, signal=None, timeout=1000):
         return blocker
 
 
-class SignalBlocker:
+class SignalBlocker(object):
+    """
+    Returned by :meth:`QtBot.waitSignal` method.
+
+    .. automethod:: wait
+    .. automethod:: connect
+
+    :ivar int timeout: maximum time to wait for a signal to be triggered. Can
+        be changed before :meth:`wait` is called.
+    """
 
     def __init__(self, timeout=1000):
         self._loop = QtCore.QEventLoop()
         self._signals = []
         self.timeout = timeout
 
     def wait(self):
+        """
+        Waits until either condition signal is triggered or
+        timeout is reached.
+
+        :raise ValueError: if no signals are connected and timeout is None; in
+            this case it would wait forever.
+        """
         if self.timeout is None and len(self._signals) == 0:
             raise ValueError("No signals or timeout specified.")
         if self.timeout is not None:
             QtCore.QTimer.singleShot(self.timeout, self._loop.quit)
         self._loop.exec_()
 
     def connect(self, signal):
+        """
+        Connects to the given signal, making :meth:`wait()` return once this signal
+        is emitted.
+
+        :param signal: QtCore.Signal
+        """
         signal.connect(self._loop.quit)
         self._signals.append(signal)