Elements

Elements represent the contents of a bundle, such as files, options, steps, and results. Their constructors accept the owning bundle. create() then initializes their attributes once:

from momotor.bundles import RecipeBundle
from momotor.bundles.elements.checklets import Checklet
from momotor.bundles.elements.steps import Step

recipe = RecipeBundle()
checklet = Checklet(recipe).create(name='example-checklet')
step = Step(recipe).create(id='run', checklet=checklet)
recipe.create(steps=[step])

recreate(target_bundle, **changes) creates a new element in another bundle. Omitted arguments retain their original values. For optional fields, an explicit None clears the field. recreate_list() applies recreation to a collection. The Bundles reference describes attachment ownership during recreation.

Changed in version 8.3.0: recreate() is implemented for every element type and can replace every field. Earlier versions only replaced some fields.

Collections differ by purpose. Steps and results use KeyedTuple, which supports integer indices and string IDs. Options, files, and properties use FilterableTuple, which supports the lookups in Sequence filtering. These collections preserve their item order.

Element base

Every element shares this base class. It provides the create() and recreate() methods used in the example above.

class momotor.bundles.elements.base.Element(bundle)

Abstract base for bundles and the elements they contain.

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Get the xsData node type

Return type:

type[TypeVar(CT)]

abstractmethod create(*args, **kwargs)

Set this element’s attributes

Usage:

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

Self

Returns:

self

abstractmethod recreate(target_bundle, *args, **kwargs)

Recreate this element in a target bundle

Parameters:

target_bundle (Bundle) – The target bundle

Return type:

Self

bundle: Final[Bundle]

The Bundle containing this element

Checklet

A checklet is the program that a recipe step runs. A checklet element names that program and where to find it.

class momotor.bundles.elements.checklets.Checklet(bundle)

A Checklet element encapsulating CheckletComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[CheckletComplexType]

create(*, name=None, extras=None, version=None, entrypoint=None, repository=None, link=None, indices=None, package_versions=None, resources=None)

Initialize the package and entry point for a checklet.

Parameters:
  • name (str | None) – Optional Python package name.

  • extras (Iterable[str] | None) – Optional package extras to install.

  • version (str | None) – Optional package version constraint.

  • entrypoint (str | None) – Optional entry point interpreted by the executor.

  • repository (Repository | None) – Attached source repository owned by this bundle.

  • link (Link | None) – Optional package source link.

  • indices (Iterable[Link] | None) – Additional package index links.

  • package_versions (Iterable[PackageVersion] | None) – Version constraints for dependent packages.

  • resources (Iterable[Resource] | None) – Resource declarations owned by this bundle.

Return type:

Self

Returns:

This initialized element.

get_dist_name()

Return a distribution selector (ie. name, extras and version in a single string)

eg: “name[extra1,extra2]==1.0”

Return type:

str

get_resources()

Get the resources as a dictionary name -> Resource

Return type:

dict[str, FilterableTuple[Resource]]

recreate(target_bundle, *, name=<object object>, extras=<object object>, version=<object object>, entrypoint=<object object>, repository=<object object>, link=<object object>, indices=<object object>, package_versions=<object object>, resources=<object object>)

Recreate this Checklet in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Original repositories and resources are recreated so they belong to the target bundle.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • name (str | None) – New checklet name, or None to clear it

  • extras (Iterable[str] | None) – New extras, or None to clear them

  • version (str | None) – New version, or None to clear it

  • entrypoint (str | None) – New entrypoint, or None to clear it

  • repository (Repository | None) – New repository, or None to clear it

  • link (Link | None) – New link, or None to clear it

  • indices (Iterable[Link] | None) – New indices, or None to clear them

  • package_versions (Iterable[PackageVersion] | None) – New package versions, or None to clear them

  • resources (Iterable[Resource] | None) – New resources, or None to clear them

Return type:

Self

Returns:

The newly created Checklet

bundle

The Bundle containing this element

property entrypoint: str | None

entrypoint attribute: Override the default package entrypoint

property extras: FilterableTuple[str] | None

extras attribute: The Python package extras (eg. “requests”)

property indices: list[Link] | None

indices attribute: (unused, untested)

link attribute: (unused, untested)

property name: NTG | None

