Model

hexa.model

Summary

Shared neutral model for hexa port trees.

All utilities (parse_yaml, generate_abc, parse_abc, generate_yaml, check_matches) serialize through this single model.

---

Notes

• The model is NOT tied to any sample — any port tree fits.

Classes

MethodSpec dataclass

MethodSpec(
    name: str,
    args: list[str] = list(),
    kwargs: dict[str, str] = dict(),
)

Specification of a single abstract method.

Attributes:

Name	Type	Description
name	str	Name of the method.
args	list[str]	Positional parameter names.
kwargs	dict[str, str]	Keyword-only parameter names mapped to their type expressions.

PortNode dataclass

PortNode(
    name: str,
    port_cls: str,
    kind: str = "leaf",
    attributes: dict[str, ConfigValue] = dict(),
    children: list[PortNode] = list(),
    methods: dict[str, MethodSpec] = dict(),
)

A node in the hexa port tree.

Each node is a leaf (no children), a port (has nested port slots), or the parent root of the tree. Every node carries a concrete typed shape derived from an ABC class name.

Attributes:

Name	Type	Description
name	str	Slot name, e.g. "parser", "amount_balance".
port_cls	str	ABC class name that gives this port its shape, e.g. "TransactionParserPort". Every port has a concrete typed shape.
kind	str	One of "leaf", "port", or "parent". - "leaf": no children (e.g. NumberPort) - "port": has children (e.g. TransactionParserPort) - "parent": the root of the tree (e.g. ExtractionPipeline)
attributes	dict[str, ConfigValue]	Annotated attributes: name -> type_expr for scalars, or a nested dict of sub-attributes (a struct) for grouped values.
children	list[PortNode]	Nested port slots.
methods	dict[str, MethodSpec]	Abstract methods keyed by method name.

Functions

diff

diff(other: PortNode, path: str = '') -> list[str]

Return a list of human-readable difference strings.

An empty list means the trees are equal.

Parameters:

Name	Type	Description	Default
other	PortNode	Tree to compare against.	required
path	str	Path prefix used when recursing into nested nodes; defaults to the root path.	''

Returns:

Type	Description
list[str]	list[str]: Human-readable difference strings, one per discrepancy.

find

find(name: str) -> PortNode | None

Find a direct child by slot name.

Parameters:

Name	Type	Description	Default
name	str	Slot name of the child to look up.	required

Returns:

Type	Description
PortNode | None	PortNode | None: The matching child node, or None if no child has that name.

walk

walk() -> list[PortNode]

Return all nodes in depth-first order (self first).

Returns:

Type	Description
list[PortNode]	list[PortNode]: All nodes of the tree, self first, depth-first.