Option definitions

An OptionDefinition describes how to read one option name and domain from a set of Providers. It does not store the option value itself. See Resolve your first option for a runnable example.

Lookup order

location controls provider order. For example, ('config', 'step', 'recipe') gives config options priority over step options, then recipe options. Unavailable providers are skipped.

Task-specific subdomains take priority over unqualified domains across all providers. With task id build.1.2 and domain checklet, the generated recipe and config search domains are:

  • checklet#build.1.2

  • checklet#build.1

  • checklet#build

  • checklet

Resolution searches named subdomains in provider order before searching any unqualified domain. A recipe option in checklet#build can therefore take priority over a config option in checklet.

resolve(..., subdomains=False) disables subdomain lookup. An explicit mapping can control subdomains per provider. For example, {'config': ('build', None)} allows both checklet#build and the unqualified checklet domain for config. Without None or an empty string, a nonempty list of named subdomains excludes the unqualified domain for that provider.

Values and missing options

With all=False, resolution stops at the first provider and domain that contains the option. Options without content contribute no values. With all=True, resolution collects values from every matching provider and domain. multiple controls the return shape:

Condition

multiple=False

multiple=True

Values found

First value

Tuple of values

No value, default set

Default value

One-item tuple containing the default

No value or default

None

()

No value and required=True

ValueError, even with a default

ValueError, even with a default

A definition with type=None keeps the value type supplied by the bundle. An explicit type converts supplied values and the default. String values retain reference placeholders until the caller expands them with replace_placeholders().

API reference

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

Define how to find, convert, and document a bundle option.

The definition is immutable. resolve() reads values from the providers in location order. Both domain and location must be set before resolution. A plain string name does not supply a default domain. An OptionNameDomain supplies both the name and the domain.

Raises:

TypeError – If the type is unknown, the domain contains a subdomain, or a required option is deprecated.

resolve(providers, subdomains=None)

Find and convert option values from the available providers.

Search all requested subdomains before any unqualified domain, using location order within each pass. For each provider, search subdomains in the supplied order. Missing providers are skipped.

By default, providers.task_id supplies subdomains for recipe and config options. Task build.1.2 gives build.1.2, build.1, build, then the unqualified domain. No task id means no generated subdomains.

Options without content are skipped. This method does not expand reference placeholders in string values.

Parameters:
  • providers (Providers) – Bundles and current task used for lookup.

  • subdomains (Mapping[Literal['step', 'recipe', 'config', 'product'], str | Sequence[str | None] | None] | bool | None) – Provider-to-subdomain mapping, or a boolean. True requires a task id and generates subdomains. False uses only unqualified domains. None generates subdomains when a task id is available. In a mapping, None or '' allows fallback to the unqualified domain. Missing mapping keys and empty sequences also allow that fallback. A sequence of only named subdomains does not.

Return type:

Any

Returns:

The first value, or a tuple when multiple=True. Without a match or default, return None or () respectively.

Raises:
  • ValueError – If disabled, missing a domain or location, missing a required value, or unable to generate requested subdomains. Invalid value conversions can also raise this exception.

  • TypeError – If a value cannot be converted to the requested 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 = None

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.OptionNameDomain(name, domain='checklet')

Immutable option name and domain, with checklet as the default domain.

Parameters:
  • name (str) – Option name without a domain suffix.

  • domain (str) – Domain name.

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 = 'checklet'

The domain of the option

name: str

The name of the option