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.

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() will reopen the bundle and will require close() to be called again.

create(**kwargs)

Set this bundle’s attributes

Usage:

bundle = Bundle(...).create(...)
Return type

~BT

Returns

self

classmethod from_bytes_factory(data, *, xml_name=None, use_lxml=None, validate_xml=None, location_base=None)

Read bundle from memory, either a bytes or memoryview object.

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

Parameters
Return type

~BT

Returns

the bundle

classmethod from_file_factory(path, *, xml_name=None, use_lxml=None, validate_xml=None, location_base=None)

Read bundle from a local file or directory.

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

  • xml_name (Optional[str]) – XML file name if not the default (for directory and zip paths)

  • use_lxml (Optional[bool]) – Force (True) or prevent (False) use of lxml library. If None, auto-detects lxml availability

  • validate_xml (Optional[bool]) – Enable (True) or disable (False) XML validation. If None, uses pyxb.RequireValidWhenParsing setting

  • location_base (Union[str, Path, None]) – Location used in error messages

Return type

~BT

Returns

the 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_root_tag()

Get the XML root tag for this bundle

Return type

str

classmethod recreate_list(elements, target_bundle, target_basesrc=None, filter=None)

Recreate a list of elements

Parameters
  • elements (Optional[Iterator[~ET]]) – List of elements to recreate (can be None)

  • target_bundle (Bundle) – The target bundle

  • target_basesrc (PurePosixPath) – The base src of the target

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

Return type

Optional[List[~ET]]

Returns

a list of elements or None if elements param was None

to_buffer(buffer, *, xml_name=None, compression=8, compresslevel=None, zip=False, pretty_xml=False)

Export the bundle to a BinaryIO buffer and close it.

If zip 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 and named xml_name

Parameters
  • buffer (BinaryIO) – buffer to export into

  • xml_name (Optional[str]) – name of the xml document (only used when generating a zipped bundle)

  • compression (int) – compression mode, see zipfile.ZipFile for possible values. (Defaults to ZIP_DEFLATE, only used when generating a zipped bundle)

  • compresslevel (Optional[int]) – compression level, see zipfile.ZipFile for possible values. (Python 3.7+ only, ignored on Python 3.6, only used when generating a zipped bundle)

  • zip (bool) – Force zip format

  • pretty_xml (bool) – Produce a better readable xml document

Return type

BundleFormat

Returns

created format, either BundleFormat.XML or BundleFormat.ZIP

to_directory(path, *, xml_name=None, dir_mode=448, pretty_xml=False)

Export the bundle to a directory and close it.

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

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

  • xml_name (Optional[str]) – name of the xml document

  • dir_mode (int) – the mode bits (defaults to 0o700, making the directory only accessible to the current user)

  • pretty_xml (bool) – Produce a better readable xml document

Return type

None

to_file(fd_or_path, *, xml_name=None, compression=8, compresslevel=None, zip=False, pretty_xml=False)

Export the bundle to a file and close it.

If zip 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 and named xml_name

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

  • xml_name (Optional[str]) – name of the xml document (only used when generating a zipped bundle)

  • compression (int) – compression mode, see zipfile.ZipFile for possible values. (Defaults to ZIP_DEFLATE, only used when generating a zipped bundle)

  • compresslevel (Optional[int]) – compression level, see zipfile.ZipFile for possible values. (Python 3.7+ only, ignored on Python 3.6, only used when generating a zipped bundle)

  • zip (bool) – Force zip format

  • pretty_xml (bool) – Produce a better readable xml document

Return type

BundleFormat

Returns

created format, either BundleFormat.XML or BundleFormat.ZIP

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_file=None)

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

Parameters
copy_files(dest_dir)

Copy the files to dest_dir

Return type

None

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

Set all attributes for this ConfigBundle

Usage:

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

ConfigBundle

Returns

self

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

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”

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

List[Option]

Returns

A list of all matching options.

property files

The files

Return type

Optional[List[File]]

property id

The id attribute

Return type

Optional[str]

property options

options children

Return type

Optional[List[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_file=None)

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

Parameters
copy_files(dest_dir)

Copy the files to dest_dir

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
Return type

ProductBundle

Returns

self

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

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”

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

List[Option]

Returns

A list of all matching options.

get_properties(name)

Get properties

Parameters

name (str) – name of the properties to get

Return type

List[Property]

Returns

A list of all matching properties.

get_property_value(name)

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

Return type

Any

Returns

The property value

property files

The files

Return type

Optional[List[File]]

property id

The id attribute

Return type

Optional[str]

property options

options children

Return type

Optional[List[Option]]

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_file=None)

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

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

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[List[Option]]) – list of options (optional)

  • steps (Dict[str, Step]) – dictionary of steps with step_id as key

  • tests (Dict[str, Any]) – dictionary of tests with test_id as key

Return type

RecipeBundle

Returns

self

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

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”

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

List[Option]

Returns

A list of all matching options.

property id

The id attribute

Return type

Optional[str]

property options

options children

Return type

Optional[List[Option]]

property steps

The recipe’s steps

Return type

Optional[Dict[str, Step]]

property tests

The recipe’s tests (not implemented yet)

Return type

Optional[Dict[str, Any]]

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 inherited from Bundle

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, results=None)

Set all attributes for this ResultsBundle

Usage:

results = ResultsBundle(...).create(id, results)
Parameters
Return type

ResultsBundle

Returns

self

property id

The id attribute

Return type

Optional[str]

momotor.bundles.results.create_error_result_bundle(step_id, status, report=None)

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

Parameters
  • step_idid of the step

  • status – error status of the step

  • report – error report of the step

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
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

TestResultBundle

Returns

self

property results

results

Return type

List[Results]