Self describing plans

[ksunden]

Motivation

• automatic UI generation
• especially useful for queueserver (requires serialization)
• type checking (impossible to do strongly, but some benefit can be had)

Specific challenges

• variadic arguments (mypy static checking does not support)
• Duck typed arguments (yay protocols)
• Want for additional info like ranges [1], step (for ui hinting), units?---not in built-in plans
• serializability

Prior art

• bluesky_queueserver annotation decorator
• cjtitus plan decorator (?)

Proposed implementation

• Use python native type hinting as much as possible
• hint variadics as custom type (child of Union, so type checking mostly works, but not precisely... variadic args must be homogenous to type hints)
• use hardware protocols
• in many cases arguments are numpy.typing.ArrayLike ---these get passed into numpy linspace, clients MAY only support the simpler float scalar option.
• function get_plan_schema(plan) -> JSON

[1] https://docs.python.org/3/library/typing.html#typing.Annotated

[ksunden]

Specific conversation about queueserver annotation decorator, which is the closest prior art:

• Mostly solves a number of the goals, but does so in a way that involves a fair amount of repetition

• Description (including description of arguments) is best represented in the docstring, we can specify numpydoc style to parse out descriptions of each parameter such that they can be displayed/used separately.

• Does not address variadic arguments common to at least the built in bluesky plans

• Defining type/ranges I feel are better integrated as type hints

• does some enum magics to represent "all devices", "all movables", "all flyers", etc...

  • These are better represented by the protocol class for type hinting purposes
  • limiting to a subset other than "conforms to xyz protocol" could be done with a different type hint, haven't thought through specifics, but even if it were a custom type, would be doable.

• default values and types are naturally part of the signature of a plan, no need to re-encode them. (if overriding is something you wish to do, functools.partial is there for you)

[untzag]

related idea sparked by this proposal: https://github.com/bluesky/bluesky/issues/1491