Reference and placeholder parsers¶

references¶

class momotor.options.parser.reference.Reference(provider, id, name, _source)¶

A reference

id: str | None¶: The id of the reference

name: str | None¶: The name of the reference, including the class or domain parts

provider: str | None¶: The provider of the references

class momotor.options.parser.reference.ReferenceMatch(provider, values)¶

A reference match

provider: Union[RecipeBundle, ConfigBundle, ProductBundle, Step, Result]¶: The provider containing the elements referenced

values: tuple[Union[Property, File, Option, Result], ...]¶: A tuple with the referenced elements

momotor.options.parser.reference.generate_reference(type_, refs, bundles)¶

A generator producing reference matches.

Each ReferenceMatch object generated is a single reference resolved.

Parameters:

type – The reference type
refs (Sequence[Reference]) – The reference options
bundles (Providers) – The bundles to resolve the references too

Return type:

Generator[ReferenceMatch, None, None]

momotor.options.parser.reference.parse_reference(reference)¶

Parse a reference into its parts.

Parameters:: reference (str) – the reference to parse
Return type:: tuple[str, tuple[Reference, ...], str]
Returns:: a 3-tuple containing the type, a tuple of Reference objects, and a string with the rest of the reference string remaining after parsing.
Raises:: ValueError – the reference cannot be parsed

Examples:

>>> parse_reference("type")
('type', (Reference(provider=None, id=None, name=None, _source=''),), '')

>>> parse_reference("type rest")
('type', (Reference(provider=None, id=None, name=None, _source=''),), ' rest')

>>> parse_reference("type[] rest")
('type', (Reference(provider=None, id=None, name=None, _source=''),), ' rest')

>>> parse_reference("type[@provider] rest")
('type', (Reference(provider='provider', id=None, name=None, _source='@provider'),), ' rest')

>>> parse_reference("type[@provider#id:class#name] rest")
('type', (Reference(provider='provider', id='id', name='class#name', _source='@provider#id:class#name'),), ' rest')

>>> parse_reference("type[@provider#id,id2:class#name] rest")
('type', (Reference(provider='provider', id='id,id2', name='class#name', _source='@provider#id,id2:class#name'),), ' rest')

>>> parse_reference("type[#wildcard.*:class] rest")
('type', (Reference(provider=None, id='wildcard.*', name='class', _source='#wildcard.*:class'),), ' rest')

momotor.options.parser.reference.resolve_reference_value(value_reference, bundles, *, default_mod='join')¶

Resolve a reference value string into the value

Parameters:

value_reference (str) – The value_reference
bundles (Providers) – The bundles to resolve the references to
default_mod (str) – The default mod

Return type:

tuple[str | int | float | bool | None, str]

Returns:

The resolved value

momotor.options.parser.reference.select_by_file_reference(reference, bundles)¶

Parse a file reference string and collect the referenced files.

This is similar to the file[...] reference syntax, but does not require the file nor the square brackets.

Parameters:

reference (str) – The reference to parse
bundles (Providers) – The bundles to resolve the references to

Return type:

tuple[tuple[ReferenceMatch, ...], str]

Returns:

a 2-tuple containing a tuple of ReferenceMatch objects, and a string with the rest of the reference string remaining after parsing.

momotor.options.parser.reference.select_by_opt_reference(reference, bundles)¶

Parse an option reference string and collect the referenced options.

This is similar to the opt[...] reference syntax, but does not require the opt nor the square brackets.

Parameters:

reference (str)
bundles (Providers) – The bundles to resolve the references to

Return type:

tuple[tuple[ReferenceMatch, ...], str]

Returns:

a 2-tuple containing a tuple of ReferenceMatch objects, and a string with the rest of the reference string remaining after parsing.

momotor.options.parser.reference.select_by_prop_reference(reference, results=None, task_id=None)¶

Parse a property reference string and collect the referenced properties.

This is similar to the prop[...] reference syntax, but does not require the prop nor the square brackets.

Parameters:

reference (str) – The reference to parse
results (ResultsBundle) – The results bundle containing the properties
task_id (StepTaskId) – The task id to expand task references

Return type:

tuple[tuple[ReferenceMatch, ...], str]

Returns:

a 2-tuple containing a tuple of ReferenceMatch objects, and a string with the rest of the reference string remaining after parsing.

momotor.options.parser.reference.select_by_reference(reference, bundles)¶

Parse a reference string and collect the referenced items

Parameters:

reference (str) – The reference string to parse
bundles (Providers) – The providers providing the objects that are referenced

Return type:

tuple[str | None, tuple[ReferenceMatch, ...], str]

Returns:

a 3-tuple containing the type, a tuple of ReferenceMatch objects, and a string with the rest of the reference string remaining after parsing.

Raises:

ValueError – the reference cannot be parsed

selectors¶

