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[source]

Bases: traits.has_traits.HasStrictTraits

Object representing the background task to be executed.

args = Tuple()

Positional arguments to be passed to the callable.

background_task()[source]

Return a background callable for this task specification.

Returns

Callable accepting arguments send and cancelled. The callable can use send to send messages and cancelled to check whether cancellation has been requested.

Return type

collections.abc.Callable

callable = Callable()

The callable to be executed.

future()[source]

Return a Future for the background task.

Returns

future – Future object that can be used to monitor the status of the background task.

Return type

ProgressFuture

kwargs = Dict(Str())

Named arguments to be passed to the callable.

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)[source]

Bases: object

Background portion of a progress background task.

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

exception traits_futures.background_progress.ProgressCancelled[source]

Bases: Exception

Exception raised when progress reporting is interrupted by task cancellation.

class traits_futures.background_progress.ProgressFuture[source]

Bases: traits_futures.base_future.BaseFuture

Object representing the front-end handle to a ProgressBackgroundTask.

progress = Event()

Event fired whenever a progress message arrives from the background.

class traits_futures.background_progress.ProgressReporter(send, cancelled)[source]

Bases: object

Object used by the target callable to report progress.

report(progress_info)[source]

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.

Raises

ProgressCancelled – If a cancellation request for this task has already been made. In this case, the exception will be raised before any progress information is sent.

traits_futures.background_progress.submit_progress(executor, callable, *args, **kwargs)[source]

Convenience function to submit a background progress call.

Parameters
  • executor (TraitsExecutor) – Executor to submit the task to.

  • callable (collections.abc.Callable) – Callable that executes the progress-providing function. This callable must accept a “progress” named argument, in addition to the provided arguments. The callable may then call the “progress” argument to report progress.

  • *args – Positional arguments to pass to the callable.

  • **kwargs – Named arguments other than “progress” to pass to the callable. These must not include “progress”.

Returns

future – Object representing the state of the background task.

Return type

ProgressFuture