The name attribute

property package_versions: FilterableTuple[PackageVersion] | None

package_versions attribute: (unused, untested)

property repository: Repository | None

repository attribute: where to retrieve the package from

property resources: FilterableTuple[Resource]

resources attribute

property version: str | None

version attribute: A PEP 440 Python package version specifier (eg. “>=1.0”)

An immutable dataclass for a reference to a link

src: str

The src of the link

class momotor.bundles.elements.checklets.PackageVersion(name, version)

An immutable dataclass for a reference to a package with version

name: str

The name of the package

version: str

The version qualifier for the package

class momotor.bundles.elements.checklets.Repository(bundle)

An attached repository with a type and optional revision.

Parameters:

bundle (Bundle) – Bundle that owns this repository element.

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[Repository]

create(*, src, type_, revision=None)

Initialize a reference to an attached repository directory.

The source remains external until export. Keep its files or source ZIP available until then.

Parameters:
  • src (PurePath | AttachmentSrc | None) – Filesystem path or attachment reference. Relative paths use the owning bundle as their base.

  • type – Repository type interpreted by the engine, such as git.

  • revision (str | None) – Optional repository revision.

Return type:

Self

Returns:

This initialized element.

recreate(target_bundle, *, src=<object object>, type_=<object object>, revision=<object object>)

Recreate this Repository in a target bundle, optionally replacing any field.

If src is not provided, the target bundle will link to the same attachment; the attachment will not be copied. Other fields that are not provided are copied unchanged.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • src (PurePath | AttachmentSrc | None) – New repository source, or None to clear it

  • type – New repository type

  • revision (str | None) – New revision, or None to clear it

Return type:

Self

Returns:

The recreated Repository

property revision: str | None

Requested repository revision, or None when unspecified.

property type_: str

Repository type passed to the engine.

File

A file element holds inline content or refers to an attachment. See Content and attachments for reading and copying attachments.

class momotor.bundles.elements.files.File(bundle)

A File element encapsulating FileComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[FileComplexType]

copy_to(destination, *, name=None, executable_attribute=False)

Copy inline content or an attachment into a destination directory.

Parameters:
  • destination (Path) – Existing destination directory.

  • name (str | PurePath | None) – Relative destination name. Omission uses this file’s name.

  • executable_attribute (bool) – Add executable bits when this file’s executable attribute is true.

Return type:

PurePath

Returns:

Path to the copied file or directory.

Raises:

BundleError – If a destination name escapes the destination directory.

create(*, class_=None, name=None, src=None, content=<object object>, type_=None, executable=False, preserve_executable=False, attrs=None)

Set this file node’s attributes.

This creates an attachment for the bundle. The src or content parameters provide the content for the attachment. Only one of them can be set. When a file path is provided using src, the file must exist when the bundle is exported using one of the Bundle.to_* methods.

Note that the src parameter of this method is not directly related to the src attribute of the <file> node in the generated XML when exporting the bundle, and how the src attribute is generated is an implementation detail of this library that can change between versions. Do not rely on an attachment being exported to a specific location in a generated zip bundle.

Parameters:
  • class – The class attribute of the file node

  • name (str | PurePosixPath | None) – The name attribute of the file node

  • src (AttachmentSrc | Path | None) – The source of the file. See note above.

  • content (str | bool | None | NewType(NoContentType, object) | bytes | int | float | Decimal) – The inline content of the file, including binary bytes. Defaults to NO_CONTENT.

  • type – The type attribute of the file node

  • executable (bool) – The executable attribute of the file node

  • preserve_executable (bool) – Retain executable bits of filesystem attachment files, including directory members. Defaults to stripping these bits. Existing attachment sources retain their policy.

  • attrs (dict | None) – Additional attributes of the file node

Return type:

Self

Added in version 9.0.0: The preserve_executable parameter.

directory_hashes(hash_names)

Calculate versioned digests of every regular descendant and relative name.

Parameters:

hash_names (Iterable[str]) – Algorithms used for the framed tree digest.

Return type:

dict[str, str]

Returns:

Hexadecimal directory-v1 digests; empty directories do not participate.

Raises:

NotADirectoryError – If this attachment is a file.

file_ctime(path=None)

Get file creation time for the attachment.

