bluesky.run_engine.RunEngine

class bluesky.run_engine.RunEngine(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, md_normalizer=None, scan_id_source=<function default_scan_id_source>, during_task=None, call_returns_result=False)

The Run Engine execute messages and emits Documents.

Parameters:

mddict-like, optional

The default is a standard Python dictionary, but fancier objects can be used to store long-term history and persist it between sessions. The standard configuration instantiates a Run Engine with historydict.HistoryDict, a simple interface to a sqlite file. Any object supporting __getitem__, __setitem__, and clear will work.

loopasyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

preprocessorslist, optional

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

context_managerslist, optional

Context managers that will be entered when we run a plan. The context managers will be composed in order, much like the preprocessors. If this argument is omitted, we will use a user-oriented handler for SIGINT. The elements of this list will be passed this RunEngine instance as their only argument. You may pass an empty list if you would like a RunEngine with no signal handling and no context managers.

md_validatorcallable, optional

a function that raises and prevents starting a run if it deems the metadata to be invalid or incomplete Expected signature: f(md) Function should raise if md is invalid. What that means is completely up to the user. The function’s return value is ignored.

md_normalizercallable, optional

a function that, similar to md_validator, raises and prevents starting a run if it deems the metadata to be invalid or incomplete. If it succeeds, it returns the normalized/transformed version of the original metadata. Expected signature: f(md) Function should raise if md is invalid. What that means is completely up to the user. Expected return: normalized metadata

scan_id_sourcecallable, optional

a function that will be used to calculate scan_id. Default is to increment scan_id by 1 each time. However you could pass in a customized function to get a scan_id from any source. Expected signature: f(md) Expected return: updated scan_id value

during_taskreference to an object of class DuringTask, optional

Class methods: block() to be run to block the main thread during RE.__call__

The required signatures for the class methods

def block(ev: Threading.Event) -> None:
    "Returns when ev is set"

The default value handles the cases of:

• Matplotlib is not imported (just wait on the event)

• Matplotlib is imported, but not using a Qt, notebook or ipympl backend (just wait on the event)

• Matplotlib is imported and using a Qt backend (run the Qt app on the main thread until the run finishes)

• Matplotlib is imported and using a nbagg or ipympl backend ( wait on the event and poll to push updates to the browser)

call_returns_resultbool, default False

A flag that controls the return value of __call__ If True, the RunEngine will return a :class:RunEngineResult object that contains information about the plan that was run. If False, the RunEngine will return a tuple of uids. Defaults to False to preserve the old RunEngine behavior, but the default is expected to change to True in the future.

Attributes:

md

Direct access to the dict-like persistent storage described above

record_interruptions

False by default. Set to True to generate an extra event stream that records any interruptions (pauses, suspensions).

state

{‘idle’, ‘running’, ‘paused’}

suspenders

Read-only collection of bluesky.suspenders.SuspenderBase objects which can suspend and resume execution; see related methods.

preprocessorslist

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

msg_hook

Callable that receives all messages before they are processed (useful for logging or other development purposes); expected signature is f(msg) where msg is a bluesky.Msg, a kind of namedtuple; default is None.

state_hook

Callable with signature f(new_state, old_state) that will be called whenever the RunEngine’s state attribute is updated; default is None

waiting_hook

Callable with signature f(status_object) that will be called whenever the RunEngine is waiting for long-running commands (trigger, set, kickoff, complete) to complete. This hook is useful to incorporate a progress bar.

ignore_callback_exceptions

Boolean, False by default.

call_returns_result

Boolean, False by default. If False, RunEngine will return uuid list after running a plan. If True, RunEngine will return a RunEngineResult object that contains the plan result, error status, and uuid list.

loopasyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

max_depth

Maximum stack depth; set this to prevent users from calling the RunEngine inside a function (which can result in unexpected behavior and breaks introspection tools). Default is None. For built-in Python interpreter, set to 2. For IPython, set to 11 (tested on IPython 5.1.0; other versions may vary).

pause_msgstr

The message printed when a run is interrupted. This message includes instructions of changing the state of the RunEngine. It is set to bluesky.run_engine.PAUSE_MSG by default and can be modified based on needs.

commands:

The list of commands available to Msg.

__init__(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, md_normalizer=None, scan_id_source=<function default_scan_id_source>, during_task=None, call_returns_result=False)

Methods

__init__([md, loop, preprocessors, ...])
abort([reason])	Stop a running or paused plan and mark it as aborted.
clear_suspenders()	Uninstall all suspenders.
emit(name, doc)
emit_sync(name, doc)	Process blocking callbacks and schedule non-blocking callbacks.
halt()	Stop the running plan and do not allow the plan a chance to clean up.
install_suspender(suspender)	Install a 'suspender', which can suspend and resume execution.
print_command_registry([verbose])	This conveniently prints the command registry of available commands.
register_command(name, func)	Register a new Message command.
remove_suspender(suspender)	Uninstall a suspender.
request_pause([defer])	Command the Run Engine to pause.
request_suspend(fut, *[, pre_plan, ...])	Request that the run suspend itself until the future is finished.
reset()	Clean up caches and unsubscribe subscriptions.
resume()	Resume a paused plan from the last checkpoint.
stop()	Stop a running or paused plan, but mark it as successful (not aborted).
subscribe(func[, name])	Register a callback function to consume documents.
unregister_command(name)	Unregister a Message command.
unsubscribe(token)	Unregister a callback function its integer ID.

Attributes

call_returns_result
commands	The list of commands available to Msg.
deferred_pause_requested	The property returns True if deferred pause was requested, but not processed.
ignore_callback_exceptions
loop
resumable	i.e., can the plan in progress by rewound
rewindable
state
suspenders
verbose