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

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

StepEventType

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

EndEventType

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

__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

(string) A human-readable describing the operation being performed.

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

(string) A human-readable describing the operation being performed.

steps

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

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

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

step

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

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

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

exit_state

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