Refs

A reference lets you define an element once and reuse it in several places. Use a reference when the same file, checklet, or option would otherwise be repeated in a bundle.

In bundle XML, the definition carries an id attribute. Each reuse is an empty element with a ref attribute that contains that ID:

<checklets>
  <checklet id="score-chk" name="generate-score"/>
</checklets>
<steps>
  <step id="step1">
    <checklet ref="score-chk"/>
  </step>
</steps>

The ref attribute is supported by the <file>, <checklet>, and <option> elements. An element with ref must not have any other attributes or child elements. The definition can appear before or after the reference.

Each bundle has its own reference scope: an ID is looked up only within that scope. Bundles embedded in self-tests, mock results, and each report case’s diagnostic files have separate scopes, so the same ID can be reused in different scopes.

You do not resolve references yourself. When you read elements through this package’s Python API, a reference returns the element it refers to. A reference to a missing, ambiguous, or wrong-type target raises InvalidRefError.

Changed in version 9.0.0: References resolve in every bundle type, including forward references to definitions that appear later in the same scope.

Note

Bundle export methods create ref nodes when deduplicate=True. This keyword-only option defaults to False and replaces identical <file>, <option>, and <checklet> definitions with references. It is independent of optimize.

deduplicate_attachments=True also shares identical external attachment payloads and requires deduplicate=True. See Bundles for the deduplication options and compatibility requirements.

API

Typed reference resolution with existing higher-level inheritance precedence.

momotor.bundles.elements.refs.resolve_ref(tag_name, node, groups)

Resolve a reference in explicit higher-level groups.

Parameters:
Return type:

tuple[FilesComplexType | OptionsComplexType | CheckletsComplexType | None, TypeVar(CT, bound= FileComplexType | OptionComplexType | CheckletComplexType)]

Returns:

Target container and terminal binding node.

Raises:

InvalidRefError – For missing, ambiguous, mistyped or cyclic targets.