Return type:

struct_time | None

file_hashes(hash_names)

Calculate the hashes of the file.

Only for file attachments. Will return an empty dictionary if the file does not exist or is a directory.

Parameters:

hash_names (Iterable[str]) – Names of the hashes to calculate. Should be valid arguments to hashlib.new()

Return type:

dict[str, str]

Returns:

A dictionary hash-algorithm -> hash

file_size(path=None)

Return the content length.

Inline strings report their character count. Inline bytes and external files report their byte count.

Parameters:

path (str | PurePath | None) – Optional relative path inside a directory attachment.

Return type:

int | None

Returns:

Content length.

Raises:
has_attachment_content()

Returns True if the element has an existing attachment

Return type:

bool

has_bundle()

Check if src references a file associated with a bundle.

Return type:

bool

Returns:

True if src references a file associated with a bundle

has_inline_content()

Check if element has inline content without processing it.

Return type:

bool

Returns:

True if element has any form of inline content (value attribute, raw content, processed value, or encoding)

has_inline_text_content()

Check if element has inline text content without processing it.

Return type:

bool

Returns:

True if the value property would return text content (bytes or str) without actually converting the content

has_text_content()

Check if element has any form of text content.

Return type:

bool

Returns:

True if the element has text content, either inline or as attachment, without processing the content

has_writable_content()

Return whether the element has an attachment or inline text or bytes.

has_zip_bundle()

Check if src references a file in a zipped bundle.

Return type:

bool

Returns:

True if src references a file associated with a zipped bundle

is_dir(path=None)

Return whether the attachment or a member is a directory.

Parameters:

path (str | PurePath | None) – Optional relative path inside a directory attachment.

Return type:

bool

Returns:

False for inline content, otherwise the attachment’s directory status.

iterdir(*, include_empty_root=False)

Recursively iterate the contents of a directory attachment. The returned paths are relative to self.absolute_path

If the attachment is an empty directory and include_empty_root is True, a single None value is yielded

Raises:

BundleError – if a member escapes its root or an imported filesystem member is a symlink

Return type:

Generator[PurePath | None, None, None]

open(path=None)

Open inline text, inline bytes, or an attachment as a binary stream.

Inline strings are encoded as UTF-8. The caller closes the returned stream.

Parameters:

path (str | PurePath | None) – Relative member path for a directory attachment. Omit for inline content or a single file.

Return type:

IO[bytes]

Returns:

Readable binary stream.

Raises:

FileNotFoundError – If a member path is supplied for inline content, or an attachment is missing.

read(path=None)

Read inline text, inline bytes, or an attachment as bytes.

Parameters:

path (str | PurePath | None) – Relative member path for a directory attachment. Omit for inline content or a single file.

Return type:

bytes

Returns:

Complete file content. Inline strings are encoded as UTF-8.

Raises:

FileNotFoundError – If a member path is supplied for inline content, or an attachment is missing.

recreate(target_bundle, *, class_=<object object>, name=<object object>, src=<object object>, content=<object object>, type_=<object object>, executable=<object object>, attrs=<object object>)

Recreate this File in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. If the node has a src attachment and neither src nor content is replaced, the target bundle will link to the same file; the file will not be copied. The same mutual-exclusion rules for src and content as create() apply.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • class – New class for the file, or None to clear it

  • name (str | PurePosixPath | None) – New name for the file, or None to clear it

  • src (AttachmentSrc | Path | None) – New attachment source, or None to clear it

  • content (str | bool | None | NewType(NoContentType, object) | bytes | int | float | Decimal) – New inline content, including binary bytes

  • type – New content type, or None to clear it

  • executable (bool) – New executable flag

  • attrs (dict | None) – New attributes, or None to clear them

Return type:

Self

Returns:

The recreated file

validate_hashes(expected_hashes, *, kind=None)

Validate file hashes or an explicitly versioned directory digest.

Parameters:
  • expected_hashes (dict[str, str]) – Expected hexadecimal digests by algorithm.

  • kind (str | None) – directory-v1 for a directory, or None for ordinary file hashes.

Return type:

bool

Returns:

Whether all hashes match. Unknown kinds and file/directory substitutions fail.

