bluesky.preprocessors.plan_mutator¶

bluesky.preprocessors.plan_mutator(plan, msg_proc)[source]¶

Alter the contents of a plan on the fly by changing or inserting messages.

Parameters

plangenerator

a generator that yields messages (Msg objects)

msg_proccallable

This function takes in a message and specifies messages(s) to replace it with. The function must account for what type of response the message would prompt. For example, an ‘open_run’ message causes the RunEngine to send a uid string back to the plan, while a ‘set’ message causes the RunEngine to send a status object back to the plan. The function should return a pair of generators (head, tail) that yield messages. The last message out of the head generator is the one whose response will be sent back to the host plan. Therefore, that message should prompt a response compatible with the message that it is replacing. Any responses to all other messages will be swallowed. As shorthand, either head or tail can be replaced by None. This means:

(None, None) No-op. Let the original message pass through.
(head, None) Mutate and/or insert messages before the original message.
(head, tail) As above, and additionally insert messages after.
(None, tail) Let the original message pass through and then insert messages after.

The reason for returning a pair of generators instead of just one is to provide a way to specify which message’s response should be sent out to the host plan. Again, it’s the last message yielded by the first generator (head).

Yields

msgMsg: messages from plan, altered by msg_proc