Task ids

A task id combines a step id with optional zero-based task numbers. For example, build.0.1 identifies task (0, 1) of step build. A step without separate tasks has the id build and task number None.

Task counts and task numbers are different. Counts (2, 3) produce six task numbers, from (0, 0) through (1, 2). The Scheduler tasks option reference describes how bundles declare these counts.

Result queries use $0, $1, and $@ to refer to the current task numbers. Text labels use task id placeholders such as $#. These are separate syntaxes.

Methods to handle task id’s

class momotor.options.task_id.StepTaskId(step_id, task_number)

Immutable step id and optional zero-based task numbers.

StepTaskId('build', (0, 1)) formats as build.0.1. A task number of None identifies a step without separate tasks.

Parameters:
  • step_id (str) – Recipe step id.

  • task_number (Sequence[int] | None) – Task numbers, or None.

step_id: str
task_number: Sequence[int] | None
momotor.options.task_id.apply_task_number(depend_id, task_id)

Replace $ references in dependency strings with their value from the task_id parameter, e.g. $0 in depend_id will be replaced with task_id.task_number[0]

Parameters:
  • depend_id (str) – the dependency string

  • task_id (StepTaskId) – the task id to use for the replacement

Return type:

str

Returns:

the dependency string with the references replaced

Simple arithmetic on the values can be done, available operators are +, -, *, / and %, for the usual operations add, subtract, multiply, integer division and modulo. Arithmetic operations are evaluated from left to right, there is no operator precedence.

When subtraction results in a negative value or division in infinity, this will not directly throw an exception, but instead will generate an invalid task-id containing #NEG or #INF.

Special value $@ will be replaced with the full task number. To include a literal $ use \$. To prevent a character between two $ placeholders from being interpreted as an arithmetic operation, use a backslash before the character. See the examples below.

Raises InvalidDependencies if depend_id contains invalid references or is syntactically incorrect.

Examples:

>>> tid = StepTaskId('step', (4, 5, 6))
>>> apply_task_number('test', tid)
'test'

Basic usage

>>> apply_task_number('test.$0', tid)
'test.4'
>>> apply_task_number('test-$0.$1', tid)
'test-4.5'
>>> apply_task_number('test$1_$2', tid)
'test5_6'

Arithmetic

>>> apply_task_number('test.$0-5.$1-5.$2-5', tid)
'test.#NEG.0.1'
>>> apply_task_number('test.$0+1.$1+1.$2+1', tid)
'test.5.6.7'
>>> apply_task_number('test.$0*2.$1*2.$2*2', tid)
'test.8.10.12'
>>> apply_task_number('test.$0/2.$1/2.$2/2', tid)
'test.2.2.3'
>>> apply_task_number('test.$0%2.$1%2.$2%2', tid)
'test.0.1.0'
>>> apply_task_number('test.$0*2+1.$1*2+1.$2*2+1', tid)
'test.9.11.13'
>>> apply_task_number('test.$0+1*2.$1+1*2.$2+1*2', tid)
'test.10.12.14'
>>> apply_task_number('test.$0+$1+$2', tid)
'test.15'
>>> apply_task_number('test.$1/0', tid)
'test.#INF'

The $@ placeholder

>>> apply_task_number('test.$@', tid)
'test.4.5.6'
>>> apply_task_number('test-$@tail', tid)
'test-4.5.6tail'
>>> apply_task_number('test-$@-tail', tid)
'test-4.5.6-tail'
>>> apply_task_number('[email protected]', tid)
'test-4.5.6.tail'
>>> apply_task_number('test-$@999', tid)
'test-4.5.6999'

Escaping $ and operators

>>> apply_task_number('test-\\$0', tid)
'test-$0'
>>> apply_task_number('test.$0\\-$1', tid)
'test.4-5'

Invalid references

>>> apply_task_number('test.$9', tid)
Traceback (most recent call last):
...
momotor.options.exception.InvalidDependencies: Task 'step.4.5.6' has invalid dependency 'test.$9'

Other special cases

>>> apply_task_number('test-$X', tid)
'test-$X'
>>> apply_task_number('test.$1$2', tid)
'test.56'
>>> apply_task_number('test.$1^4', tid)
'test.5^4'
>>> apply_task_number('test.$0text.$1', tid)
'test.4text.5'
>>> apply_task_number('test.$0.text.$1', tid)
'test.4.text.5'
>>> apply_task_number('test.$0.999.$1', tid)
'test.4.999.5'
momotor.options.task_id.get_task_id_lookup(task_ids)

Convert an iterable of StepTaskId objects into a lookup table to convert a string representation of a task-id to the StepTaskId

>>> get_task_id_lookup({StepTaskId('step', (0, 0))})
{'step.0.0': StepTaskId(step_id='step', task_number=(0, 0))}
Parameters:

task_ids (Iterable[StepTaskId]) – the task ids to convert

Return type:

dict[str, StepTaskId]

Returns:

the lookup table

momotor.options.task_id.iter_task_ids(step_id, sub_tasks)

Generate all the task-ids for the subtasks.

>>> list(str(t) for t in iter_task_ids('step', None))
['step']
>>> list(str(t) for t in iter_task_ids('step', tuple()))
['step']
>>> list(str(t) for t in iter_task_ids('step', (2,)))
['step.0', 'step.1']
>>> list(str(t) for t in iter_task_ids('step', (2, 2)))
['step.0.0', 'step.0.1', 'step.1.0', 'step.1.1']
Parameters:
  • step_id (str) – the id of the step

  • sub_tasks (Sequence[int] | None) – sequence of integers with the number of sub-tasks for each level

Return type:

Generator[StepTaskId, None, None]

Returns:

Step and task id objects in task-number order.

momotor.options.task_id.iter_task_numbers(sub_tasks)

Generate all the task-numbers for the subtasks.

>>> list(iter_task_numbers(None))
[None]
>>> list(iter_task_numbers(tuple()))
[None]
>>> list(iter_task_numbers((1,)))
[(0,)]
>>> list(iter_task_numbers((3,)))
[(0,), (1,), (2,)]
>>> list(iter_task_numbers((2, 2)))
[(0, 0), (0, 1), (1, 0), (1, 1)]
>>> list(iter_task_numbers((2, 3)))
[(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)]
Parameters:

sub_tasks (Sequence[int] | None) – sequence of integers with the number of sub-tasks for each level

Return type:

Generator[Sequence[int] | None, None, None]

Returns:

the task numbers

momotor.options.task_id.task_id_from_number(task_number)

Convert a task number (tuple of ints) into a task id (dotted string)

Return type:

str

>>> task_id_from_number(None)
''
>>> task_id_from_number((1,))
'1'
>>> task_id_from_number((1, 2,))
'1.2'
>>> task_id_from_number((1, 2, 3,))
'1.2.3'
momotor.options.task_id.task_number_from_id(task_id)

Convert a task_id string into a task number

Return type:

Sequence[int] | None

>>> task_number_from_id('') is None
True
>>> task_number_from_id('1')
(1,)
>>> task_number_from_id('1.2')
(1, 2)
>>> task_number_from_id('1.2.3')
(1, 2, 3)