HAS_ENCODING = True
MAX_VALUE_LENGTH = 1000
VALID_PROCESSED_TYPES = (<class 'str'>, <class 'bool'>, <class 'bytes'>, <class 'int'>, <class 'float'>, <class 'decimal.Decimal'>)
property absolute_path: Path

Get the absolute path of the attachment referenced by src

Raises:
  • ZippedAttachment – when the attachment is in a zipped bundle and therefor has no filesystem path

  • BundleError – if an imported source escapes its bundle root

property attrs: ImmutableDict[str, str]

Wildcard attributes

bundle

The Bundle containing this element

property class_: str | None

class attribute

property encoding: str | None

encoding attribute: read-only, the encoding is automatically determined from the value

property executable: bool

executable attribute

If this attribute is set to True, the file “Executable” mode bits (S_IXUSR, S_IXGRP and S_IXOTH) will be set when the file is copied using copy_to() with the executable_attribute parameter set to True.

property export_src: PurePath

The export path of the attachment, converted to be safe for use in ZIP files

property name: NTG | None

The name attribute

property src: PurePath | None

src attribute: file path of the content.

property src_bundle: Bundle | None

If src is a relative path, the Bundle src references to.

An src attribute with a relative path is always associated with a bundle, either the current bundle or a source bundle retained by recreate(). The source bundle provides the base path for the relative path.

property type_: str | None

The type attribute.

property value: PT

value attribute: The content.

Setting value to None will generate a node with a <none/> tag. Set value to NO_CONTENT to create an empty content node.

When accessing, raises NoContent if no content was set instead of returning NO_CONTENT, raises AttachmentContent if the node refers to an attachment using src.

Meta

Metadata describes a bundle: its name, version, descriptions, authors, sources, and the tool that generated it. Most bundles and some elements carry metadata in their meta attribute.

class momotor.bundles.elements.meta.Meta(name=None, version=None, descriptions=<factory>, authors=<factory>, sources=<factory>, generators=<factory>)

A frozen dataclass containing metadata. All fields are optional.

Added in version 8.0.0.

recreate(target_bundle, *, name=<object object>, version=<object object>, descriptions=<object object>, authors=<object object>, sources=<object object>, generators=<object object>)

Recreate this metadata for a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Original descriptions are recreated so they belong to the target bundle.

Parameters:
Return type:

Self

Returns:

The recreated metadata

Added in version 8.3.0.

authors: tuple[str, ...]

a sequence of author strings.

descriptions: Sequence[Description]

a FilterableTuple of Description elements.

generators: tuple[str, ...]

a sequence of generator strings. indicates the tool that created the bundle

name: str | None = None

name string - only a single name value is allowed. if the bundle has multiple names, the first one is used.

sources: tuple[str, ...]

a sequence of source strings. indicates the source of the bundle

version: str | None = None

version string - only a single version value is allowed. if the bundle has multiple versions, the first one is used.

class momotor.bundles.elements.meta.Description(bundle)

A Description element encapsulating Description

Added in version 8.0.0.

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

static get_node_type()

Get the xsData node type

Return type:

type[TypeVar(CT)]

create(*, text=None, lang=None, markup=None)

Initialize a metadata description.

Parameters:
  • text (str | None) – Description text. HTML markup remains text and is escaped during XML export.

  • lang (str | None) – Optional language code stored in xml:lang.

  • markup (str | None) – Optional format label, such as text, html, or rst. This package does not render it.

Return type:

Self

Returns:

This initialized element.

recreate(target_bundle, *, text=<object object>, lang=<object object>, markup=<object object>)

Recreate this Description in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • text (str | None) – New description text, or None to clear it

  • lang (str | None) – New language code, or None to clear it

  • markup (str | None) – New markup type, or None to clear it

Return type:

Self

Returns:

The recreated Description

bundle: Final[Bundle]

The Bundle containing this element

property lang: str | None

xml:lang attribute: language code of this description node

property markup: str | None

markup attribute: markup of this description node, e.g. rst or text

Added in version 8.0.0.

property text: str | None

The description text

Option

An option is a named setting value, such as a timeout. Recipes, configurations, and products can carry options.

class momotor.bundles.elements.options.Option(bundle)

An Option element encapsulating OptionComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[OptionComplexType]

