Tools domain

The tools domain contains options who’s name should be a tool name, and the value of the option should be a version requirement. 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 should use ToolOptionDefinition to define required tools in their options

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)

Resolve the value of this option by inspecting the options of the providers.

Sub-domains to look for can be specified for each provider. Options including a specified sub-domain take priority over options without the sub-domain.

If the subdomains option is not provided, a default is generated from the providers.task_id value if this is specified. To disable the default subdomains, set subdomains to False

Parameters:

  • providers (Providers) – The providers

  • subdomains (Mapping[Literal['step', 'recipe', 'config', 'product'], str | Sequence[str | None] | None] | bool | None) – For each provider, a sequence of subdomains to take into account when looking for options. Merged with domain. Missing values and empty sequences are interpreted as containing None. If not set or True, generates subdomains based on providers.task_id. Set to False to disable generation of subdomains.

Return type:

Iterable[ToolName]

Returns:

The resolved option value. A tuple of values if multiple is True.

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

Resolve a tool option into a single Tool using the tool registry. If multiple options are provided, the first existing tool will be returned. If none of the requested tools exist, raises FileNotFoundError

If include_default_paths is True (default), this reads the tool registry from .toolregistry.d in the current user’s home directory and /etc/toolregistry.d. If paths is provided, registry will be read from all paths in the path list as well.

providers and subdomain arguments are the same as for resolve(), and paths and include_default_paths arguments are the same as for resolve_tool()

Parameters:
Return type:

Tool | None

Returns:

the tool

NO_DEFAULT: typing.ClassVar[object] = <object object>

Sentinel indicating there is no default

all: bool = False

When multiple is True, resolve() will match the first provider in location that defines an option with the correct name and domain. Set all to True to resolve all matching options of all providers listed in location. Has no effect when multiple is False.

default: typing.Any = <object object>

The default value if the option is not provided by any provider.

deprecated: str | None = None

If this option is deprecated, set to the reason for deprecation. Should describe which option(s) - if any - replace this option

doc: str | None = None

Documentation of the option

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 have a subdomain. Required (but can be provided through the name argument)

enable: bool = True

If False this OptionDefinition will be disabled (i.e. ignored as if it was not listed)

property fullname: OptionNameDomain

Full name, including domain

location: str | collections.abc.Sequence[str] | None = None

The names and order of the providers resolve() looks for the options. Can be provided as a comma separated string, or as a sequence of strings. Required. CheckletBaseMeta provides the default. When accessing, will always be a sequence

multiple: bool = False

This option can be provided multiple times. If True, resolve() will return a FilterableTuple of matched options. If False, resolve() will return a single value, or throw a ValueError if multiple options match. Default: False

name: OptionNameDomain | str

Name of the option. Required

required: bool = False

This option is required. If the option is not defined by any of the providers, resolve() will throw a ValueError exception: Default: False

property shortname: str

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

type: OptionTypeLiteral | None = 'str'

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')
classmethod from_qualified_name(name)

Create an OptionNameDomain from a qualified name (i.e. including the domain). If name does not include a domain, the default domain is used.

Return type:

Self

qualified_name()

Return the fully qualified option name (i.e. including the domain)

Return type:

str

short_name()

Return the short name of the option (i.e. without the domain if it is the default domain)

Return type:

str

domain: str = 'tools'

The domain of the option

name: str

The name of the option