Progress Events

Events and helpers for managing progress indicators

class encore.events.progress_events.ProgressManager(event_manager=None, source=None, operation_id=None, message='Performing operation', steps=-1, **kwargs)

Utility class for managing progress events

This class provides a context manager that will probably be sufficient in most use cases. The standard method of invoking it will be something like:

with ProgressManager(event_manager, source, id, "Performing operation", steps) as progress:
    for step in range(steps):
        ... do work ...
        progress(step)

This pattern guarantees that the appropriate Start and Stop events are always emitted, even if there is an exception.

If finer-grained control is needed, the class also provides start(), step() and stop() methods that can be invoked in when required. In particular, this pattern may be useful for more fine-grained exception reporting:

progress = ProgressManager(event_manager, source, id, "Performing operation", steps)
progress.start()
try:
    for step in range(steps):
        ... do work ...
        progress(step)
except ... as exc:
    progress.end(message='Failure mode 1', end_state='warning')
except ... as exc:
    progress.end(message='Failure mode 2', end_state='error')
except Exception as exc:
    progress.end(message=str(exc), end_state='exception')
else:
    progress.end(message='Success', end_state='normal')

StartEventType

The actual event class to use when emitting a start event. The default is ProgressStartEvent, but subclasses may choose to override.

Type:

ProgressStartEvent subclass

StepEventType

The actual event class to use when emitting a step event. The default is ProgressStepEvent, but subclasses may choose to override.

Type:

ProgressStepEvent subclass

EndEventType

The actual event class to use when emitting an end event. The default is ProgressEndEvent, but subclasses may choose to override.

Type:

ProgressEndEvent subclass

__init__(event_manager=None, source=None, operation_id=None, message='Performing operation', steps=-1, **kwargs)

Create a progress manager instance

Parameters:

• event_manager (EventManager instance) – The event manager to use when emitting events.

• source (any) – The object that is the source of the events.

• operation_id (any) – The unique identifier for the operation.

• message (string) – The default message to use for events which are emitted.

• steps (int) – The number of steps. If this is not known, use -1.

end(message=None, exit_state='normal', **extra_kwargs)

Emit a step event

By default creates an instance of StepEventType with the appropriate attributes.

Parameters:

• message (str) – The message to be passed to the event’s constructor. By default will use self.message.

• exit_state (one of normal, warning, error or exception) – The exit_state of the event.

• extra_kwargs (dict) – Additional arguments to be passed through to the event’s constructor.

start(**extra_kwargs)

Emit a start event

By default creates an instance of StartEventType with the appropriate attributes.

Parameters:

extra_kwargs (dict) – Additional arguments to be passed through to the event’s constructor.

step(message=None, step=None, **extra_kwargs)

Emit a step event

By default creates an instance of StepEventType with the appropriate attributes.

Parameters:

• message (str) – The message to be passed to the event’s constructor. By default will use self.message.

• step (int) – The step number. By default keeps an internal step count, incremented each time this method is called.

• extra_kwargs (dict) – Additional arguments to be passed through to the event’s constructor.

class encore.events.progress_events.ProgressEvent(source=None, **kwargs)

Abstract base class for all progress events

This class is provided so that listeners can easily listen for any type ProgressEvent.

operation_id

A unique identifier for the operation being performed.

message

A human-readable describing the operation being performed.

Type:

string

class encore.events.progress_events.ProgressStartEvent(source=None, **kwargs)

Event emitted at the start of an operation

operation_id

A unique identifier for the operation being performed.

message

A human-readable describing the operation being performed.

Type:

string

steps

The number of steps in the operation. If unknown or variable, use -1.

Type:

int

class encore.events.progress_events.ProgressStepEvent(source=None, **kwargs)

Event emitted periodically during an operation

operation_id

A unique identifier for the operation being performed.

message

A human-readable describing the state of the operation being performed.

Type:

string

step

The count of the step. If unknown, use -1.

Type:

int

class encore.events.progress_events.ProgressEndEvent(source=None, **kwargs)

Event emitted at the end of an operation

operation_id

A unique identifier for the operation that is finished.

message

A human-readable describing the state of the operation that ended.

Type:

string

exit_state

A constant describing the end state of the operation. One of normal, warning, error or exception.

Type:

string