create(*, name, domain=None, value=None, type_=None, description=None, attrs=None)

Initialize an option with a name, domain, and inline value.

Parameters:
  • name (str) – Option name within its domain.

  • domain (str | None) – Domain name. Omission uses checklet. A leading # adds a subdomain to checklet.

  • value (Any) – Python value. None represents an explicit XML <none/> value.

  • type – Scalar type name, such as integer or decimal. Omission infers the type from the value.

  • description (str | None) – Optional description of the option.

  • attrs (Mapping[str, str] | None) – Additional XML attributes keyed by their qualified names.

Return type:

Self

Returns:

This initialized element.

has_attachment_content()

Check if element has attachment content.

Return type:

bool

Returns:

True if this element has an existing attachment

has_inline_content()

Check if element has inline content without processing it.

Return type:

bool

Returns:

True if element has any form of inline content (value attribute, raw content, processed value, or encoding)

has_inline_text_content()

Check if element has inline text content without processing it.

Return type:

bool

Returns:

True if the value property would return text content (bytes or str) without actually converting the content

has_text_content()

Check if element has any form of text content.

Return type:

bool

Returns:

True if the element has text content, either inline or as attachment, without processing the content

recreate(target_bundle, *, name=<object object>, domain=<object object>, value=<object object>, type_=<object object>, description=<object object>, attrs=<object object>)

Recreate this Option in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Existing raw or encoded content is preserved when neither value nor type_ is replaced.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • name (str) – New name for the option

  • domain (str | None) – New domain for the option, or None to use the default domain

  • value (Any) – New value for the option

  • type – New type for the option, or None to clear it

  • description (str | None) – New description, or None to clear it

  • attrs (Mapping[str, str] | None) – New attributes, or None to clear them

Return type:

Self

Returns:

The recreated Option

DEFAULT_DOMAIN: ClassVar[str] = 'checklet'
HAS_ENCODING: ClassVar[bool] = True
MAX_VALUE_LENGTH: ClassVar = 1000
VALID_PROCESSED_TYPES: ClassVar[tuple[type, ...]] = (<class 'str'>, <class 'bool'>, <class 'bytes'>, <class 'int'>, <class 'float'>, <class 'decimal.Decimal'>)
property attrs: ImmutableDict[str, str]

Wildcard attributes

bundle: Final[Bundle]

The Bundle containing this element

property description: str | None

description attribute

property domain: str

domain attribute

property domain_parts: tuple[str, str | None]

A tuple with the two parts of the domain.

If domain equals <main>#<sub> this is (<main>, <sub>). If domain does not contain a #, it equals (<domain>, None).

property encoding: str | None

encoding attribute: read-only, the encoding is automatically determined from the value

property name: NTG | None

The name attribute

property type_: str | None

Scalar type of the value, such as string, integer, decimal, or boolean.

property value: PT

value attribute: The content.

Setting value to None will generate a node with a <none/> tag. Set value to NO_CONTENT to create an empty content node.

When accessing, raises NoContent if no content was set instead of returning NO_CONTENT, raises AttachmentContent if the node refers to an attachment using src.

Property

A property is a named value in a product or a result, such as a status or a score reported by a checklet.

class momotor.bundles.elements.properties.Property(bundle)

A Property element encapsulating PropertyComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[PropertyComplexType]

create(*, name, value=None, type_=None, accept=None, attrs=None)

Initialize a named result property.

Parameters:
  • name (str) – Property name.

  • value (Any) – Python value. None represents an explicit XML <none/> value.

  • type – Scalar type name. Omission infers the type from the value.

  • accept (str | None) – Optional comparison rule from PropertyComplexTypeAccept.

  • attrs (Mapping[str, str] | None) – Additional XML attributes keyed by their qualified names.

Return type:

Self

Returns:

This initialized element.

has_attachment_content()

Check if element has attachment content.

Return type:

bool

Returns:

True if this element has an existing attachment

has_inline_content()

Check if element has inline content without processing it.

Return type:

bool

Returns:

True if element has any form of inline content (value attribute, raw content, processed value, or encoding)

has_inline_text_content()

Check if element has inline text content without processing it.

Return type:

bool

Returns:

True if the value property would return text content (bytes or str) without actually converting the content

has_text_content()

