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
]) – AZipWrapper
instance for the zip-file containing the bundle, for internal use by thefrom_bytes_factory()
andfrom_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(...)
- 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
]) – APath
to the bundle file or directory, or abytes
ormemoryview
containing a bundle XML or ZIP fileargs (
Optional
[BundleFactoryArguments
]) – arguments for the detectionkwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args
- Return type
- Returns
The matching
Bundle
class, eitherRecipeBundle
,ConfigBundle
,ProductBundle
,ResultsBundle
, orTestResultBundle
- 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
ormemoryview
object. When using theBundle
base class, usesdetect()
to autodetect the type of bundle. When using a specific bundle class, will raise anInvalidBundle
exception if the file is the wrong bundle type.Make sure to call
close()
either explicitly or usingcontextlib.closing()
when done with the bundle to release all resources- Parameters
data (
Union
[bytes
,memoryview
]) – Bundle dataargs (
Optional
[BundleFactoryArguments
]) – arguments for the factorykwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args
- Return type
- 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, usesdetect()
to autodetect the type of bundle. When using a specific bundle class, will raise anInvalidBundle
exception if the file is the wrong bundle type.Make sure to call
close()
either explicitly or usingcontextlib.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 fileargs (
Optional
[BundleFactoryArguments
]) – arguments for the factorykwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args
- Return type
- Returns
the bundle
- Raises
InvalidBundle
if path does not contain a valid bundle
- static get_category()¶
Get the category for this bundle
- Return type
- 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 bundlefilter (
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 booleankwargs – Additional keyword arguments are passed on to
recreate()
- Return type
- 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 intoargs (
Optional
[FileConstructionArguments
]) – arguments for the constructionkwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args
- Return type
- Returns
created format, either
BundleFormat
.XML
orBundleFormat
.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 existargs (
Optional
[DirectoryConstructionArguments
]) – arguments for the constructionkwargs – alternative way to provide the arguments. Arguments in kwargs override arguments in args
- Return type
- 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
- Return type
- Returns
created format, either
BundleFormat
.XML
orBundleFormat
.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_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
]) – AZipWrapper
instance for the zip-file containing the bundle, for internal use by thefrom_bytes_factory()
andfrom_file_factory()
methods
- copy_files_to(destination, *, files=None)¶
Copy files to a directory
- create(*, id=None, options=None, files=None)¶
Set all attributes for this ConfigBundle
Usage:
config = ConfigBundle(...).create(id, options, files)
- 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
- get_options(name, *, domain='checklet')¶
Get options
- Parameters
- Return type
- Returns
A filterable tuple of all matching options.
- property files: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]¶
files children
- Return type
- property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]¶
options children
- Return type
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
]) – AZipWrapper
instance for the zip-file containing the bundle, for internal use by thefrom_bytes_factory()
andfrom_file_factory()
methods
- copy_files_to(destination, *, files=None)¶
Copy files to a directory
- 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
- 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
- get_options(name, *, domain='checklet')¶
Get options
- Parameters
- Return type
- Returns
A filterable tuple of all matching options.
- get_properties(name)¶
Get properties
- Parameters
name (
str
) – name of the properties to get- Return type
- 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
- property files: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]¶
files children
- Return type
- property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]¶
options children
- Return type
- property properties: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.properties.Property]¶
properties children
- Return type
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
]) – AZipWrapper
instance for the zip-file containing the bundle, for internal use by thefrom_bytes_factory()
andfrom_file_factory()
methods
- copy_files_to(destination, *, files=None)¶
Copy files to a directory
- 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
- 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
- get_options(name, *, domain='checklet')¶
Get options
- Parameters
- Return type
- Returns
A filterable tuple of all matching options.
- property files: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.files.File]¶
files children
- Return type
- property options: momotor.bundles.utils.filters.FilterableTuple[momotor.bundles.elements.options.Option]¶
options children
- Return type
- property steps: momotor.bundles.utils.keyedtuple.KeyedTuple[momotor.bundles.elements.steps.Step]¶
The recipe’s steps
- Return type
- property tests: momotor.bundles.utils.keyedtuple.KeyedTuple¶
The recipe’s tests (not implemented yet)
- Return type
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 thefrom_bytes_factory()
andfrom_file_factory()
methods
- create(*, id=None, results=None)¶
Set all attributes for this ResultsBundle
Usage:
results = ResultsBundle(...).create(id, results)
- property results: momotor.bundles.elements.results.ResultKeyedTuple¶
results children
- Return type
- 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
- Return type
- 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 thefrom_bytes_factory()
andfrom_file_factory()
methods
- create(*, results=None)¶
Set all attributes for this TestResultBundle
Usage:
test_result = TestResultBundle(...).create(results)
- property results: List[momotor.bundles.elements.results.Results]¶
results children