Mappings¶
zeroth.contracts.mappings ¶
Data mapping contracts.
This package provides tools to define how data flows between nodes in a graph. You can describe what fields to copy, rename, set to fixed values, or give defaults, then validate and run those mappings against real data.
MappingExecutionError ¶
Bases: ValueError
Raised when a mapping operation fails during execution.
For example, this is raised when a transform expression encounters a division by zero, type error, or references an unsupported AST construct.
MappingExecutor ¶
Apply validated mapping operations sequentially.
Use this class when you want to transform an input dictionary into an output
dictionary according to a set of mapping rules (an EdgeMapping). The
executor first validates the mapping and then runs each operation in order.
execute ¶
execute(
payload: Mapping[str, Any],
mapping: EdgeMapping,
*,
context: Mapping[str, Any] | None = None,
) -> dict[str, Any]
Run all mapping operations against the given payload and return the result.
The payload is the input data (read-only). A brand-new dictionary is built up by applying each operation and then returned.
An optional context keyword argument provides the full namespace
for transform expressions (payload, state, variables, etc.). When
omitted, a minimal namespace is built from payload alone.
ConstantMappingOperation ¶
Bases: MappingOperationBase
Set a target field to a fixed value, ignoring the input entirely.
Useful when you always want a specific value in the output regardless of what the input contains.
DefaultMappingOperation ¶
Bases: MappingOperationBase
Copy a value from the input, falling back to a default if it is missing.
If source_path is None, the default value is always used. Otherwise
the source is looked up first, and the default is only used when the source
path does not exist in the input.
EdgeMapping ¶
Bases: BaseModel
A complete set of mapping operations that describe one edge's data transform.
An EdgeMapping groups together all the individual operations that should
run when data crosses a particular edge in the graph.
PassthroughMappingOperation ¶
Bases: MappingOperationBase
Copy a value from the input to the output without changing it.
The source and target paths are the same logical field, just moved across the edge boundary.
RenameMappingOperation ¶
Bases: MappingOperationBase
Copy a value from the input to the output under a different name.
Works just like passthrough, but the target path can differ from the source path, effectively renaming the field.
TransformMappingOperation ¶
Bases: MappingOperationBase
Evaluate an expression and write the computed result to target_path.
The expression is evaluated using the safe AST-based evaluator against a
namespace containing payload, state, variables, and other
runtime context. This enables side-effect-free data transformation
between nodes.
MappingValidationError ¶
Bases: ValueError
Raised when an edge mapping definition is invalid.
For example, this is raised if a mapping has an empty path, a duplicate
target, or no operations at all. It inherits from ValueError so you can
catch it with a broad except ValueError if needed.
MappingValidator ¶
Validate edge mapping definitions before execution.
Call validate() with an EdgeMapping to make sure all its operations
are correct. If anything is wrong, a MappingValidationError is raised
with a message explaining the problem.
validate ¶
Validate an entire edge mapping.
Checks that there is at least one operation, that every path is well-formed, and that no two operations write to the same target path.