Bundles

There is a class for each bundle type: ConfigBundle, ProductBundle, RecipeBundle, ResultsBundle, and TestResultBundle.

All classes implement the same basic functionality to implement reading and writing bundles, plus functionality specific to the bundle type.

Bundle base

Bundle is the base class from which all other bundle types extend. It provides the shared functionality for all bundle classes.

The constructor creates a new uninitialized bundle. The create() method is used to initialize a newly created bundle, the class methods from_bytes_factory() and from_file_factory() are used load a bundle from either a bytes (or more specifically a memoryview) object or a file.

The methods to_buffer(), to_directory(), and to_file() are used to export a bundle to various formats. A bundle must be fully initialized before it can be exported.

Bundles are immutable, it’s not possible to modify a bundle once it has been created. The bundle and each element have recreate() and recreate_list() methods to copy elements from one bundle to another optionally with modifications to (some of the) attributes.

class momotor.bundles.Bundle(base=None, zip_wrapper=None)

Access a Momotor bundle

Parameters:
close()

Close bundle and release all files and resources held.

Any access to the bundle after calling close() is undefined.

abstract create(**kwargs)

Set this element’s attributes

Usage:

element = Element(bundle).create(...)
Return type:

Self

Returns:

self

classmethod detect(path_or_data, *, args=None, **kwargs)

Detect type of bundle and return the corresponding class.

Parameters:
Return type:

type[Bundle]

Returns:

The matching Bundle class, either RecipeBundle, ConfigBundle, ProductBundle, ResultsBundle, or TestResultBundle

Raises:

FileNotFoundError if path does exist

Raises:

InvalidBundle if path does not contain a bundle

classmethod from_bytes_factory(data, *, args=None, **kwargs)

Read bundle from memory, either a bytes or memoryview object. When called from the Bundle base class, uses detect() to autodetect the type of bundle. When called from a specific bundle class specialization, will raise an InvalidBundle exception if the object contains the wrong bundle type.

Make sure to call close() either explicitly or using contextlib.closing() when done with the bundle to release all resources

Parameters:

  • data (bytes | memoryview) – Bundle data

  • args (BundleFactoryArguments | None) – arguments for the factory

  • kwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args

Return type:

Self

Returns:

the bundle

Raises:

InvalidBundle if data does not contain a valid bundle

classmethod from_file_factory(path, *, args=None, **kwargs)

Read bundle from a local file or directory. When called from the Bundle base class, uses detect() to autodetect the type of bundle. When called from a specific bundle class specialization, will raise an InvalidBundle exception if the file is the wrong bundle type.

Make sure to call close() either explicitly or using contextlib.closing() when done with the bundle to release all resources

Parameters:

  • path (str | Path) – Either a file or directory. When it is a file, it can be an XML file or a zip file. When it is a directory, that directory should contain a <bundle>.xml file

  • args (BundleFactoryArguments | None) – arguments for the factory

  • kwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args

Return type:

Self

Returns:

the bundle

Raises:

InvalidBundle if path does not contain a valid bundle

abstract static get_category()

Get the category for this bundle

Return type:

BundleCategory

abstract static get_default_xml_name()

Get the default XML file name

Return type:

str

static get_node_type()

Get the xsData node type

Return type:

type[TypeVar(CT, bound= object)]

classmethod get_root_qname()

Get the XML root tag for this bundle

Return type:

str

classmethod get_root_tag()

Get the XML root tag for this bundle

Return type:

str

classmethod recreate_list(elements, target_bundle, filter=None, **kwargs)

Recreate a list of elements using the recreate() method

Parameters:

  • elements (Iterable[Self] | None) – List of elements to recreate (can be None)

  • target_bundle (Bundle) – The target bundle

  • filter (Callable[[Self], bool] | None) – An optional callable to filter the list of elements before recreation. The callable receives an element and should return a boolean. Only elements for which the callable returns True will be recreated

  • kwargs – Additional keyword arguments are passed on to recreate()

Return type:

list[Self] | None

Returns:

a list of elements or None if elements param was None

to_buffer(buffer, *, args=None, **kwargs)

Export the bundle to a BinaryIO buffer and close it.

If the zip option is False and the bundle does not contain any attachments, will generate a plain XML bundle, otherwise it will generate a zip compressed bundle with the bundle XML file located in the root of the zip file.

Any access to the bundle after calling to_buffer() is undefined.

Parameters:

  • buffer (BinaryIO) – buffer to export into

  • args (FileConstructionArguments | None) – arguments for the construction

  • kwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args

