Skip to content

Threading decorators

Qt objects must generally be used from the thread they live in, and widgets from the main (GUI) thread. These two decorators make a function run in the right thread, whichever thread calls it:

ensure_main_thread
Runs the decorated function, or method, in the main thread.
ensure_object_thread
Runs the decorated method of a QObject in the thread that the object lives in (see Qt's threads and QObjects).

They're meant for calling Qt code from code that doesn't use Qt (such as a callback from another library's thread). Between Qt objects, signals and slots already do this.

Usage

When called from another thread, the decorated function is queued to run in its target thread, and the call returns a concurrent.futures.Future at once. (When called from the target thread, the function runs right away, and the Future it returns is already done.)

from qtpy.QtCore import QObject

from superqt import ensure_main_thread, ensure_object_thread


@ensure_main_thread
def update_label(text):
    print("this runs in the main thread")


class Counter(QObject):
    def __init__(self):
        super().__init__()
        self._value = 1

    @ensure_main_thread
    def show(self):
        print("this runs in the main thread")

    @ensure_object_thread
    def reset(self):
        print("this runs in the thread that the Counter lives in")

    @property
    def value(self):
        return self._value

    @value.setter
    @ensure_object_thread
    def value(self, value):
        print("setters work too")
        self._value = value

Waiting for the result

To wait for the function to finish, and get its return value, pass await_return=True. It waits for at most timeout milliseconds (1000 by default), and then raises a TimeoutError.

Warning

The calling thread is blocked while it waits.

from concurrent.futures import Future

from superqt import ensure_main_thread


@ensure_main_thread
def get_one():
    return 1


@ensure_main_thread(await_return=True)
def get_two():
    return 2


@ensure_main_thread(await_return=True, timeout=10000)
def get_three():
    return 3


assert isinstance(get_one(), Future)
assert get_two() == 2
assert get_three() == 3

API

ensure_main_thread

ensure_main_thread(
    await_return: Literal[True], timeout: int = 1000
) -> Callable[[Callable[P, R]], Callable[P, R]]
ensure_main_thread(
    func: Callable[P, R],
    await_return: Literal[True],
    timeout: int = 1000,
) -> Callable[P, R]
ensure_main_thread(
    await_return: Literal[False] = False,
    timeout: int = 1000,
) -> Callable[
    [Callable[P, R]], Callable[P, Future[R]]
]
ensure_main_thread(
    func: Callable[P, R],
    await_return: Literal[False] = False,
    timeout: int = 1000,
) -> Callable[P, Future[R]]
ensure_main_thread(
    func: Callable | None = None,
    await_return: bool = False,
    timeout: int = 1000,
)

Decorator that ensures a function is called in the main QApplication thread.

It can be applied to functions or methods.

Parameters:

  • func (callable, default: None ) –

    The method to decorate, must be a method on a QObject.

  • await_return (bool, default: False ) –

    Whether to block and wait for the result of the function, or return immediately. by default False

  • timeout (int, default: 1000 ) –

    If await_return is True, time (in milliseconds) to wait for the result before raising a TimeoutError, by default 1000

ensure_object_thread

ensure_object_thread(
    await_return: Literal[True], timeout: int = 1000
) -> Callable[[Callable[P, R]], Callable[P, R]]
ensure_object_thread(
    func: Callable[P, R],
    await_return: Literal[True],
    timeout: int = 1000,
) -> Callable[P, R]
ensure_object_thread(
    await_return: Literal[False] = False,
    timeout: int = 1000,
) -> Callable[
    [Callable[P, R]], Callable[P, Future[R]]
]
ensure_object_thread(
    func: Callable[P, R],
    await_return: Literal[False] = False,
    timeout: int = 1000,
) -> Callable[P, Future[R]]
ensure_object_thread(
    func: Callable | None = None,
    await_return: bool = False,
    timeout: int = 1000,
)

Decorator that ensures a QObject method is called in the object's thread.

It must be applied to methods of QObjects subclasses.

Parameters:

  • func (callable, default: None ) –

    The method to decorate, must be a method on a QObject.

  • await_return (bool, default: False ) –

    Whether to block and wait for the result of the function, or return immediately. by default False

  • timeout (int, default: 1000 ) –

    If await_return is True, time (in milliseconds) to wait for the result before raising a TimeoutError, by default 1000