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: 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(cancel)

Return a Future for the background task.

Parameters:

cancel – Zero-argument callable, returning no useful result. The returned future’s cancel method should call this to request cancellation of the associated 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.

task()

Return a background callable for this task specification.

Returns:

task – 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:

ProgressTask

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.ProgressFuture

Bases: BaseFuture

Object representing the front-end handle to a ProgressTask.

progress = Event()

Event fired whenever a progress message arrives from the background.

class traits_futures.background_progress.ProgressReporter(send, cancelled)

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.

Raises:

TaskCancelled – 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.

class traits_futures.background_progress.ProgressTask(callable, args, kwargs)

Bases: BaseTask

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.

run()

Run the body of the background task.

Returns:

any – May return any object. That object will be delivered to the future’s result attribute.

Return type:

object

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

Submit a progress-reporting task to an executor.

Parameters:

• executor (TraitsExecutor) – Executor to submit the task to. This argument should always be passed by position rather than by name. Future versions of the library may enforce this restriction.

• 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. This argument should always be passed by position rather than by name. Future versions of the library may enforce this restriction.

• *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