Tools domain

The tools domain maps a requirement name to one or more acceptable registry names. A registry name can include a version and variant. For example:

<option domain="tools" name="python" value="python/3.9" />

The option name and first part of the value should normally be the same, unless there is a very specific reason for the checklet to require multiple versions of the same tool:

<option domain="tools" name="python-legacy" value="python/2" />
<option domain="tools" name="python" value="python/3.9" />

Checklets declare these options with ToolOptionDefinition in their option metadata. Lookup uses config, step, then recipe options, with task subdomains handled by resolve().

A value can list alternatives separated by spaces or commas. ToolOptionDefinition.resolve_tool tries them in their listed order and returns the first available tool. Without an option value, the requirement name selects the registry’s default version.

The scheduler reads the requirement names from tools@scheduler. It stores each requirement’s alternatives as a set, so that scheduler mapping does not preserve preference order. Alternatives for one requirement normally share a base tool name, such as python/3.13 python/3.12.

If alternatives have different base names, the scheduler keeps those whose base name equals the requirement name and emits UserWarning. If none match, it raises InvalidToolRequirements. A requirement can use an alias such as python-legacy when all its alternatives share the same base name, such as python.

Added in version 2.1.3: Validation of alternatives with different base names, and the InvalidToolRequirements exception.

class momotor.options.domain.tools.ToolOptionDefinition(name, type=None, doc=None, required=False, multiple=False, all=False, location=None, domain=None, default=<object object>, enable=True, deprecated=None)

A specialization of OptionDefinition for tool dependency definitions.

The option value can be a space or comma separated list of version requirements to indicate alternative version preferences of a single tool (in order of most to least preferred).

Provides appropriate defaults for domain, default and location fields:

  • the default for domain is tools

  • the default for default is the option name, i.e. if no option for the given name is in any bundle, the default version as defined in the registry will be used.

  • location is config, step, recipe and cannot be changed.

Other differences compared to OptionDefinition:

  • multiple must be False (setting it to True will throw a ValueError),

  • resolve() returns an iterable of ToolName objects,

  • additional method resolve_tool() resolves the tool using the tool registry, it resolves to a single tool, matching the most preferred tool available.

  • auto-generates suitable doc if none is provided

resolve(providers, subdomains=None)

Yield tool names in the order listed in the resolved option value.

Reference placeholders are expanded before splitting on spaces and commas. This method does not inspect the tool registry or check tool availability.

Parameters:
Return type:

Iterable[ToolName]

Returns:

An iterator of tool names, in preference order.

Raises:
  • FileNotFoundError – If the resolved option value is None.

  • TypeError – If the option value is neither a string nor bytes.

  • ValueError – If option lookup or placeholder expansion fails.

resolve_tool(providers, subdomains=None, *, paths=None, include_default_paths=True)

Return the first available tool from the option’s ordered alternatives.

Parameters:
Return type:

Tool | None

Returns:

The resolved Tool.

Raises:
  • FileNotFoundError – If none of the requested tools is available.

  • ValueError – If option lookup or placeholder expansion fails.

  • TypeError – If the option value has an unsupported type.

NO_DEFAULT: ClassVar[object] = <object object>

Sentinel indicating there is no default

all: bool = False

Collect values from every matching provider and domain when True. Otherwise stop at the first provider and domain containing the option. Usually paired with multiple=True. With multiple=False, resolution still converts all collected values but returns only the first.

default: Any = <object object>

Value used when no value is found and required=False. Converted to type at construction. For multiple=True, returned as a one-item tuple.

deprecated: str | None = None

Deprecation message, including a replacement when available. Resolving a supplied value logs the message and emits DeprecationWarning.

doc: str | None = None

reStructuredText description used by the Sphinx option documenter.

domain: str | None = None

The domain of the option: Momotor defines the following values for domain:

  • checklet: (Default) Options defined and used by checklets.

  • scheduler: Options used by the Momotor Broker for executing and scheduling the step.

  • tools: Options used by the Momotor Broker to declare tools used by the checklet.

  • x-…: “Experimental”, or private use domains

Domain names starting with x- can be used for private use cases. All other domain names are reserved for use by Momotor in the future.

Cannot contain a subdomain. Required for resolution, either explicitly or through an OptionNameDomain passed as name.

enable: bool = True

Whether the definition is enabled. Direct resolution raises ValueError when False.

property fullname: OptionNameDomain

Full name, including domain

location: str | Sequence[str] | None = None

Provider search order: step, recipe, config, or product. Accepts a comma-separated string or a sequence, stored as a tuple. None is allowed at construction but prevents direct resolution. Checklet metadata can supply this field before resolution.

multiple: bool = False

Return a tuple of values when True. Otherwise return the first value. Multiple matching options do not cause an error.

name: OptionNameDomain | str

Plain option name, or an OptionNameDomain containing its domain.

required: bool = False

Raise ValueError when no value is found, even if a default is set.

property shortname: str

Commonly used option name. Only includes domain if it is not the default domain

type: Literal['string', 'boolean', 'integer', 'float'] | None = 'string'

Expected type of the option. Optional. If not set, the type as given by the <option> node is used as-is. Allowed values: string, integer, float and boolean

class momotor.options.domain.tools.ToolOptionName(name, domain='tools')

Option name with tools as its default domain.

classmethod from_qualified_name(name)

Split name@domain, or use checklet when the domain is omitted.

Parameters:

name (str) – Plain or qualified option name.

Return type:

Self

Returns:

The option name and domain.

qualified_name()

Return name@domain, including the checklet domain.

Return type:

str

short_name()

Return name for the checklet domain, otherwise name@domain.

Return type:

str

domain: str = 'tools'

The domain of the option

name: str

The name of the option