momotor.options.parser.selector.filter_by_selector(selector, bundles)¶

Filter the elements selected by selector from the bundles

Parameters:

selector (str) – the selector to parse
bundles (Providers) – The bundles to resolve the references to

Return type:

tuple[tuple[Element, ...], str]

Returns:

a 2-tuple containing a tuple with the selected elements, and a string with the rest of the selector string remaining after parsing.

Raises:

ValueError – if the selector is not valid

momotor.options.parser.selector.match_by_selector(selector, bundles, *, default_mod='all')¶

Match the elements selected by match selector from the bundles

Parameters:

selector (str) – the match selector to parse
bundles (Providers) – The bundles to resolve the references to
default_mod (str) – Default ‘mod’

Return type:

tuple[bool, str]

Returns:

a 2-tuple containing a boolean indicating if there was a match, and a string with the rest of the selector string remaining after parsing.

Raises:

ValueError – if the selector is not valid

momotor.options.parser.selector.parse_selector(selector)¶

Parse a selector into its parts.

Parameters:: selector (str) – the selector to parse
Return type:: tuple[str, tuple[Reference, ...], str | None, str | int | float | None, str]
Returns:: a 5-tuple containing the type, a tuple of Reference objects, the operator, the value, and a string with the rest of the selector string remaining after parsing.
Raises:: ValueError – the selector cannot be parsed

Examples:

>>> parse_selector('pass')
('pass', (Reference(provider=None, id=None, name=None, _source=''),), None, None, '')

>>> parse_selector('prop[#id:name]!')
('prop', (Reference(provider=None, id='id', name='name', _source='#id:name'),), '!', None, '')

>>> parse_selector('prop[:test]?')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '?', None, '')

>>> parse_selector('prop[:test]?123')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '?', None, '123')

>>> parse_selector('prop[:test]>0')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', 0, '')

>>> parse_selector('prop[:test]>1_000')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', 1000, '')

>>> parse_selector('prop[:test]>1.5')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', 1.5, '')

>>> parse_selector('prop[:test]>-2')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', -2, '')

>>> parse_selector('prop[:test]>-2e2')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', -200.0, '')

>>> parse_selector('prop[:test]>2e-2')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', 0.02, '')

>>> parse_selector('prop[:test]=="test string"')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '==', 'test string', '')

>>> parse_selector('prop[:test]>0 123')
('prop', (Reference(provider=None, id=None, name='test', _source=':test'),), '>', 0, ' 123')

Returns:

momotor.options.parser.selector.resolve_selector(selector, bundles)¶

Resolve all parts of a selector

Parameters:

selector (str) – the selector to parse
bundles (Providers) – The bundles to resolve the references to

Return type:

tuple[str, Iterable[ReferenceMatch], Callable[[Any, Any], bool], str | int | float | None, str]

Returns:

A 5-tuple containing the attribute to get the reference value from (based on type), an iterator for ReferenceMatch objects, the operator, the value, and a string with the rest of the selector string remaining after parsing.

Raises:

ValueError – if the selector is not valid

reference placeholders¶

momotor.options.parser.placeholders.replace_placeholders(value, bundles, *, value_processor=None, mod='join')¶

Replace all placeholders in value with their resolved values. Placeholders are resolved recursively, i.e. if a resolved value contains more placeholders, these will be resolved as well.

Parameters:

value (TypeVar(VT)) – the string containing placeholders to resolve. If value is not a string, no processing is done and value is returned unmodified.
bundles (Providers) – the bundles to resolve the references to
value_processor (Callable[[str | None], str]) – a callable that is called with every resolved value, can be used to modify placeholders. If not supplied, uses str to cast the returned value to a string.
mod (str) – the modifier to apply to the resolved values. Defaults to 'join'.

Return type:

TypeVar(VT)

Returns:

the value with all placeholders resolved

task id placeholders¶

momotor.options.parser.tasks.replace_task_placeholder(text, task_id)¶

Replace the task id placeholders in a string.

Replaces the $#, $0#, and $1# placeholders in a string with the sub-task number. $# and $0# are replaced with the zero-based task number, $1# is replaced with the one-based task number.

If the task id is None, or has no sub-tasks, the placeholders are replaced with -.

>>> replace_task_placeholder('Text $#', StepTaskId('task', (0, 1)))
'Text 0.1'

>>> replace_task_placeholder('Text $0#', StepTaskId('task', (0, 1)))
'Text 0.1'

>>> replace_task_placeholder('Text $1#', StepTaskId('task', (0, 1)))
'Text 1.2'

>>> replace_task_placeholder('Text $#', StepTaskId('task', None))
'Text -'

>>> replace_task_placeholder('Text $#', None)
'Text -'

Parameters:

text (str | None) – the string to replace the placeholders in
task_id (StepTaskId | None) – the task id to use

Return type:

str | None

Returns:

the string with the placeholders replaced