marsh.element

Tools for working with the raw JSON-like data.

This type of data is refered to as element in the marsh framework. It is what is produced when marshaling a python value and it is given as input when unmarshaling a python type.

ElementType: TypeAlias = Union[None, int, float, bool, str, Sequence[ElementType], Mapping[str, ElementType]]

A type alias for any element value.

SequenceElementType: TypeAlias = Sequence[ElementType]

A type alias for a sequence element value.

MappingElementType: TypeAlias = Mapping[str, ElementType]

A type alias for a mapping element value.

TerminalElementType: TypeAlias = Union[None, int, float, bool, str]

A type alias for a terminal element value.

merge(element, *elements, concatenate=False)

Combine two or more elements.

Maps are combined recursively. All other types of values are replaced with the last element in the merge (with an exception for sequences if concatenate is True). The final element in the inputs will be given the highest priority in the merge, i.e. if it contains a value for a specific path that exists in other elements in the input its value will be the one that exists in the final merged element (output).

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The first element.

• elements (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – Remaining elements to merge into the first element.

• concatenate (bool) – Concatenate sequences with eachother when merging instead of replacing the old sequence with the new sequence.

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

A new element which is the combination of all input elements.

override(element, value, path, combine=False)

Set the value of a specific path in an element.

If the path is already occupied by a value, it will be replaced. A copy of the input element is returned with the value set for the specified path.

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The input element.

• value (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The value to set for the path.

• path (str) – The path for the new value.

• combine (bool) – If a previous value exists for the path, attempt to merge it with the new value. This only applies when both values are maps or sequences. For maps, the new element takes precedence when a key exists in both values. For sequences, the old value is concatenated with the new value (old + new).

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

A copy of the element with a new value set for the specified path.

remove(element, path)

Remove a subelement in the input specified by a path.

A copy of the input element is returned with the final subelement referenced by the path removed.

Parameters:

• element (Union[Sequence[Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]], Mapping[str, Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]]]) – The element containing a value to be removed.

• path (str) –

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

A copy of the element with the value for the specified path removed.

select(element, path)

Retrieve the value for a specific path in an element.

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The input element to retrieve a value from.

• path (str) – The path to retrieve the value from.

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

Value for the specified path.

iterative_select(element, path)

Iterate through all elements in a specified path.

At each step in the path a selection is yielded containing the current element, the path traversed and the remaining untraversed path.

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The input element to yield subelements from based on the specified path.

• path (str) – The path to traverse.

Return type:

Iterator[ElementSelection]

Returns:

Selection iterator.

standardize(element, *, mapping_type=<class 'dict'>, sequence_type=<class 'tuple'>)

Standardize the sequence/mapping types through an entire element.

Copy the element and replace all sequences with the specified sequence type and all mappings with the specified mapping type recursively.

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The element to standardize sequence and mapping types for.

• sequence_type (Type[Sequence]) – The type to use for sequences.

• mapping_type (Type[Mapping]) – The type to use for mappings.

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

The standardized element.

has_missing(element)

Recursively look for missing values in an element.

Returns True if the element is missing or contains any missing values, otherwise False is returned. A missing value is represented by marsh.MISSING or dataclasses.MISSING.

Parameters:

element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – Element to check for missing values in.

Return type:

bool

Returns:

Boolean representing if the element is missing or contains missing values.

resolve(element)

Resolve any variable interpolation using omegaconf resolvers.

Parameters:

element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The element to resolve any variable interpolations for.

Return type:

Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]

Returns:

The element with variable interpolations performed.

class ElementSelection(element, path, remaining_path)

Parameters:

• element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) –

• path (str) –

• remaining_path (str) –