Base Checklet

exception mtrchk.org.momotor.base.checklet.CheckletError(status, report=None)

An erroneous Step result exception

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
report: str
status: str
exception mtrchk.org.momotor.base.checklet.CheckletException(status, report=None)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
report: str
status: str
class mtrchk.org.momotor.base.checklet.Checklet(recipe, product, config, results, task_id, work_dir=None)

A checklet is a class that implements a single step in a recipe.

Parameters:
apply_task_number(depend_id)

Applies momotor.options.task_id.apply_task_number() to the current task’s id.

Return type:

str

static collect_files(path, class_, pattern='**/*', *, name_prefix=None, executable_attribute=False)

Collect files in a directory (including files in subdirectories).

The return value can be used directly with CheckletResult files argument.

Parameters:

  • path (Path) – path to base directory with files to collect

  • class – the class of the files

  • pattern (str) – glob pattern to match. Defaults to **/*, meaning every file, recursively

  • name_prefix (PurePath)

  • executable_attribute – if file has X-bit set, set the executable attribute

Return type:

dict[NameClass, ResultFile]

Returns:

a dictionary with the collected files, with the key being a tuple of the name and class and the value being a ResultFile object.

content_refs(references)

Collect content from file, prop and option references.

Can contain reference placeholders, which will be expanded.

Parameters:

references (Iterable[str] | str) – A single string or list of strings with the references

Return type:

Generator[str, None, None]

Returns:

A generator yielding the content of the references

Raises:

CheckletError – if the reference is not a file, property or option reference

filter_by_selector(sel)

Convenience shortcut for momotor.options.parser.selector.filter_by_selector()

Return type:

tuple[tuple[Element, ...], str]

find_files(references)

Find files from various sources using file references.

references is a single string or list of strings with the file references. This is similar to the file[...] reference syntax, but does not require the file string nor the square brackets.

Examples:

  • @recipe:(<class>)(#name) Find files of class and/or name from the recipe

  • @step:(<class>)(#name) Find files of class and/or name from the current step

  • @config:(<class>)(#name) Find files of class and/or name from the config

  • @product:(<class>)(#name) Find files of class and/or name from the product

  • @result#<resultid>:(<class>)(#name) Find files of class and/or name produced by result with given id

If <class> and <name> are not supplied, finds all files.

References will be expanded using replace_placeholders(), thus (part of) the reference can be retrieved from properties of other steps: e.g. @config:${prop[#step-id:prop-name]}#filename will first retrieve property prop-name from step with id step-id.

If the step is unknown, or has no or an empty property with the given name, the reference is ignored.

Parameters:

references (Iterable[str] | str) – A single string or list of strings with the file references

Return type:

FilterableTuple[File]

Returns:

A list of files

classmethod get_checklet_options()

Get the checklet options

Return type:

CheckletOptions

get_option(name, domain=None)

Get an option definition by name

Parameters:

  • name (OptionNameDomain | str) – Name of the option to retrieve

  • domain (str | None) – Domain of the option to retrieve (only used if name is a string)

Return type:

OptionDefinition

Returns:

The option definition

get_step_workdir(*subdirs)

Create a working directory for the current step.

Parameters:

subdirs – The subdirectories to create

Return type:

Path

Returns:

The path to the directory

match_by_selector(sel)

Convenience shortcut for momotor.options.parser.selector.match_by_selector()

Return type:

tuple[bool, str]

merge_results(*results)

Merge multiple CheckletResult objects. How the result properties are merged is configured using the MERGED_PROPS_TYPE class variable.

Parameters:

results (CheckletResult) – The results to merge

Return type:

CheckletResult

Returns:

The merged result

replace_placeholders(value, *, value_processor=None)

Convenience shortcut for momotor.options.parser.placeholders.replace_placeholders()

Return type:

str | None

replace_task_placeholder(text)

Convenience shortcut for momotor.options.parser.tasks.replace_task_placeholder()

Return type:

str | None

resolve_option(name, domain=None, *, subdomains=None, replace_tasknumber=False, replace_placeholders=False, resolve_reference=False, encoding='utf-8', errors='replace')

Resolve an option by getting the value from one of the option providers as configured in the options meta

Parameters:

  • name (str | OptionNameDomain) – Name of the option to retrieve

  • domain (str | None) – Domain of the option to retrieve (only used if name is a string)

  • subdomains (SubDomainDefinitionType’ | 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.

  • replace_tasknumber (bool) – If True, replaces task id placeholders in the option value with the task number.

  • replace_placeholders (bool) – If True, replace reference placeholders in the option value. Cannot be combined with resolve_reference.

  • resolve_reference (bool) – If True, resolve the value as a reference to another option or a property. Cannot be combined with replace_placeholders.

  • encoding (str) – The encoding to use when option is bytes. Set to None to not decode bytes.

  • errors (str) – The error handling strategy for decoding bytes.

Raises:

CheckletError – if the option is not defined

Return type:

typing.Any

resolve_value_reference(ref)

Convenience shortcut for momotor.options.parser.reference.resolve_value_reference()

Return type:

tuple[str | int | float | bool | None, str]

result(result_id)

Get the result of a previous task

Parameters:

result_id (str | StepTaskId) – The id of the task, as a str or a StepTaskId object

Return type:

Result

Returns:

The result

result_query(query)

Get results of previous tasks, filtered on one or more id queries.

The query is either a literal id (e.g. step, step.1 etc.), or a glob-like query to select multiple id’s, (e.g. *, step.*, step.?). Also applies task numbers, so e.g. step.$@ will match the exact same task number as the current result’s task number.

Multiple queries separated with a comma are possible.

See make_result_id_re() for the documentation on the query syntax, see apply_task_number() for documentation of the task number replacements using $.

Return type:

Iterator[Result]

abstract run()

Must be implemented by subclasses.

Process the product bundle, with the recipe, and config bundles to create a result.

Return type:

ResultsBundle | CheckletResult

Returns:

The step result.

Returning a ResultsBundle is deprecated. All checklet mixins that define a decorator for run() expect it to return a CheckletResult.

Raises:

CheckletError – should be raised when an internal error prevents the checklet from completing.

select_by_file_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_file_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_opt_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_opt_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_prop_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_prop_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_reference()

Return type:

tuple[str | None, tuple[ReferenceMatch, ...], str]

MERGED_PROPS_TYPE: ClassVar[dict[str, tuple[type, Union[str, Callable]]]] = {'checklet-warning': (<class 'set'>, 'update')}

Properties that need special handling when merging using merge_results(). Default is using operator.add() which will work for strings and numeric values. Mapping from property name to a tuple containing the merged type, and a method for merging. The method for merging can be a function, or a method name for a method on the merged type.

property config: ConfigBundle | None

The provided config bundle

property product: ProductBundle

The provided product bundle

property recipe: RecipeBundle

The provided recipe bundle

property results: ResultsBundle

The provided results bundle, containing results of earlier steps

property step: Step

The current step

class mtrchk.org.momotor.base.checklet.CheckletBase

Base class for all momotor checklets

apply_task_number(depend_id)

Applies momotor.options.task_id.apply_task_number() to the current task’s id.

Return type:

str

static collect_files(path, class_, pattern='**/*', *, name_prefix=None, executable_attribute=False)

