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