napari.qt.threading¶

Classes

`FunctionWorker`
`GeneratorWorker`
`GeneratorWorkerSignals`
`WorkerBase`	Base class for creating a Worker that can run in another thread.
`WorkerBaseSignals`

Functions

napari.qt.threading.create_worker(func: Union[function, generator], *args, _start_thread: Optional[bool] = None, _connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None, _progress: Optional[Union[bool, Dict[str, Union[int, bool, str]]]] = None, _worker_class: Optional[Union[Type[napari._qt.qthreading.GeneratorWorker], Type[napari._qt.qthreading.FunctionWorker]]] = None, _ignore_errors: bool = False, **kwargs) → Union[napari._qt.qthreading.FunctionWorker, napari._qt.qthreading.GeneratorWorker][source]¶

Convenience function to start a function in another thread.

By default, uses Worker, but a custom WorkerBase subclass may be provided. If so, it must be a subclass of Worker, which defines a standard set of signals and a run method.

Parameters

func (Callable) – The function to call in another thread.
_start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.
_connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None
_progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None.
_worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.
_ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).
*args – will be passed to func
**kwargs – will be passed to func

Returns

worker – An instantiated worker. If _start_thread was False, the worker will have a .start() method that can be used to start the thread.

Return type

WorkerBase

Raises

TypeError – If a worker_class is provided that is not a subclass of WorkerBase.
TypeError – If _connect is provided and is not a dict of {str: callable}
TypeError – If _progress is provided and function is not a generator

Examples

def long_function(duration):
    import time
    time.sleep(duration)

worker = create_worker(long_function, 10)

napari.qt.threading.thread_worker(function: Optional[Callable] = None, start_thread: Optional[bool] = None, connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None, progress: Optional[Union[bool, Dict[str, Union[int, bool, str]]]] = None, worker_class: Optional[Union[Type[napari._qt.qthreading.GeneratorWorker], Type[napari._qt.qthreading.FunctionWorker]]] = None, ignore_errors: bool = False)[source]¶

Decorator that runs a function in a separate thread when called.

When called, the decorated function returns a WorkerBase. See create_worker() for additional keyword arguments that can be used when calling the function.

The returned worker will have these signals:

started: emitted when the work is started

finished: emitted when the work is finished

returned: emitted with return value

errored: emitted with error object on Exception

It will also have a worker.start() method that can be used to start execution of the function in another thread. (useful if you need to connect callbacks to signals prior to execution)

If the decorated function is a generator, the returned worker will also provide these signals:

yielded: emitted with yielded values

paused: emitted when a running job has successfully paused

resumed: emitted when a paused job has successfully resumed

aborted: emitted when a running job is successfully aborted

And these methods:

quit: ask the thread to quit

toggle_paused: toggle the running state of the thread.

send: send a value into the generator. (This requires that your decorator function uses the value = yield syntax)

Parameters

function (callable) – Function to call in another thread. For communication between threads may be a generator function.
start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.
connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None
progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None. Must be used in conjunction with a generator function.
worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.
ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).

Returns

function that creates a worker, puts it in a new thread and returns the worker instance.

Return type

callable

Examples

@thread_worker
def long_function(start, end):
    # do work, periodically yielding
    i = start
    while i <= end:
        time.sleep(0.1)
        yield i

    # do teardown
    return 'anything'

# call the function to start running in another thread.
worker = long_function()
# connect signals here if desired... or they may be added using the
# `connect` argument in the `@thread_worker` decorator... in which
# case the worker will start immediately when long_function() is called
worker.start()

napari.components.ViewerModel

napari.qt.threading.FunctionWorker