Result query

A result query references one or more results in a results bundle. Each result has an id, consisting of the id of the step that generated that result, and optionally one or more task number for steps with multiple tasks. The id and task numbers are separated with a dot (.)

For example, the following result ids are valid: step1, step.1, step.1.2.3.4.5

Result queries allows selection of these result ids using wildcards and with a replacement for some of the task numbers based on another task number.

The syntax for a result query is

queries        ::=  query ( "," query )*
query          ::=  step-id [ task_query ] | [ step-id ] "*" [ task_query ] | [ step-id ] "**"
task_query     ::=  ( "." task_number )* | ".$@"
task_number    ::=  integer | task_wildcard | task_reference
task_wildcard  ::=  "*" | "?"
task_reference ::=  "$" integer [ oper integer ]
oper           ::=  "+" | "-" | "*" | "/" | "%"

Where step-id is a (XML) id without periods (.), and integer is a positive natural number (including zero).

The most simple result queries are just the result id and will match that single result id:

result query
step1	Matches exactly one result, with id step1
step.1	Matches exactly one result, with id step.1
step.1.2.3.4.5	Matches exactly one result, with id step.1.2.3.4.5

Multiple queries are possible by separating them with a comma (,)

result query
step1,step.1	Matches exactly two results: step1 and step.1

A * is a wildcard character that matches one or more elements and is allowed in both the step-id and task-number sections. In the step-id, the * wildcard does not have to be used only at the end:

result query
st*p	Matches step, stap, steeeeeep, etc.
step*	Matches any step whose id starts with step, but without task number
step.*	Matches any step whose id equals step followed by a task number, e.g. step.1 and step.1.2.3.4.5 match, but step does not
step*.*	Combination of the above two: matches step.1, stepxyz.2, but not step
step**	Matches any step whose id starts with step, with or without any task number

The task-number section can also contain a ? wildcard, which will match exactly one element:

result query
step.?	Matches step.1, but not step or step.1.2.3.4.5
step.1.?	Matches step.1.1, step.1.42 but not step, step.1 or step.1.2.3.4.5
step.?.1	Matches step.1.1, step.42.1 but not step, step.1 or step.1.2.3.4.5

It is also possible to reference a specific task number based on a current task number. For example, when executing task step.2.3 it would be useful to reference another based on the current task number 2.3. This is done using a $ reference. Where $0 references the first task number element (2 in this example), $1 references the second element (3), etc.

The following examples all use current task number 2.3:

result query
task.$0	References result id task.2
task.$1	References result id task.3
task.$0.$1	References result id task.2.3
task.$1.$0	References result id task.3.2
task.$@	Special “shortcut” to replace the full task number, here task.2.3

Simple arithmetic is possible on the task number references. Available operations are + (addition), - (subtraction), * (multiplication), / (integer floor division) and % (modulo). The right-hand side of the operator has to be an integer, it cannot be another reference.

result query
task.$0-1	References result id task.1
task.$0+1	References result id task.3
task.$0*2	References result id task.4
task.$0/2.$1/2	References result id task.1.1
task.$0%2.$1%2	References result id task.0.1

If a subtraction results in a negative number the value is replaced with #NEG, and if a division results in a division by zero the value is replaced with #INF. Both of these result in invalid result id.

result query
task.$0-3	References result id task.#NEG
task.$0/0	References result id task.#INF

Methods for querying and filtering results

momotor.options.result_query.filter_result_query(results, query, task_id=None)

Filter an iterable of Result objects on a result query

Returns an iterator that iterates all the Result objects from results that match the query

Parameters

• results (Iterable[Result]) – an iterable with the results to query

• query (str) – the query to filter the results on

• task_id (Optional[StepTaskId]) – a task id to resolve id references in the query

Return type

Iterator[Result]

Returns

results filtered on the query

momotor.options.result_query.make_result_id_re(query)

Make a regex that matches a result query to the query.

Uses a glob-like pattern matching on the dot-separated elements of the selector. For the first element (the step-id part), a * will match zero or more characters except . For all the other elements (the task number parts), a * matches one or more elements starting at that position and a ? matches a single element in that position.

Special query ** matches all step-ids and task-numbers, i.e. it produces a regex that matches anything.

This method does not apply any task numbers, apply apply_task_number() to the selector before calling this function for that if needed.

Examples:

>>> make_result_id_re('test').match('test') is not None
True

>>> make_result_id_re('test').match('test.1') is not None
False

>>> make_result_id_re('test').match('testing') is not None
False

>>> make_result_id_re('test.1').match('test.2') is not None
False

>>> make_result_id_re('test.2').match('test.2.3') is not None
False

>>> make_result_id_re('test.2.3').match('test.2.3') is not None
True

>>> make_result_id_re('test.?').match('test.2.3') is not None
False

>>> make_result_id_re('test.?.?').match('test.2.3') is not None
True

>>> make_result_id_re('test.?.?.?').match('test.2.3') is not None
False

>>> make_result_id_re('test.*').match('test.2.3') is not None
True

>>> make_result_id_re('test.?.*').match('test.2.3') is not None
True

>>> make_result_id_re('test.?.?.*').match('test.2.3') is not None
False

>>> make_result_id_re('*').match('test') is not None
True

>>> make_result_id_re('*').match('test.2.3') is not None
False

>>> make_result_id_re('*.*').match('test.2.3') is not None
True

>>> make_result_id_re('test*').match('testing') is not None
True

>>> make_result_id_re('*sti*').match('testing') is not None
True

>>> make_result_id_re('*sting').match('testing') is not None
True

>>> make_result_id_re('te*ng').match('testing') is not None
True

>>> make_result_id_re('test*').match('tasting') is not None
False

>>> make_result_id_re('test*').match('testing.1') is not None
False

>>> make_result_id_re('test**').match('testing.1') is not None
True

>>> make_result_id_re('t*t**').match('testing.1') is not None
True

>>> make_result_id_re('t*x**').match('testing.1') is not None
False

>>> make_result_id_re('test*.*').match('testing.1') is not None
True

>>> make_result_id_re('**').match('testing') is not None
True

>>> make_result_id_re('**').match('testing.1') is not None
True

Parameters

query (str) – the result-id query to convert

Return type

Pattern

Returns

a compiled regular expression (a re.compile() object) for the query

momotor.options.result_query.result_query_fn(query, task_id=None)

Make a function to match a result with a result query.

The query is either a literal id (e.g. step, step.1 etc), or a glob-like query to select multiple id’s, (e.g. *, step.*, step.?). Also applies task numbers if task_id is provided.

Multiple queries are possible, separated with a comma.

Parameters

• query (str) – the query to convert

• task_id (Optional[StepTaskId]) – a task id to resolve id references in the query

Return type

Callable[[Result], bool]

Returns

a callable that takes a Result and returns a boolean indicating if that result matches the query