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

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 can be used to initialize a newly created bundle, the class methods from_bytes_factory() and from_file_factory() can be used to create an initialized instance of a bundle class from an existing bundle file, either from memory or disk.

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

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

Access a Momotor bundle

Parameters

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper (Optional[ZipWrapper]) – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

close()

Close bundle and release all files and resources held.

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

create(**kwargs)

Set this bundle’s attributes

Usage:

bundle = Bundle(...).create(...)

Return type

TypeVar(BT, bound= Bundle)

Returns

self

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

Detect type of bundle and return the corresponding class.

Parameters

• path_or_data (Union[Path, bytes, memoryview]) – A Path to the bundle file or directory, or a bytes or memoryview containing a bundle XML or ZIP file

• args (Optional[BundleFactoryArguments]) – arguments for the detection

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

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 using the Bundle base class, uses detect() to autodetect the type of bundle. When using a specific bundle class, 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

• data (Union[bytes, memoryview]) – Bundle data

• args (Optional[BundleFactoryArguments]) – arguments for the factory

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

Return type

TypeVar(BT, bound= Bundle)

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 using the Bundle base class, uses detect() to autodetect the type of bundle. When using a specific bundle class, 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 (Union[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 (Optional[BundleFactoryArguments]) – arguments for the factory

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

Return type

TypeVar(BT, bound= Bundle)

Returns

the bundle

Raises

InvalidBundle if path does not contain a valid bundle

static get_category()

Get the category for this bundle

Return type

BundleCategory

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

Parameters

• elements (Optional[Iterator[TypeVar(ET, bound= Element)]]) – List of elements to recreate (can be None)

• target_bundle (Bundle) – The target bundle

• filter (Optional[Callable[[TypeVar(ET, bound= Element)], bool]]) – An optional callable to filter the list of elements before recreation. The callable receives an element and should return a boolean

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

Return type

Optional[List[TypeVar(ET, bound= Element)]]

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 (Optional[FileConstructionArguments]) – 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 (Optional[DirectoryConstructionArguments]) – 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 (Union[int, str, Path]) – either an open file descriptor, or a path. The file descriptor will be closed

• args (Optional[FileConstructionArguments]) – 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: 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

It also implements all methods inherited from Bundle

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

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

Parameters

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper (Optional[ZipWrapper]) – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

copy_files_to(destination, *, files=None)

Copy files to a directory

Parameters

• destination (Path) – destination for the files

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

Return type

None

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

Set all attributes for this ConfigBundle

Usage:

config = ConfigBundle(...).create(id, options, files)

Parameters

• id (Optional[str]) – id of the bundle (optional)

• options (Optional[Iterable[Option]]) – list of options (optional)

• files (Optional[Iterable[File]]) – list of files (optional)

Return type

TypeVar(BT, bound= Bundle)

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 in case option is empty or undefined

Return type

Any

Returns

The option value

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: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]

files children

Return type

FilterableTuple[File]

property id: Optional[str]

The id attribute

Return type

Optional[str]

property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]

options children

Return type

FilterableTuple[Option]

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

It also implements all methods inherited from Bundle

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

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

Parameters

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper (Optional[ZipWrapper]) – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

copy_files_to(destination, *, files=None)

Copy files to a directory

Parameters

• destination (Path) – destination for the files

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

Return type

None

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

Set all attributes for this ProductBundle

Usage:

product = ProductBundle(...).create(id, options, files)

Parameters

• id (Optional[str]) – id of the bundle (optional)

• options (Optional[Iterable[Option]]) – list of options (optional)

• files (Optional[Iterable[File]]) – list of files (optional)

• properties (Optional[Iterable[Property]]) – list of properties (optional)

Return type

TypeVar(BT, bound= Bundle)

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 in case option is empty or undefined

Return type

Any

Returns

The option value

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: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]

files children

Return type

FilterableTuple[File]

property id: Optional[str]

The id attribute

Return type

Optional[str]

property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]

options children

Return type

FilterableTuple[Option]

property properties: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.properties.Property]

properties children

Return type

FilterableTuple[Property]

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

It also implements all methods inherited from Bundle

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

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

Parameters

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper (Optional[ZipWrapper]) – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

copy_files_to(destination, *, files=None)

Copy files to a directory

Parameters

• destination (Path) – destination for the files

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

Return type

None

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

Set all attributes for this RecipeBundle

Usage:

recipe = RecipeBundle(...).create(id, options, steps, tests)

Parameters

• id (Optional[str]) – id of the bundle (optional)

• options (Optional[Iterable[Option]]) – list of options (optional)

• files (Optional[Iterable[File]]) – list of files (optional)

• steps (Iterable[Step]) – list of steps

• tests (Optional[Iterable]) – list of tests (optional)

Return type

TypeVar(BT)

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 in case option is empty or undefined

Return type

Any

Returns

The option value

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: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]

files children

Return type

FilterableTuple[File]

property id: Optional[str]

The id attribute

Return type

Optional[str]

property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]

options children

Return type

FilterableTuple[Option]

property steps: momotor.bundles.utils.keyedtuple.KeyedTuple[momotor.bundles.elements.steps.Step]

The recipe’s steps

Return type

KeyedTuple[Step]

property tests: momotor.bundles.utils.keyedtuple.KeyedTuple

The recipe’s tests (not implemented yet)

Return type

KeyedTuple

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 from Bundle and Results

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

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

Parameters

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

create(*, id=None, results=None)

Set all attributes for this ResultsBundle

Usage:

results = ResultsBundle(...).create(id, results)

Parameters

• id (Optional[str]) – id of the bundle (optional)

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

Return type

TypeVar(BT, bound= Bundle)

Returns

self

property id: Optional[str]

The id attribute

Return type

Optional[str]

property results: momotor.bundles.elements.results.ResultKeyedTuple

results children

Return type

ResultKeyedTuple

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 (Optional[str]) – 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

It also implements all methods inherited from Bundle

Self-testing is not yet implemented in Momotor.

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

• base (Union[str, Path, None]) – A path to the directory containing the XML source file in instance. Any file path is relative to this base.

• zip_wrapper – A ZipWrapper instance for the zip-file containing the bundle, for internal use by the from_bytes_factory() and from_file_factory() methods

create(*, results=None)

Set all attributes for this TestResultBundle

Usage:

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

Parameters

results (Optional[Iterable[Results]]) – list of results (optional)

Return type

TypeVar(BT, bound= Bundle)

Returns

self

property results: List[momotor.bundles.elements.results.Results]

results children

Return type

List[Results]