Bluesky数据采集框架-7
内建预处理程序
每个名为
1、bluesky.preprocessors.baseline_decorator
# 在open_run后，积累一个所有设备的baseline的预处理程序
bluesky.preprocessors.baseline_decorator(plan, devices, name='baseline')¶
Preprocessor that records a baseline of all devices after open_run
"""
1、plan：可迭代的或迭代器。一个生成器，list或者包含Msg对象类似的
2、devices：集合。要读取的设备集合。如果None，这个计划无修改的传递
3、name：string，可选的，事件流的名称，默认，'baseline'。
生成：msg:Msg 来自计划的消息，插入的'set'消息。
"""2、bluesky.preprocessors.baseline_wrapper
# 记录在open_run后所有设备一个baseline的预处理程序。
# 默认为名为"baseline"的单独事件流指定读取。
bluesky.preprocessors.baseline_wrapper(plan, devices, name='baseline')
"""
参数：
1、plan：可迭代或迭代器，一个生成器，列表或者包含msg对象的类似
2、devices：要读取设备的集合，如果None，计划不变的传递c
3、name：string, 可选的，事件流的名称，默认，'baseline'
生成：msg：Msg 来自计划的消息，带插入的'set'消息。
"""3、bluesky.preprocessors.contingency_wrapper
# try…except…else…finally helper
# 一个简化但功能弱的错误处理预处理程序finalize_wrapper()
bluesky.preprocessors.contingency_wrapper(plan, *, except_plan=None, else_plan=None, final_plan=None, pause_for_debug=False, auto_raise=True)
"""
参数：
1、plan:可迭代或迭代器，一个生成器，list或包含Msg对象的类似
2、except_plan：生成器函数，可选, 将用异常调用这个，作为唯一输入。这个计划不需要再次产生，但如果你想要更改这个异常，可以的。仅Exception的子类将被传入，将看不到GeneratorExit, SystemExit,或KeyboardInterrupt。
3、else_plan：生成器函数，可选,如果计划不产生异常完成了，将不带参数地调用这个。
4、final_plan：生成器函数，可选,一个生成器，list或包含Msg对象的类似，或者返回一个的可调用；无论在第一个计划章发生什么，尝试被运行。
5、pause_for_debug：bool, 可选的，遇到一个异常，如果在运行清理的final_plan前，这个计划应该暂停。这仅用作调试工具。
6、auto_raise：bool, 可选的，如果异常应该总是被再次引起，无论except_plan做什么。注意：这对后向兼容性默认为True，这不是一个except语句的常见行为。
生成：msg:Msg 在它终止或者产生一个错误前，来自计划的消息，接着来自final_plan的消息
"""4、bluesky.preprocessors.finalize_decorator
# try…finally helper
# 运行第一个计划，接着第二个。如果任何消息在RunEngine中产生一个错误
# 注意：这个装饰器需要一个生成器函数，因而，它可以被多次使用，
# 而bluesky.plans.finalize_wrapper()尝试察南一个生成器函数或者一个生成器实例。
bluesky.preprocessors.finalize_decorator(final_plan)，第二个计划无论如何将尝试被运行。
"""
参数：
final_plan：callable，一个可调用的，它返回一个生成器，list或者包含Msg对象的类似；
在第一个计划中无论发生什么，尝试被运行。
生成：在它终止或者产生一个错误前，来自计划的消息，接着来自final_plan的消息
"""5、bluesky.preprocessors.finalize_decorator
# try…finally helper
# 运行第一个计划，接着第二个。如果任何消息在RunEngine中产生一个错误，
# 第二个无论如何尝试被运行。
# 更复杂和更加功能完整的错误处理预处理程序见contingency_wrapper()
bluesky.preprocessors.finalize_wrapper(plan, final_plan, *, pause_for_debug=False)
"""
参数：
1、plan：可迭代或者迭代器，包含Msg对象的类似
2、final_plan：callable, iterable or iterator，一个迭代器，list或者包含Msg的类似，或者一个返回一个的可调用；无论第一个计划发生了什么，尝试被运行。
3、pause_for_debug：bool, 可选的，如果遇到一个异常时在运行清理的final_plan前，计划应该暂停。这仅用作调试工具。
生成：在它终止或者产生一个错误前，来自计划的消息，接着来自final_plan的消息。
"""6、bluesky.preprocessors.fly_during_decorator
# 开始并且在运行中采集"flyer"对象(异步采集)。
# 这是一个在打开一个run后和在它被关闭前立即掺入消息的预处理程序。
bluesky.preprocessors.fly_during_decorator(plan, flyers)
"""
参数：
1、plan：iterable or iterator，一个生成器，list或者包含Msg对象的类似。
2、flyers：collection，支持flyer接口的对象。
生成：msg:Msg，来自插入了‘kickoff’, ‘wait’ 和 ‘collect’的消息的消息
"""7、bluesky.preprocessors.fly_during_wrapper
# 开始并且在运行中采集"flyer"(异步采集)对象.
# 这是一个在一个run被打开并且在它被关闭前立即插入消息的预处理程序。
bluesky.preprocessors.fly_during_wrapper(plan, flyers)
"""
参数：
1、plan：iterable or iterator，一个生成器，list或者包含Msg对象的类型。
2、flyers：collection，支持flyer接口的对象。
生成：来自插入了‘kickoff’, ‘wait’ 和 ‘collect’消息的消息。
"""8、bluesky.preprocessors.inject_md_decorator
# 插入其它的元数据到一个run。
# 遇到了重叠的键，这优先于原来的元数据字典，但它不更改原来的元数据字典(它使用ChainMap)。
bluesky.preprocessors.inject_md_decorator(plan, md)
"""
参数：
1、plan：iterable or iterator，包含Msg对象的类似。
2、md：dict，metadata
"""
9、bluesky.preprocessors.inject_md_wrapper
# 插入其它的元数据到一个run
# 遇到重叠键时，这优先于原来的元数据字典，但它不更改原来的元数据字典(它使用ChainMap).
bluesky.preprocessors.inject_md_wrapper(plan, md)
"""
1、planiterable 或 iterator，一个生成器，list或包含Msg对象的类似
2、md：dict，metadata
"""10、bluesky.preprocessors.lazily_stage_decorator
# 这是一个预处理程序，它插入'stage'消息并且在末尾添加"unstage"。
# object’s ultimate parent 在计划中首次看到一个对象时，它被staged。
# 为了避免冗余的staging，我们实际stage对象的最终父对象。
# 最终，在一个最终块中，为每个'stage'消息发出一个'unstage'消息。
bluesky.preprocessors.lazily_stage_decorator(plan)
"""
参数：
plan：iterable 或 iterator，包含Msg对象的类似的。
生成：
产生：来自插入了'stage'消息和末尾添加了'unstage'消息的计划的消息。
"""11、bluesky.preprocessors.lazily_stage_wrapper
# 这是一个预处理器，它插入'stage'消息并且在末尾添加'unstage'。
# 在计划中首次见到一个对象，它被staged。为了避免多余的staging, 我们实际
# stage对象的最终父对象。
# 最后，在一个最终块中，对每个'stage'消息发出一个'unstage'消息。
bluesky.preprocessors.lazily_stage_wrapper(plan)
"""
参数：
plan：iterable 或 iterator，一个生成器，list或者包含Msg对象的类似的。
生成：
msg：Msg：来自插入了'stage'消息和在末尾添加了'unstage'消息的计划的消息。
"""12、bluesky.preprocessors.monitor_during_decorator
# 在运行中，监视(异步读取)设备。
# 它时一个预处理程序，它在一个run被打开后和在其被关闭前立即插入消息。
bluesky.preprocessors.monitor_during_decorator(plan, signals)
"""
1、plan:iterable 或 iterator，一个生成器，list或者包含Msg对象的类似的。
2、signals：collection，支持Signal接口的对象。
生成：msg：Msg，有插入了‘monitor’和 ‘unmontior’消息的计划的消息。
"""13、bluesky.preprocessors.monitor_during_wrapper
# 在运行中，监视(异步读取)设备。
# 它时一个预处理程序，它在一个run被打开后和在其被关闭前立即插入消息。
bluesky.preprocessors.monitor_during_wrapper(plan, signals)[source]¶
"""
1、plan：iterable 或 iterator，生成器，list或者包含Msg对象的类似的。
2、signals：collection，支持Signal接口的对象。
生成：msg:Msg 来自有插入的‘monitor’和 ‘unmontior’消息的计划的消息。
"""14、bluesky.preprocessors.relative_set_decorator
# 以相对于初始位置解析设备上的'set'消息。
bluesky.preprocessors.relative_set_decorator(plan, devices=None)
"""
参数：
1、plan：iterable 或 iterator 一个生成器，list或者包含Msg对象的类似的。
2、devices：collection 或 None, 可选的，如果默认(None)，应用到由这个计划移动的所有设备上。
生成：msg:Msg，来自有插入了'read'消息和更改的'set'消息的计划的消息
"""15、bluesky.preprocessors.relative_set_wrapper
# 相对于初始位置解析设备上的'set'消息。
bluesky.preprocessors.relative_set_wrapper(plan, devices=None)[source]
"""
1、plan：iterable 或 iterator，一个生成器，list或者包含了Msg对象的类似的。
2、devices：collection 或 None, 可选的，如果默认(None)，应用到由这个计划移动的所有设备上。
生成：msg：Msg，来自有插入了'read'消息和更改的'set'消息的计划的消息。
"""
16、bluesky.preprocessors.reset_positions_decorator
# 结束时，返回可移动设备到它们的初始位置。
bluesky.preprocessors.reset_positions_decorator(plan, devices=None)¶
"""
参数：
1、plan：iterable 或 iterator，一个生成器，list或者包含Msg对象的类似的。
2、devices：collection 或 None, 可选的，如果默认(None)，应用到由此计划移动的所有设备上。
生成：msg:Msg，来自有插入了'read'和最终插入了'set'消息的计划的消息。
"""17、bluesky.preprocessors.reset_positions_wrapper
# 结束时，返回可移动设备到它们的初始位置。
bluesky.preprocessors.reset_positions_wrapper(plan, devices=None)[source]¶
"""
参数：
1、plan：iterable 或 iterator，一个生成器，list或者包含Msg对象的类似的。
2、devices：collection 或 None, 可选的，如果默认(None)，应用到由此计划移动的所有设备上。
生成：有插入了'read'和最终插入了'set'的消息。
"""18、bluesky.preprocessors.run_decorator
# 放在‘open_run’ 和 ‘close_run’消息里。
bluesky.preprocessors.run_decorator(plan, *, md=None)
"""
参数：
1、plan：iterable 或 iterator，一个生成器，list或包含Msg对象的类似的
2、md：dict, 可选的，被传入'open_run'消息的元数据
"""19、bluesky.preprocessors.run_wrapper
# 放在‘open_run’ 和 ‘close_run’消息里。
bluesky.preprocessors.run_wrapper(plan, *, md=None)
"""
参数：
1、plan：iterable 或 iterator，一个生成器，list或者包含了Msg对象的类似的。
2、2、md：dict, 可选的，被传入'open_run'消息的元数据
"""20、bluesky.preprocessors.stage_decorator
# 'Stage'设备(即：为使用它们做好准备，'arm'它们)并且接着unstage。
bluesky.preprocessors.stage_decorator(plan, devices)
"""
1、plan：iterable 或 iterator，一个生成器，list或者包含Msg对象的类似的。
2、devices：collection，进入时设备列表立即stage，而退出时unstage
生成：msg:Msg 来自有插入了'stage'和最终'unstage'消息的计划的消息
"""21、bluesky.preprocessors.stage_wrapper
# 'stage'设备(即：为使用它们做好准备，'arm'它们)并且接着unstage.
bluesky.preprocessors.stage_wrapper(plan, devices)
"""
1、plan：iterable 或 iterator，一个生成器，list或者包含了Msg对象的类似的。
2、devices: collection, 在进入时立即准备好设备列表并且在退出时unstage。
产生：msg:Msg 有插入了'stage'和最终插入了'unstage'消息的计划的消息。
"""22、 bluesky.preprocessors.subs_decorator
# 向document流订阅回调，最终，取消奥订阅。
bluesky.preprocessors.subs_decorator(plan, subs)
"""
参数：
1、plan：iterable 或 iterator，生成器，list，或者包含了Msg对象的类似的。
2、subs:callable, 可调用的列表，或者可调用的列表的字典
每种请求的文档路由到一个函数列表。输入被规范化为一个函数列表的字典，像这样：
None -> {‘all’: [], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
func -> {‘all’: [func], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
[f1, f2] -> {‘all’: [f1, f2], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
{‘event’: [func]} -> {‘all’: [], ‘start’: [], ‘stop’: [],
‘event’: [func], ‘descriptor’: []}
函数签名必须遵守f(name, doc)，此处名称是{‘all’, ‘start’, ‘stop’, ‘event’, ‘descriptor’}之一，而doc是一个字典。
生成：msg:Msg，来自有插入了‘subscribe’ 和末尾添加了 ‘unsubscribe’ 消息的计划的消息。
"""23、bluesky.preprocessors.subs_wrapper
# 向document流订阅回调，最终，取消奥订阅。
bluesky.preprocessors.subs_wrapper(plan, subs)
"""
参数：
1、plan：iterable 或 iterator，生成器，list，或者包含了Msg对象的类似的。
2、subs:callable, 可调用的列表，或者可调用的列表的字典
每种请求的文档路由到一个函数列表。输入被规范化为一个函数列表的字典，像这样：
None -> {‘all’: [], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
func -> {‘all’: [func], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
[f1, f2] -> {‘all’: [f1, f2], ‘start’: [], ‘stop’: [], ‘event’: [],
‘descriptor’: []}
{‘event’: [func]} -> {‘all’: [], ‘start’: [], ‘stop’: [],
‘event’: [func], ‘descriptor’: []}
函数签名必须遵守f(name, doc)，此处名称是{‘all’, ‘start’, ‘stop’, ‘event’, ‘descriptor’}之一，而doc是一个字典。
生成：msg:Msg，来自有插入了‘subscribe’ 和末尾添加了 ‘unsubscribe’ 消息的计划的消息。
"""24、bluesky.preprocessors.suspend_decorator
# 向RunEngine安装了suspenders，并且在结束时删除它们。
bluesky.preprocessors.suspend_decorator(plan, suspenders)
"""
参数：
1、planiterable 或 iterator：一个生成器，list或者包含了Msg对象的类似的。
2、suspenders：suspender 或suspenders列表，用于这个wrapper持续事件的Suspenders
生成：来自插入了‘install_suspender’和末尾插入了‘remove_suspender’消息的计划的消息。
"""25、bluesky.preprocessors.suspend_wrapper
# 向RunEngine安装了suspenders，并且在结束时删除它们。
bluesky.preprocessors.suspend_wrapper(plan, suspenders)[source]
"""
参数：
1、planiterable 或 iterator：一个生成器，list或者包含了Msg对象的类似的。
2、suspenders：suspender 或suspenders列表，用于这个wrapper持续事件的Suspenders
生成：来自插入了‘install_suspender’和末尾插入了‘remove_suspender’消息的计划的消息。
"""自定义预处理程序
使用msg_mutator()(用于就地更改消息)和plan_mutator()(用于插入消息到这个计划或者移除消息)实现了这个预处理程序。通过示例学习这个是最简单的，在plans模块的源代码学习内建处理程序的实现。
用per_step的自定义步进扫描
一维和多维计划是组成(1)设置，(2)在一个计划上的循环来在每个位置执行，(3)清理。
我们为自定义步进(2)提供了一个hook。这使你能无需从头开始编写一个已有计划的一个变体。
对于一维计划，默认内循环是：
from bluesky.plan_stubs import checkpoint, abs_set, trigger_and_read
def one_1d_step(detectors, motor, step):
"""
步进扫描的内层循环。这是在1D计划中'per_step'参数的默认函数。
"""
yield from checkpoint()
yield from abs_set(motor, step, wait=True)
return (yield from trigger_and_read(list(detectors) + [motor]))某个用户定义的具有相同签名的函数，custom_step，可以在其位置被使用：
scan([det], motor, 1, 5, 5, per_step=custom_step)为了方便，这可以被包进一个新计划的定义中：
def custom_scan(detectors, motor, start, stop, step, *, md=None):
yield from scan([det], motor, start, stop, step, md=md
per_step=custom_step)对于多维计划，默认内层循环：
from bluesky.utils import short_uid
from bluesky.plan_stubs import checkpoint, abs_set, wait, trigger_and_read
def one_nd_step(detectors, step, pos_cache):
"""
一个N维步进扫描的内层循环，这是在ND计划中'per_step'的默认函数。
参数：
1、detectors : iterable，要读取的设备
2、step : dict，在这步中映射电机到位置。
3、pos_cache : dict，映射电机到它们最后设定的位置。
"""
def move():
yield from checkpoint()
grp = short_uid('set')
for motor, pos in step.items():
if pos == pos_cache[motor]:
# 这边不移动这个电机
continue
yield from abs_set(motor, pos, group=grp)
pos_cache[motor] = pos
yield from wait(group=grp)
motors = step.keys()
yield from move()
yield from trigger_and_read(list(detectors) + list(motors))同样，一个具有相同签名的自定义函数可以被传递给任意多维计划的per_step参数。
异步计划："飞行扫描"和"监视"
有关这个术语的内容见异步采集章节，接近本章末尾，某些示例计划。
计划工具
这些是有用工具，用于定义自定义计划和计划预处理程序。
1、bluesky.preprocessors.pchain
# 类似itertools.chain，但使用yield from
# 这确保了.send如预期工作，并且下层计划获取了返回值。
bluesky.preprocessors.pchain(*args)
"""
参数：
args：生成器(计划)
生成：msg:Msg ，逐个从每个计划来的消息。
"""2、bluesky.preprocessors.msg_mutator
# 一个简单的预处理程序，它更改或者删除在一个计划中的单个消息。
# 要插入消息，使用plan_mutator
bluesky.preprocessors.msg_mutator(plan, msg_proc)
"""
参数：
1、plan：生成器，一个产生消息(Msg对象)的生成器
2、msg_proc：可调用的，预计签名f(msg)->new_msg或None
生成：来自计划的消息，由msg_proc更改
"""3、bluesky.preprocessors.plan_mutator
# 通过更改或者插入消息，立即更改一个计划的内容。
bluesky.preprocessors.plan_mutator(plan, msg_proc)
"""
参数：
1、plan:生成器，产生消息(Msg对象)的生成器
2、msg_proc：callable，这个函数接收一条消息并且指定替代它的消息。
这个函数必须考虑这条消息会提示什么类型的响应。例如，一条'open_run'消息使得RunEngine发送一个uid string回这个计划，而一条'set'消息使得RunEngine发送一个状态对象回这个计划。
函数应该返回一对生成消息的生成器(head, tail)。出自head生成器的最后消息是其响应将被发回host计划的消息.因而,那消息应该产生一条兼容它正在替换消息的响应.对所有其他消息的任何响应将被吞掉.作为简写,head或tail可以被None替换.这表示:
(None, None) 无操作,让原来的消息通过.
(head, None) 在原来的消息前,改变和/或插入消息.
(head, tail) 同上,在后面更多地插入消息.
(None, tail) 让原先地消息通过,并且接着在后面插入消息.
返回一对生成器而不是仅一个生成器的原因是提供一种指定哪条消息的响应应该被发送回host计划的方式.
再次,它是由第一个生成器(head)产生的最后消息.
生成:msg:Msg 来自plan的消息,由msg_proc改变.
"""
4、bluesky.preprocessors.single_gen
# 把一条消息变成一个计划。
# 如果lambda x: yield x是有效的Python，这将是等效的。
# 在Python 3.6 或 3.7中，我们会得到lambda生成器。
bluesky.preprocessors.single_gen(msg)
"""
参数：
msg:Msg：一条消息
生成：msg：Msg，这条输入消息。
"""5、bluesky.preprocessors.make_decorator
# 把一个生成器实例wrapper变成一个生成器函数装饰器。
# 这个名为_wrapper的函数接收一个生成器实例并且返回一个转变的生成器实例。
bluesky.preprocessors.make_decorator(wrapper)
"""
一个'wrapper'的示例:
>>> plan = count([det]) # 返回一个生成器实例
>>> revised_plan = some_wrapper(plan) # 返回一个新实例.
装饰器的示例:
>>> some_decorator = make_decorator(some_wrapper) # 返回装饰器
>>> customized_count = some_decorator(count) # 返回一个生成器函数.
>>> plan = customized_count([det]) # 返回一个生成器实例
这转变一个'wrapper'为一个装饰器,它接收一个生成器函数并且返回一个生成器函数.
"""