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:
tag_name (
Literal['file','option','checklet']) – Expected schema element name.node (
TypeVar(CT, bound=FileComplexType|OptionComplexType|CheckletComplexType)) – Original binding occurrence.groups (
Iterable[Iterable[object]]) – Ordered definition containers to search.
- 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.