qasync

You can install qasync using pip or uv.

pip install qasync

To perform asynchronous cleanup or logic when a window is closing, decorate the closeEvent method with @asyncClose.

from qasync import asyncClose
from PySide6.QtGui import QCloseEvent

class MainWindow(QWidget):
    @asyncClose
    async def closeEvent(self, event: QCloseEvent):
        self.button.setText("Closing...")
        await asyncio.sleep(1)

To use an async function as a Qt slot (e.g., responding to a button click), decorate the method with @asyncSlot(). This allows you to await coroutines directly within the slot logic.

from qasync import asyncSlot

class MainWindow(QWidget):
    @asyncSlot()
    async def onButtonClicked(self):
        self.button.setText("Loading...")
        await asyncio.sleep(1)
        self.button.setText("Load")

To integrate the asyncio event loop with the Qt event loop, use the loop_factory argument in asyncio.run() (for Python 3.11+) or use qasync.run() (for Python 3.10 and older).

import asyncio
import sys
from PySide6.QtWidgets import QApplication
import qasync
from qasync import QEventLoop

async def main(app):
    # Your application logic here
    pass

if __name__ == "__main__":
    app = QApplication(sys.argv)
    
    # For Python 3.11 or newer:
    asyncio.run(main(app), loop_factory=QEventLoop)
    
    # For Python 3.10 or older:
    # qasync.run(main(app))

You can control which Qt binding qasync uses by setting the QT_API environment variable. This is useful if multiple bindings (e.g., PyQt5 and PySide6) are installed on your system.

Supported values (case-insensitive):

• PyQt6
• PyQt5
• PySide6
• PySide2

If QT_API is not set, qasync will attempt to use the binding that is already imported in sys.modules, or search for the first available binding in the preference order: PyQt6, PyQt5, PySide6, PySide2.

# Example: Forcing PySide6
export QT_API=PySide6
python my_qt_app.py

Ensure your environment meets the following requirements:

• Python: >=3.8, <3.14 (For Python 3.6 or 3.7, use version v0.25.0)
• Qt Bindings: PyQt5, PyQt6, PySide2, or PySide6

The run() function is a convenience wrapper around asyncio.run(). It automatically sets the QEventLoop as the event loop policy, ensuring that the provided coroutine runs on the Qt event loop.

• Python 3.12+: Uses loop_factory to create the QEventLoop.
• Python < 3.12: Sets a DefaultQEventLoopPolicy to ensure asyncio.run() uses the QEventLoop.

import asyncio
from qasync import run

async def main():
    await asyncio.sleep(1)
    print("Done")

run(main())

The QEventLoop class is an implementation of the asyncio event loop that uses the Qt event loop. It allows you to run asynchronous code within a Qt application.

If you are using an existing, already running QApplication, you must instantiate QEventLoop with already_running=True. In this case, you are responsible for manual cleanup using stop() and close().

On Windows, it uses QIOCPEventLoop (Proactor), and on Unix-like systems, it uses QSelectorEventLoop (Selector).

import asyncio
from qasync import QEventLoop

# Example usage with asyncio.run
async def main():
    await asyncio.sleep(1)
    print("Hello from qasync!")

# Note: In Python 3.12+, run() is simplified. 
# For older versions, you might need to provide a loop_factory.
asyncio.run(main(), loop_factory=lambda: QEventLoop(app))

The asyncClose decorator allows you to run asynchronous cleanup or logic immediately before a Qt application or component is closed. It wraps the decorated function, creates an asyncio.Task, and processes Qt events until the task is complete.

from qasync import asyncClose

@asyncClose()
async def cleanup():
    await asyncio.sleep(1)
    print("Cleanup complete")

# Call this when the app is closing
cleanup()

The asyncWrap function wraps a blocking function (like a modal Qt dialog) so it can be awaited within an async function without blocking the main asyncio event loop. It schedules the function to run using a one-shot QTimer in the next event loop iteration.

from qasync import asyncWrap
from PySide6.QtWidgets import QMessageBox

async def show_dialog():
    # This prevents the modal dialog from freezing the asyncio loop
    result = await asyncWrap(
        lambda: QMessageBox.information(None, "Title", "Message")
    )
    print(f"Dialog result: {result}")

The QThreadExecutor provides a thread pool implementation using QThread objects, following the same API as concurrent.futures.Executor. This is useful for offloading blocking tasks to background threads while remaining compatible with the Qt environment.

Use it as a context manager to ensure proper shutdown of worker threads.

from qasync import QThreadExecutor

with QThreadExecutor(max_workers=5) as executor:
    future = executor.submit(lambda x: x * x, 10)
    result = future.result()
    assert result == 100