Return type:

BundleFormat

Returns:

created format, either BundleFormat.XML or BundleFormat.ZIP

to_directory(path, *, args=None, **kwargs)

Export the bundle to a directory.

Writes the XML file to the given path and all the bundle’s attachments in the right location relative to the XML file.

Any access to the bundle after calling to_directory() is undefined.

Parameters:

  • path (Path) – path of the directory. Will be created if it does not exist

  • args (DirectoryConstructionArguments | None) – arguments for the construction

  • kwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args

Return type:

None

to_file(fd_or_path, *, args=None, **kwargs)

Export the bundle to a file and close it.

If the zip option is False and the bundle does not contain any attachments, will generate a plain XML bundle, otherwise it will generate a zip compressed bundle with the bundle XML file located in the root of the zip file.

Any access to the bundle after calling to_file() is undefined.

Parameters:

  • fd_or_path (int | str | Path) – either an open file descriptor, or a path. The file descriptor will be closed

  • args (FileConstructionArguments | None) – arguments for the construction

  • kwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args

Return type:

BundleFormat

Returns:

created format, either BundleFormat.XML or BundleFormat.ZIP

bundle: typing.Final['momotor.bundles.Bundle']

The Bundle containing this element

ConfigBundle

A ConfigBundle contains all configuration needed by the recipe. It provides a Python interface to read and create XML files of ConfigComplexType

See the documentation of the base class Bundle on how to use bundles.

class momotor.bundles.ConfigBundle(base=None, zip_wrapper=None)

A config bundle. This implements the interface to create and access Momotor configuration files

Parameters:
copy_files_to(destination, *, files=None)

Copy files attached using the files nodes to a directory

Parameters:

  • destination (Path) – destination for the files

  • files (Sequence[File] | None) – optionally a filtered list of files to copy

Return type:

None

create(*, id=None, meta=None, options=None, files=None)

Set all attributes for this ConfigBundle

Usage:

config = ConfigBundle(...).create(id=..., meta=..., options=..., files=...)
Parameters:
Return type:

Self

Returns:

self

get_option_value(name, *, domain='checklet', default=<object object>)

Get the value for a single option. If multiple options match, the value of the first one found will be returned.

Parameters:

  • name (str) – name of the option to get

  • domain (str) – domain of the option to get. Defaults to checklet

  • default – default value to return in case option is empty or undefined instead of raising an exception

Return type:

Any

Returns:

The option value

Raises:

  • KeyError – If no option with the given name exists and no default is provided

  • NoContent – If the option is empty

get_options(name, *, domain='checklet')

Get options

Parameters:

  • name (str) – name of the options to get

  • domain (str) – domain of the options to get. Defaults to checklet

Return type:

FilterableTuple[Option]

Returns:

A filterable tuple of all matching options.

property files: FilterableTuple[File]

files children

property id: str | None

The id attribute

property meta: Meta

meta attribute

property options: FilterableTuple[Option]

options children

ProductBundle

A ProductBundle contains the product to be evaluated by the recipe. It provides a Python interface to read and create XML files of ProductComplexType

See the documentation of the base class Bundle on how to use bundles.

class momotor.bundles.ProductBundle(base=None, zip_wrapper=None)

A product bundle. This implements the interface to create and access Momotor product files

Parameters:
copy_files_to(destination, *, files=None)

Copy files attached using the files nodes to a directory

Parameters:

  • destination (Path) – destination for the files

  • files (Sequence[File] | None) – optionally a filtered list of files to copy

Return type:

None

create(*, id=None, meta=None, options=None, files=None, properties=None)

Set all attributes for this ProductBundle

Usage:

product = ProductBundle(...).create(id=..., meta=..., options=..., files=..., properties=...)
Parameters:
Return type:

Self

Returns:

self

get_option_value(name, *, domain='checklet', default=<object object>)

Get the value for a single option. If multiple options match, the value of the first one found will be returned.

Parameters:

  • name (str) – name of the option to get

  • domain (str) – domain of the option to get. Defaults to checklet

  • default – default value to return in case option is empty or undefined instead of raising an exception

Return type:

Any

Returns:

The option value

Raises:

  • KeyError – If no option with the given name exists and no default is provided

  • NoContent – If the option is empty

get_options(name, *, domain='checklet')

Get options

Parameters:

  • name (str) – name of the options to get

  • domain (str) – domain of the options to get. Defaults to checklet

Return type:

FilterableTuple[Option]

Returns:

A filterable tuple of all matching options.