Check if element has any form of text content.

Return type:

bool

Returns:

True if the element has text content, either inline or as attachment, without processing the content

recreate(target_bundle, *, name=<object object>, value=<object object>, type_=<object object>, accept=<object object>, attrs=<object object>)

Recreate this Property in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Existing raw or encoded content is preserved when neither value nor type_ is replaced.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • name (str) – New name for the property

  • value (Any) – New value for the property

  • type – New type for the property, or None to clear it

  • accept (str | None) – New accept mode, or None to clear it

  • attrs (Mapping[str, str] | None) – New attributes, or None to clear them

Return type:

Self

Returns:

The recreated Property

HAS_ENCODING: ClassVar[bool] = True
MAX_VALUE_LENGTH: ClassVar = 1000
VALID_PROCESSED_TYPES: ClassVar[tuple[type, ...]] = (<class 'str'>, <class 'bool'>, <class 'bytes'>, <class 'int'>, <class 'float'>, <class 'decimal.Decimal'>)
property accept: str | None

accept attribute

property attrs: ImmutableDict[str, str]

Wildcard attributes

bundle: Final[Bundle]

The Bundle containing this element

property encoding: str | None

encoding attribute: read-only, the encoding is automatically determined from the value

property name: NTG | None

The name attribute

property type_: str | None

Scalar type of the value, such as string, integer, decimal, or boolean.

property value: PT

value attribute: The content.

Setting value to None will generate a node with a <none/> tag. Set value to NO_CONTENT to create an empty content node.

When accessing, raises NoContent if no content was set instead of returning NO_CONTENT, raises AttachmentContent if the node refers to an attachment using src.

Resource

A resource is a named value that a step or checklet declares for the engine, stored as text in the bundle XML.

class momotor.bundles.elements.resources.Resource(bundle)

A Resource element encapsulating ResourceComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[ResourceComplexType]

create(*, name, value=None)

Initialize a named resource declaration.

Parameters:
  • name (str) – Resource name interpreted by the engine.

  • value (str | None) – Resource value, or None for an explicit null.

Return type:

Self

Returns:

This initialized element.

has_attachment_content()

Check if element has attachment content.

Return type:

bool

Returns:

True if this element has an existing attachment

has_inline_content()

Check if element has inline content without processing it.

Return type:

bool

Returns:

True if element has any form of inline content (value attribute, raw content, processed value, or encoding)

has_inline_text_content()

Check if element has inline text content without processing it.

Return type:

bool

Returns:

True if the value property would return text content (bytes or str) without actually converting the content

has_text_content()

Check if element has any form of text content.

Return type:

bool

Returns:

True if the element has text content, either inline or as attachment, without processing the content

recreate(target_bundle, *, name=<object object>, value=<object object>)

Recreate this Resource in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • name (str) – New name for the resource

  • value (str | None) – New value for the resource, or None to clear it

Return type:

Self

Returns:

The recreated Resource

HAS_ENCODING: ClassVar[bool] = False
MAX_VALUE_LENGTH: ClassVar = 1000
VALID_PROCESSED_TYPES: ClassVar[tuple[type, ...]] = (<class 'str'>, <class 'bool'>)
bundle: Final[Bundle]

The Bundle containing this element

property name: NTG | None

The name attribute

property value: PT

value attribute: The content.

Setting value to None will generate a node with a <none/> tag. Set value to NO_CONTENT to create an empty content node.

When accessing, raises NoContent if no content was set instead of returning NO_CONTENT, raises AttachmentContent if the node refers to an attachment using src.

Result

A result records the outcome of one recipe step, with its properties, options, and output files.

class momotor.bundles.elements.result.Result(bundle)

A Result element encapsulating ResultComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[ResultComplexType]

copy_files_to(destination, *, files=None)

Copy files attached using the files nodes to a directory

Copies are incremental. A failure retains earlier successful copies and does not remove pre-existing files or overwrite existing targets.

Parameters:
  • destination (Path) – destination for the files

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

Return type:

None

create(*, step_id, outcome, properties=None, options=None, files=None, parent_id=None)

Initialize the execution result for a step.