Collect files in a directory (including files in subdirectories).

The return value can be used directly with CheckletResult files argument.

Parameters:

  • path (Path) – path to base directory with files to collect

  • class – the class of the files

  • pattern (str) – glob pattern to match. Defaults to **/*, meaning every file, recursively

  • name_prefix (PurePath)

  • executable_attribute – if file has X-bit set, set the executable attribute

Return type:

dict[NameClass, ResultFile]

Returns:

a dictionary with the collected files, with the key being a tuple of the name and class and the value being a ResultFile object.

content_refs(references)

Collect content from file, prop and option references.

Can contain reference placeholders, which will be expanded.

Parameters:

references (Iterable[str] | str) – A single string or list of strings with the references

Return type:

Generator[str, None, None]

Returns:

A generator yielding the content of the references

Raises:

CheckletError – if the reference is not a file, property or option reference

filter_by_selector(sel)

Convenience shortcut for momotor.options.parser.selector.filter_by_selector()

Return type:

tuple[tuple[Element, ...], str]

find_files(references)

Find files from various sources using file references.

references is a single string or list of strings with the file references. This is similar to the file[...] reference syntax, but does not require the file string nor the square brackets.

Examples:

  • @recipe:(<class>)(#name) Find files of class and/or name from the recipe

  • @step:(<class>)(#name) Find files of class and/or name from the current step

  • @config:(<class>)(#name) Find files of class and/or name from the config

  • @product:(<class>)(#name) Find files of class and/or name from the product

  • @result#<resultid>:(<class>)(#name) Find files of class and/or name produced by result with given id

If <class> and <name> are not supplied, finds all files.

References will be expanded using replace_placeholders(), thus (part of) the reference can be retrieved from properties of other steps: e.g. @config:${prop[#step-id:prop-name]}#filename will first retrieve property prop-name from step with id step-id.

If the step is unknown, or has no or an empty property with the given name, the reference is ignored.

Parameters:

references (Iterable[str] | str) – A single string or list of strings with the file references

Return type:

FilterableTuple[File]

Returns:

A list of files

classmethod get_checklet_options()

Get the checklet options

Return type:

CheckletOptions

get_option(name, domain=None)

Get an option definition by name

Parameters:

  • name (OptionNameDomain | str) – Name of the option to retrieve

  • domain (str | None) – Domain of the option to retrieve (only used if name is a string)

Return type:

OptionDefinition

Returns:

The option definition

get_step_workdir(*subdirs)

Create a working directory for the current step.

Parameters:

subdirs – The subdirectories to create

Return type:

Path

Returns:

The path to the directory

match_by_selector(sel)

Convenience shortcut for momotor.options.parser.selector.match_by_selector()

Return type:

tuple[bool, str]

merge_results(*results)

Merge multiple CheckletResult objects. How the result properties are merged is configured using the MERGED_PROPS_TYPE class variable.

Parameters:

results (CheckletResult) – The results to merge

Return type:

CheckletResult

Returns:

The merged result

replace_placeholders(value, *, value_processor=None)

Convenience shortcut for momotor.options.parser.placeholders.replace_placeholders()

Return type:

str | None

replace_task_placeholder(text)

Convenience shortcut for momotor.options.parser.tasks.replace_task_placeholder()

Return type:

str | None

resolve_option(name, domain=None, *, subdomains=None, replace_tasknumber=False, replace_placeholders=False, resolve_reference=False, encoding='utf-8', errors='replace')

Resolve an option by getting the value from one of the option providers as configured in the options meta

Parameters:

  • name (str | OptionNameDomain) – Name of the option to retrieve

  • domain (str | None) – Domain of the option to retrieve (only used if name is a string)

  • subdomains (SubDomainDefinitionType’ | 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.

  • replace_tasknumber (bool) – If True, replaces task id placeholders in the option value with the task number.

  • replace_placeholders (bool) – If True, replace reference placeholders in the option value. Cannot be combined with resolve_reference.

  • resolve_reference (bool) – If True, resolve the value as a reference to another option or a property. Cannot be combined with replace_placeholders.

  • encoding (str) – The encoding to use when option is bytes. Set to None to not decode bytes.

  • errors (str) – The error handling strategy for decoding bytes.

Raises:

CheckletError – if the option is not defined

Return type:

typing.Any

resolve_value_reference(ref)

Convenience shortcut for momotor.options.parser.reference.resolve_value_reference()

Return type:

tuple[str | int | float | bool | None, str]

result(result_id)

Get the result of a previous task

Parameters:

result_id (str | StepTaskId) – The id of the task, as a str or a StepTaskId object

Return type:

Result

Returns:

The result

result_query(query)

Get results of previous tasks, filtered on one or more id queries.

The query is either a literal id (e.g. step, step.1 etc.), or a glob-like query to select multiple id’s, (e.g. *, step.*, step.?). Also applies task numbers, so e.g. step.$@ will match the exact same task number as the current result’s task number.

Multiple queries separated with a comma are possible.

See make_result_id_re() for the documentation on the query syntax, see apply_task_number() for documentation of the task number replacements using $.

Return type:

Iterator[Result]

select_by_file_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_file_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_opt_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_opt_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_prop_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_prop_reference()

Return type:

tuple[tuple[ReferenceMatch, ...], str]

select_by_reference(ref)

Convenience shortcut for momotor.options.parser.reference.select_by_reference()

Return type:

tuple[str | None, tuple[ReferenceMatch, ...], str]

MERGED_PROPS_TYPE: ClassVar[dict[str, tuple[type, Union[str, Callable]]]] = {'checklet-warning': (<class 'set'>, 'update')}

Properties that need special handling when merging using merge_results(). Default is using operator.add() which will work for strings and numeric values. Mapping from property name to a tuple containing the merged type, and a method for merging. The method for merging can be a function, or a method name for a method on the merged type.

property config: ConfigBundle | None

The provided config bundle

property product: ProductBundle

The provided product bundle

property recipe: RecipeBundle

The provided recipe bundle

property results: ResultsBundle

The provided results bundle, containing results of earlier steps

property step: Step

The current step