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.2checklet#build.1checklet#buildchecklet
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 |
|
|
|---|---|---|
Values found |
First value |
Tuple of values |
No value, default set |
Default value |
One-item tuple containing the default |
No value or default |
|
|
No value and |
|
|
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 inlocationorder. Bothdomainandlocationmust be set before resolution. A plain stringnamedoes not supply a default domain. AnOptionNameDomainsupplies 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
locationorder within each pass. For each provider, search subdomains in the supplied order. Missing providers are skipped.By default,
providers.task_idsupplies subdomains for recipe and config options. Taskbuild.1.2givesbuild.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.Truerequires a task id and generates subdomains.Falseuses only unqualified domains.Nonegenerates subdomains when a task id is available. In a mapping,Noneor''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:
- Returns:
The first value, or a tuple when
multiple=True. Without a match or default, returnNoneor()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.
- 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.OptionNameDomain(name, domain='checklet')¶
Immutable option name and domain, with
checkletas the default domain.