Parameters:
  • step_id (str) – Step or task identifier.

  • outcome (str | Outcome) – pass, fail, skip, error, or an Outcome member.

  • properties (Iterable[Property] | None) – Result properties owned by this bundle.

  • options (Iterable[Option] | None) – Result options owned by this bundle.

  • files (Iterable[File] | None) – Result files owned by this bundle.

  • parent_id (str | None) – Optional identifier of the containing results group.

Return type:

Self

Returns:

This initialized element.

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

recreate(target_bundle, *, step_id=<object object>, outcome=<object object>, properties=<object object>, options=<object object>, files=<object object>, parent_id=<object object>)

Recreate this Result in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. The original properties, options, and files are recreated in the target bundle. Explicitly passing None for one of those collections clears it.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • step_id (str) – New step_id for the result

  • outcome (str | Outcome) – New outcome for the result

  • properties (Iterable[Property] | None) – New properties for the result, or None to clear them

  • options (Iterable[Option] | None) – New options for the result, or None to clear them

  • files (Iterable[File] | None) – New files for the result, or None to clear them

  • parent_id (str | None) – New parent id for the result, or None to clear it

Return type:

Self

Returns:

The recreated Result

Changed in version 8.3.0: All fields can be replaced. Earlier versions only allowed replacing step_id. All other fields were copied unchanged.

set_parent_id(parent_id)

Set the id of the result parent

bundle

The Bundle containing this element

property erred: bool

Returns True if outcome_enum is ERROR

property failed: bool

Returns True if outcome_enum is FAIL

property files: FilterableTuple[File]

files children

property options: FilterableTuple[Option]

options children

property outcome: Literal['pass', 'fail', 'skip', 'error']

outcome attribute as string value. Valid values are pass, fail, skip and error

property outcome_enum: Outcome

outcome attribute as an Outcome enum

property passed: bool

Returns True if outcome_enum is PASS

property properties: FilterableTuple[Property]

properties children

property skipped: bool

Returns True if outcome_enum is SKIP

property step_id: str

step_id attribute

class momotor.bundles.elements.results.Results(bundle)

A Results element encapsulating ResultsComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[ResultsComplexType]

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

Initialize a collection of execution results.

Parameters:
  • id (str | None) – Optional results identifier.

  • meta (Meta | None) – Optional metadata.

  • results (Iterable[Result] | None) – Result elements owned by this bundle. Step identifiers must be unique.

Return type:

Self

Returns:

This initialized element.

recreate(target_bundle, *, id=<object object>, meta=<object object>, results=<object object>)

Recreate these results in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Original metadata and results are recreated so they belong to the target bundle. Recreated child results receive the recreated parent id.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • id (str | None) – New results id, or None to clear it

  • meta (Meta | None) – New metadata, or None to clear it

  • results (Iterable[Result] | None) – New results, or None to clear them

Return type:

Self

Returns:

The recreated results

bundle

The Bundle containing this element

property id: str | None

The id attribute

property meta: Meta

meta attribute

property results: ResultKeyedTuple

results children

class momotor.bundles.elements.result.Outcome(value)

An enum for the Result.outcome. Mirrors OutcomeSimpleType

classmethod condition(state)

Get outcome based on a condition

Return type:

Self

Returns:

returns Outcome.PASS if state is truthy, otherwise returns Outcome.FAIL

classmethod from_simpletype(st)

Create an Outcome from an OutcomeSimpleType

Return type:

Self

to_simpletype()

Convert into an OutcomeSimpleType

Return type:

OutcomeSimpleType

ERROR = 'error'
FAIL = 'fail'
PASS = 'pass'
SKIP = 'skip'
class momotor.bundles.elements.results.ResultKeyedTuple(results=None)

The results as a KeyedTuple of Result objects.

The KeyedTuple allows access as a tuple or a mapping. Results are indexed by their step_id attribute

Step

A step is one processing step in a recipe. It names the checklet to run and the steps it depends on.

class momotor.bundles.elements.steps.Step(bundle)

A Step element encapsulating StepComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[StepComplexType]

copy_files_to(destination, *, files=None)

Copy files attached using the files nodes to a directory

Copies are incremental. A failure retains earlier successful copies and does not remove pre-existing files or overwrite existing targets.

Parameters:
  • destination (Path) – destination for the files

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

Return type:

None

