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
OptionDefinitionfor 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,defaultandlocationfields:the default for
domainistoolsthe default for
defaultis 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.locationisconfig, step, recipeand cannot be changed.
Other differences compared to
OptionDefinition:multiplemust be False (setting it to True will throw aValueError),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
docif 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:
- 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:
providers (
Providers) – Bundles and current task used for option lookup.subdomains (
Mapping[Literal['step','recipe','config','product'],str|Sequence[str|None] |None] |bool|None) – Subdomain policy passed toresolve.paths (
Iterable[str|PathLike] |None) – Registry paths searched before the defaults.include_default_paths (
bool) – IncludeTOOLREGISTRYpaths, or the standard paths when that environment variable is unset. See Registry location.
- Return type:
- 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.
- 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 withmultiple=True. Withmultiple=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 totypeat construction. Formultiple=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.
- 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
OptionNameDomainpassed asname.
- enable: bool = True¶
Whether the definition is enabled. Direct resolution raises
ValueErrorwhenFalse.
- property fullname: OptionNameDomain¶
Full name, including domain
- location: str | Sequence[str] | None = None¶
Provider search order:
step,recipe,config, orproduct. Accepts a comma-separated string or a sequence, stored as a tuple.Noneis 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
OptionNameDomaincontaining its domain.
- required: bool = False¶
Raise
ValueErrorwhen no value is found, even if a default is set.
- class momotor.options.domain.tools.ToolOptionName(name, domain='tools')¶
Option name with
toolsas its default domain.