traits_futures.background_progress module

Support for a progress-reporting background call.

The code in this module supports an arbitrary callable that accepts a “progress” named argument, and can use that argument to submit progress information.

Every progress submission also marks a point where the callable can be cancelled.

class traits_futures.background_progress.BackgroundProgress

Bases: traits.has_traits.HasStrictTraits

Object representing the background task to be executed.

args = Tuple()

Positional arguments to be passed to the callable.

callable = Callable()

The callable to be executed.

future_and_callable(cancel_event, message_sender, message_receiver)

Return a future and a linked background callable.

Parameters:

• cancel_event (threading.Event) – Event used to request cancellation of the background task.
• message_sender (MessageSender) – Object used by the background task to send messages to the UI. Supports the context manager protocol, and provides a ‘send’ method.
• message_receiver (MessageReceiver) – Object that remains in the main thread and receives messages sent by the message sender. This is a HasTraits subclass with a ‘message’ Event trait that can be listened to for arriving messages.

Returns:

• future (ProgressFuture) – Foreground object representing the state of the running calculation.
• runner (ProgressBackgroundTask) – Callable to be executed in the background.

kwargs = Dict(Str(), Any())

Named arguments to be passed to the callable.

traits_futures.background_progress.INTERRUPTED = 'interrupted'

Task was cancelled before it started. No arguments.

traits_futures.background_progress.PROGRESS = 'progress'

Task sends progress. Argument is a single object giving progress information. This module does not interpret the contents of the argument.

class traits_futures.background_progress.ProgressBackgroundTask(callable, args, kwargs, message_sender, cancel_event)

Bases: object

Background portion of a progress background task.

This provides the callable that will be submitted to the thread pool, and sends messages to communicate with the ProgressFuture.

send(message_type, message_args=None)

Send a message to the linked future.

Sends a pair consisting of a string giving the message type along with an object providing any relevant arguments. The interpretation of the arguments depends on the message type.

Parameters:

• message_type (string) – Type of the message to be sent.
• message_args (object, optional) – Any arguments relevant to the message. Ideally, should be pickleable and immutable. If not provided, None is sent.

class traits_futures.background_progress.ProgressFuture

Bases: traits.has_traits.HasStrictTraits

Object representing the front-end handle to a ProgressBackgroundTask.

cancel()

Method that can be called from the main thread to indicate that the task should be cancelled (provided it hasn’t already started running).

cancellable = Property(Bool())

True if this task can be cancelled, else False.

done = Property(Bool())

True if we’ve received the final message from the background task, else False. True indicates either that the background task succeeded, or that it raised, or that it was cancelled.

exception = CANCELLING

progress = Event(Any())

Event fired whenever a progress message arrives from the background.

result = CANCELLING

state = FutureState

The state of the background task, to the best of the knowledge of this future.

class traits_futures.background_progress.ProgressReporter(message_sender, cancel_event)

Bases: object

Object used by the target callable to report progress.

report(progress_info)

Send progress information to the linked future.

The progress_info object will eventually be sent to the corresponding future’s progress event trait.

Parameters:progress_info (object) – An arbitrary object representing progress. Ideally, this should be immutable and pickleable.

traits_futures.background_progress.RAISED = 'raised'

Task failed with an exception. Argument gives exception information.

traits_futures.background_progress.RETURNED = 'returned'

Task succeeded and returned a result. Argument is the result.

traits_futures.background_progress.STARTED = 'started'

Task started executing. No arguments.