API Usage¶

`AsyncManager`¶

class PySink.AsyncManager¶

Bases: QObject

Class that manages all workers and their corresponding threads. Once a worker is created, provide it to the start_worker() method to start the worker’s long-running task. If the worker is of type CancellableAsyncWorker, it can be cancelled by passing the worker’s id to the cancel_worker() method. All threads/workers will be garbage collected upon completion.

Worker signals are also exposed via the provided signal attributes worker_started_signal , worker_progress_signal , and worker_finished_signal . Once all active workers are complete, the manager will emit its all_workers_finished_signal

all_workers_finished_signal¶: Signal(): Signals that all workers have finished their tasks.

cancel_all_workers() → {<class 'str'>: <class 'str'>}¶

Attempts to cancel all workers that are active and cancellable..

Returns:: A dictionary of errors if they are encountered, keyed by worker id.
Return type:: dict

cancel_worker(worker_id: str) → str¶

Attempts to cancel the worker with the given id…

Parameters:: worker_id (str) – The unique identifier of the worker to be cancelled
Returns:: An message describing the issue if the worker could not be cancelled or does not exist
Return type:: str

start_worker(worker: AsyncWorker) → None¶

Starts the worker on a new thread (or queues the worker if there are no threads available). Once the worker is on the thread, the worker’s run() method is called..

Parameters:: worker (AsyncWorker) – The worker to be run
Raises:: Exception – Raised if a worker is provided that has the same id as one that is already running.

worker_finished_signal¶: Signal(AsyncWorkerResults): Signals that a worker has finished its task. Contains the results of the worker.

worker_progress_signal¶: Signal(AsyncWorkerProgress): Signal that contains progress data for a worker.

worker_started_signal¶: Signal(str): Signals that a worker has started its task. Contains the id of the worker.

`AsyncWorker`¶

class PySink.AsyncWorker(identifier: str | None = None)¶

Bases: QRunnable

A class that represents an Asynchronous Worker. Workers should inherit from this class and perform their long-running tasks by overriding the run() method.

To define custom results and signals, redefine them within your custom worker’s __init__ method..

Parameters:: identifier (str, optional) – A unique identifier to differentiate this worker from other workers. Defaults to a uuid4 string

complete(**kwargs) → None¶

Signals the completion of the worker’s long-running task. This should be called at the end of the overridden run() method. Calling this method emits the worker’s results via the self.signals.finished signal.

By default, the kwargs provided will be packaged into results.results_dict as key-value pairs. However, if a custom result type was defined within __init__(), the key-word arguments will also be mapped to their corresponding result attributes (they will still be packed into the result_dict)

Parameters:: kwargs – Result values to be emitted, defined as key-word arguments

emit_start() → None¶: This method can be called within run() to let the application know that the long-running task has begun (this is signalled via the self.signals.started signal). Calling this method is completely optional and does not affect the functionality of the worker.

reset() → None¶: Resets the worker’s state. All warnings and errors will be cleared, and result will be reset to the defined result type.

run() → None¶: Performs the worker’s long-running task. Custom Workers should override this method. By default, this will perform a demo task of counting to 5 at a one-second interval.

update_progress(progress_value: int, message='') → None¶

Emits the progress value and message. These values are emitted via the self.signals.progress signal..

Parameters:

progress_value (int) – The current progress value. For discrete behavior, this value should be [0, 100]. For indeterminate behavior, this value should be -1.
message (str, optional) – A message describing the current progress stage of the worker (‘Downloading’, ‘Calculating’, etc).

`CancellableAsyncWorker`¶

class PySink.CancellableAsyncWorker(*args, **kwargs)¶

Bases: AsyncWorker

A class that represents a cancellable AsyncWorker. Any workers that need to be cancellable should inherit from this class. CancellableAsyncWorker inherits from AsyncWorker, and offers the ability to cancel the worker’s task at any time by calling the cancel() method.

IMPORTANT NOTE: While calling cancel() effectively halts the worker’s task, it DOES NOT terminate the execution of run() (doing so could result in unwanted data corruption). Within run(), you should poll the cancelled flag intermittently and return early if it is True.

cancel() → None¶

Cancels the worker. A ‘Cancelled’ message is appended to both warnings and errors, and the finished signal is emitted (similar to calling complete()). Once this method is called, all internal method calls/signal updates will be ignored, and an internal flag called cancelled is set to True.