create(*, id, meta=None, priority='default', depends=None, checklet=None, options=None, files=None, resources=None)

Initialize a recipe step and its inputs.

Parameters:
  • id (str) – Step identifier.

  • meta (Meta | None) – Optional step metadata.

  • priority (str) – One of must-pass, high, normal, default, or low.

  • depends (Iterable[Depends] | None) – Dependency elements owned by this bundle.

  • checklet (Checklet | None) – Checklet owned by this bundle, or None.

  • options (Iterable[Option] | None) – Option elements owned by this bundle.

  • files (Iterable[File] | None) – File elements owned by this bundle.

  • resources (Iterable[Resource] | None) – Resource declarations owned by this bundle.

Return type:

Self

Returns:

This initialized element.

get_dependencies_ids()

ids of the dependencies

Return type:

Generator[str, None, None]

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_resources()

get all resources needed by this step

Return type:

dict[str, FilterableTuple[Resource]]

recreate(target_bundle, *, id=<object object>, meta=<object object>, priority=<object object>, depends=<object object>, checklet=<object object>, options=<object object>, files=<object object>, resources=<object object>)

Recreate this Step in a target bundle, optionally replacing any field.

Fields that are not provided are copied unchanged. Original child elements are recreated so they belong to the target bundle.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • id (str) – New id for the step

  • meta (Meta | None) – New metadata, or None to clear it

  • priority (str) – New priority

  • depends (Iterable[Depends] | None) – New dependencies, or None to clear them

  • checklet (Checklet | None) – New checklet, or None to clear it

  • options (Iterable[Option] | None) – New options, or None to clear them

  • files (Iterable[File] | None) – New files, or None to clear them

  • resources (Iterable[Resource] | None) – New resources, or None to clear them

Return type:

Self

Returns:

The recreated Step

bundle

The Bundle containing this element

property checklet: Checklet | None

checklet

property depends: FilterableTuple[Depends] | None

depends

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 priority: str

priority attribute

property priority_value: Priority

priority attribute as Priority instance

property resources: FilterableTuple[Resource]

resources attribute

class momotor.bundles.elements.steps.Depends(bundle)

A Depends element encapsulating DependsComplexType

Parameters:

bundle (Bundle) – The Bundle containing this element

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

static get_node_type()

Return the generated XML binding class for this element.

Return type:

type[DependsComplexType]

create(*, step)

Initialize a dependency on another step.

Parameters:

step (str) – Dependency selector stored in the XML step attribute.

Return type:

Self

Returns:

This initialized element.

recreate(target_bundle, *, step=<object object>)

Recreate this Depends in a target bundle, optionally replacing its step.

Parameters:
  • target_bundle (Bundle) – The target bundle

  • step (str) – New step id

Return type:

Self

Returns:

The recreated Depends

bundle: Final[Bundle]

The Bundle containing this element

property step: str

step attribute

class momotor.bundles.elements.steps.Priority(value)

An enum for the step priority

DEFAULT = 2
HIGH = 1
LOW = 3
MUST_PASS = 0
NORMAL = 2

Name type parameter

NTG denotes the name type returned by an element’s inherited name property.

momotor.bundles.mixins.name.NTG = ~NTG

Type variable.

Usage:

T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

Type variables exist primarily for the benefit of static type checkers. They serve as the parameters for generic types as well as for generic function definitions. See class Generic for more information on generic types. Generic functions work as follows:

def repeat(x: T, n: int) -> List[T]:

‘’’Return a list containing n references to x.’’’ return [x]*n

def longest(x: A, y: A) -> A:

‘’’Return the longest of two strings.’’’ return x if len(x) >= len(y) else y

The latter example’s signature is essentially the overloading of (str, str) -> str and (bytes, bytes) -> bytes. Also note that if the arguments are instances of some subclass of str, the return type is still plain str.

At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.

Type variables defined with covariant=True or contravariant=True can be used to declare covariant or contravariant generic types. See PEP 484 for more details. By default generic types are invariant in all type variables.

Type variables can be introspected. e.g.:

T.__name__ == ‘T’ T.__constraints__ == () T.__covariant__ == False T.__contravariant__ = False A.__constraints__ == (str, bytes)

Note that only type variables defined in global scope can be pickled.