rename to asyncWrap, parametrize the test and format the code

Author: hosaka

examples/modal_example.py

@@ -2,29 +2,28 @@
 import sys
 
 # from PyQt6.QtWidgets import
-from PySide6.QtWidgets import QApplication, QProgressBar, QMessageBox
-from qasync import QEventLoop, call_sync
+from PySide6.QtWidgets import QApplication, QMessageBox, QProgressBar
+
+from qasync import QEventLoop, asyncWrap
 
 
 async def master():
     progress = QProgressBar()
     progress.setRange(0, 99)
     progress.show()
     await first_50(progress)
-    
+
 
 async def first_50(progress):
     for i in range(50):
         progress.setValue(i)
         await asyncio.sleep(0.1)
-    
+
     # Schedule the last 50% to run asynchronously
-    asyncio.create_task(
-        last_50(progress)
-    )
-    
+    asyncio.create_task(last_50(progress))
+
     # create a notification box, use helper to make entering event loop safe.
-    result = await call_sync(
+    result = await asyncWrap(
         lambda: QMessageBox.information(
             None, "Task Completed", "The first 50% of the task is completed."
         )

qasync/__init__.py

@@ -8,7 +8,7 @@
 BSD License
 """
 
-__all__ = ["QEventLoop", "QThreadExecutor", "asyncSlot", "asyncClose", "call_sync"]
+__all__ = ["QEventLoop", "QThreadExecutor", "asyncSlot", "asyncClose", "asyncWrap"]
 
 import asyncio
 import contextlib
@@ -833,8 +833,29 @@ def wrapper(*args, **kwargs):
 
     return outer_decorator
 
-async def call_sync(fn, *args, **kwargs):
-    """run a blocking call from the Qt event loop."""
+
+async def asyncWrap(fn, *args, **kwargs):
+    """
+    Wrap a blocking function as an asynchronous and run it on the native Qt event loop.
+    The function will be scheduled using a one shot QTimer which prevents blocking the
+    QEventLoop. An example usage of this is raising a modal dialogue inside an asyncSlot.
+    ```python
+    async def before_shutdown(self):
+        await asyncio.sleep(2)
+
+    @asyncSlot()
+    async def shutdown_clicked(self):
+        # do some work async
+        asyncio.create_task(self.before_shutdown())
+
+        # run on the native Qt loop, not blocking the QEventLoop
+        result = await asyncWrap(
+            lambda: QMessageBox.information(None, "Done", "It is now safe to shutdown.")
+        )
+        if result == QMessageBox.StandardButton.Ok:
+            app.exit(0)
+    ```
+    """
     future = asyncio.Future()
 
     @functools.wraps(fn)
@@ -850,6 +871,7 @@ def helper():
     QtCore.QTimer.singleShot(0, helper)
     return await future
 
+
 class QEventLoopPolicyMixin:
     def new_event_loop(self):
         return QEventLoop(QApplication.instance() or QApplication(sys.argv))

tests/test_qeventloop.py

@@ -791,47 +791,21 @@ async def mycoro():
     loop.run_until_complete(mycoro())
     assert not loop.is_running()
 
-def test_task_recursion_fails(loop, application):
-    """Re-entering the event loop from a Task will fail if there is another
-    runnable task."""
-    async_called = False
-    main_called = False
-    
-    async def async_job():
-        nonlocal async_called
-        async_called = True
-
-    def sync_callback():
-        asyncio.create_task(async_job())
-        assert not async_called
-        application.processEvents()
-        assert not async_called
-        return 1
-
-    async def main():
-        nonlocal main_called
-        res = sync_callback()
-        assert res == 1
-        main_called = True
-
-    exceptions= []
-    loop.set_exception_handler(lambda loop, context: exceptions.append(context))
-
-    loop.run_until_complete(main())
-    assert main_called, "The main function should have been called"
-    
-    # We will now have an error in there, because the task 'async_job' could not 
-    # be entered, because the task 'main' was still being executed by the event loop.
-    assert len(exceptions) == 1
-    assert isinstance(exceptions[0]["exception"], RuntimeError)
-
 
-def test_call_sync(loop, application):
-    """Re-entering the event loop from a Task will fail if there is another
-    runnable task."""
+@pytest.mark.parametrize(
+    "async_wrap, expect_async_called, expect_exception",
+    [(False, False, True), (True, True, False)],
+)
+def test_async_wrap(
+    loop, application, async_wrap, expect_async_called, expect_exception
+):
+    """
+    Re-entering the event loop from a Task will fail if there is another
+    runnable task.
+    """
     async_called = False
     main_called = False
-    
+
     async def async_job():
         nonlocal async_called
         async_called = True
@@ -840,24 +814,31 @@ def sync_callback():
         asyncio.create_task(async_job())
         assert not async_called
         application.processEvents()
-        assert async_called
+        assert async_called if expect_async_called else not async_called
         return 1
 
     async def main():
         nonlocal main_called
-        res = await qasync.call_sync(sync_callback)
+        if async_wrap:
+            res = await qasync.asyncWrap(sync_callback)
+        else:
+            res = sync_callback()
         assert res == 1
         main_called = True
 
-    exceptions= []
+    exceptions = []
     loop.set_exception_handler(lambda loop, context: exceptions.append(context))
 
     loop.run_until_complete(main())
     assert main_called, "The main function should have been called"
-    
-    # We will now have an error in there, because the task 'async_job' could not 
-    # be entered, because the task 'main' was still being executed by the event loop.
-    assert len(exceptions) == 0
+
+    if expect_exception:
+        # We will now have an error in there, because the task 'async_job' could not
+        # be entered, because the task 'main' was still being executed by the event loop.
+        assert len(exceptions) == 1
+        assert isinstance(exceptions[0]["exception"], RuntimeError)
+    else:
+        assert len(exceptions) == 0
 
 
 def test_slow_callback_duration_logging(loop, caplog):