get_properties(name)

Get properties

Parameters:

name (str) – name of the properties to get

Return type:

FilterableTuple[Property]

Returns:

A list of all matching properties.

get_property_value(name, *, default=<object object>)

Get the value for a single property. If multiple properties match, the value of the first one found will be returned

Parameters:

  • name (str) – name of the property to get

  • default – default value in case property is empty or undefined

Return type:

Any

Returns:

The property value

property files: FilterableTuple[File]

files children

property id: str | None

The id attribute

property meta: Meta

meta attribute

property options: FilterableTuple[Option]

options children

property properties: FilterableTuple[Property]

properties children

RecipeBundle

A RecipeBundle describes the process of processing a product into a result. It provides a Python interface to read and create XML files of RecipeComplexType

See the documentation of the base class Bundle on how to use bundles.

class momotor.bundles.RecipeBundle(base=None, zip_wrapper=None)

A recipe bundle. This implements the interface to create and access Momotor recipe files

Parameters:
copy_files_to(destination, *, files=None)

Copy files attached using the files nodes to a directory

Parameters:

  • destination (Path) – destination for the files

  • files (Sequence[File] | None) – optionally a filtered list of files to copy

Return type:

None

create(*, id=None, meta=None, options=None, files=None, steps, tests=None)

Set all attributes for this RecipeBundle

Usage:

recipe = RecipeBundle(...).create(id=..., meta=..., options=..., files=..., steps=..., tests=...)
Parameters:
Return type:

Self

Returns:

self

get_option_value(name, *, domain='checklet', default=<object object>)

Get the value for a single option. If multiple options match, the value of the first one found will be returned.

Parameters:

  • name (str) – name of the option to get

  • domain (str) – domain of the option to get. Defaults to checklet

  • default – default value to return in case option is empty or undefined instead of raising an exception

Return type:

Any

Returns:

The option value

Raises:

  • KeyError – If no option with the given name exists and no default is provided

  • NoContent – If the option is empty

get_options(name, *, domain='checklet')

Get options

Parameters:

  • name (str) – name of the options to get

  • domain (str) – domain of the options to get. Defaults to checklet

Return type:

FilterableTuple[Option]

Returns:

A filterable tuple of all matching options.

property files: FilterableTuple[File]

files children

property id: str | None

The id attribute

property meta: Meta

meta attribute

property options: FilterableTuple[Option]

options children

property steps: KeyedTuple[Step]

The recipe’s steps

property tests: KeyedTuple

The recipe’s tests (not implemented yet)

ResultsBundle

A ResultsBundle contains the results of the recipe applied to a product. It provides a Python interface to read and create XML files of ResultsComplexType

It also implements all methods and properties inherited Results

See the documentation of the base class Bundle on how to use bundles.

class momotor.bundles.ResultsBundle(base=None, zip_file=None)

A results bundle. This implements the interface to create and access Momotor result files

Parameters:
create(*, id=None, meta=None, results=None)

Set all attributes for this ResultsBundle

Usage:

results = ResultsBundle(...).create(id=..., meta=..., results=...)
Parameters:

  • id (str | None) – id of the bundle (optional)

  • meta (Meta | None) – meta of the bundle (optional)

  • results (Iterable[Result] | None) – sequence of results (optional)

Return type:

Self

Returns:

self

property id: str | None

The id attribute

property meta: Meta

meta attribute

property results: ResultKeyedTuple

results children

momotor.bundles.results.create_error_result_bundle(result_id, status, report=None, **properties)

Helper to create an error result bundle with a single step with an error

Parameters:

  • result_id (str) – id of the step

  • status (str) – error status of the step

  • report (str | None) – error report of the step

  • properties – additional properties to add

Return type:

ResultsBundle

Returns:

A ResultsBundle with the error step

TestResultBundle

A TestResultBundle contains the results of a recipe’s self-test. It provides a Python interface to read and create XML files of TestResultComplexType

See the documentation of the base class Bundle on how to use bundles.

Note

Self-testing bundles are not yet implemented in Momotor, this interface is subject to change when testing gets implemented.

class momotor.bundles.TestResultBundle(base=None, zip_file=None)

A test results bundle. This implements the interface to create and access Momotor result files containing test results

Parameters:
create(*, results=None)

Set all attributes for this TestResultBundle

Usage:

test_result = TestResultBundle(...).create(results)
Parameters:

results (Iterable[Results] | None) – list of results (optional)

Return type:

Self

Returns:

self

property results: list[Results]

results children