Rename spread to map

dmontagu · dmontagu · commit 96511843fbfb · 2025-10-03T13:05:34.000-06:00
diff --git a/pydantic_graph/pydantic_graph/beta/decision.py b/pydantic_graph/pydantic_graph/beta/decision.py
@@ -112,7 +112,7 @@ class DecisionBranch(Generic[SourceT]):
     path: Path
     """The execution path to follow when an input value matches this branch of a decision node.
 
-    This can include transforming, spreading, and broadcasting the output before sending to the next node or nodes.
+    This can include transforming, mapping, and broadcasting the output before sending to the next node or nodes.
 
     The path can also include position-aware labels which are used when generating mermaid diagrams."""
 
@@ -211,7 +211,7 @@ def transform(
             path_builder=self.path_builder.transform(func),
         )
 
-    def spread(
+    def map(
         self: DecisionBranchBuilder[StateT, DepsT, Iterable[T], SourceT, HandledT],
         *,
         fork_id: ForkID | None = None,
@@ -224,16 +224,16 @@ def spread(
 
         Args:
             fork_id: Optional ID for the fork, defaults to a generated value
-            downstream_join_id: Optional ID of a downstream join node which is involved when spreading empty iterables
+            downstream_join_id: Optional ID of a downstream join node which is involved when mapping empty iterables
 
         Returns:
-            A new DecisionBranchBuilder where spreading is performed prior to generating the final output.
+            A new DecisionBranchBuilder where mapping is performed prior to generating the final output.
         """
         return DecisionBranchBuilder(
             decision=self.decision,
             source=self.source,
             matches=self.matches,
-            path_builder=self.path_builder.spread(fork_id=fork_id, downstream_join_id=downstream_join_id),
+            path_builder=self.path_builder.map(fork_id=fork_id, downstream_join_id=downstream_join_id),
         )
 
     def label(self, label: str) -> DecisionBranchBuilder[StateT, DepsT, OutputT, SourceT, HandledT]:
diff --git a/pydantic_graph/pydantic_graph/beta/graph.py b/pydantic_graph/pydantic_graph/beta/graph.py
@@ -659,23 +659,23 @@ def _handle_path(self, path: Path, inputs: Any, fork_stack: ForkStack) -> Sequen
             try:
                 iter(inputs)
             except TypeError:
-                raise RuntimeError(f'Cannot spread non-iterable value: {inputs!r}')
+                raise RuntimeError(f'Cannot map non-iterable value: {inputs!r}')
 
             node_run_id = NodeRunID(str(uuid.uuid4()))
 
-            # If the spread specifies a downstream join id, eagerly create a reducer for it
+            # If the map specifies a downstream join id, eagerly create a reducer for it
             if item.downstream_join_id is not None:
                 join_node = self.graph.nodes[item.downstream_join_id]
                 assert isinstance(join_node, Join)
                 self._active_reducers[(item.downstream_join_id, node_run_id)] = join_node.create_reducer(), fork_stack
 
-            spread_tasks: list[GraphTask] = []
+            map_tasks: list[GraphTask] = []
             for thread_index, input_item in enumerate(inputs):
                 item_tasks = self._handle_path(
                     path.next_path, input_item, fork_stack + (ForkStackItem(item.fork_id, node_run_id, thread_index),)
                 )
-                spread_tasks += item_tasks
-            return spread_tasks
+                map_tasks += item_tasks
+            return map_tasks
         elif isinstance(item, BroadcastMarker):
             return [GraphTask(item.fork_id, inputs, fork_stack)]
         elif isinstance(item, TransformMarker):
diff --git a/pydantic_graph/pydantic_graph/beta/graph_builder.py b/pydantic_graph/pydantic_graph/beta/graph_builder.py
@@ -344,7 +344,7 @@ def add(self, *edges: EdgePath[StateT, DepsT]) -> None:
         """Add one or more edge paths to the graph.
 
         This method processes edge paths and automatically creates any necessary
-        fork nodes for broadcasts and spreads.
+        fork nodes for broadcasts and maps.
 
         Args:
             *edges: The edge paths to add to the graph
@@ -358,12 +358,12 @@ def _handle_path(p: Path):
             """
             for item in p.items:
                 if isinstance(item, BroadcastMarker):
-                    new_node = Fork[Any, Any](id=item.fork_id, is_spread=False)
+                    new_node = Fork[Any, Any](id=item.fork_id, is_map=False)
                     self._insert_node(new_node)
                     for path in item.paths:
                         _handle_path(Path(items=[*path.items]))
                 elif isinstance(item, SpreadMarker):
-                    new_node = Fork[Any, Any](id=item.fork_id, is_spread=True)
+                    new_node = Fork[Any, Any](id=item.fork_id, is_map=True)
                     self._insert_node(new_node)
                 elif isinstance(item, DestinationMarker):
                     pass
@@ -407,34 +407,34 @@ def add_edge(self, source: Source[T], destination: Destination[T], *, label: str
             builder = builder.label(label)
         self.add(builder.to(destination))
 
-    def add_spreading_edge(
+    def add_mapping_edge(
         self,
         source: Source[Iterable[T]],
-        spread_to: Destination[T],
+        map_to: Destination[T],
         *,
-        pre_spread_label: str | None = None,
-        post_spread_label: str | None = None,
+        pre_map_label: str | None = None,
+        post_map_label: str | None = None,
         fork_id: ForkID | None = None,
         downstream_join_id: JoinID | None = None,
     ) -> None:
-        """Add an edge that spreads iterable data across parallel paths.
+        """Add an edge that maps iterable data across parallel paths.
 
         Args:
             source: The source node that produces iterable data
-            spread_to: The destination node that receives individual items
-            pre_spread_label: Optional label before the spread operation
-            post_spread_label: Optional label after the spread operation
-            fork_id: Optional ID for the fork node produced for this spread operation
-            downstream_join_id: Optional ID of a join node that will always be downstream of this spread.
-                Specifying this ensures correct handling if you try to spread an empty iterable.
+            map_to: The destination node that receives individual items
+            pre_map_label: Optional label before the map operation
+            post_map_label: Optional label after the map operation
+            fork_id: Optional ID for the fork node produced for this map operation
+            downstream_join_id: Optional ID of a join node that will always be downstream of this map.
+                Specifying this ensures correct handling if you try to map an empty iterable.
         """
         builder = self.edge_from(source)
-        if pre_spread_label is not None:
-            builder = builder.label(pre_spread_label)
-        builder = builder.spread(fork_id=fork_id, downstream_join_id=downstream_join_id)
-        if post_spread_label is not None:
-            builder = builder.label(post_spread_label)
-        self.add(builder.to(spread_to))
+        if pre_map_label is not None:
+            builder = builder.label(pre_map_label)
+        builder = builder.map(fork_id=fork_id, downstream_join_id=downstream_join_id)
+        if post_map_label is not None:
+            builder = builder.label(post_map_label)
+        self.add(builder.to(map_to))
 
     # TODO(P2): Support adding subgraphs ... not sure exactly what that looks like yet..
     #  probably similar to a step, but with some tweaks
@@ -590,17 +590,17 @@ def _get_new_broadcast_id(self, from_: str | None = None) -> str:
             index += 1
         return node_id
 
-    def _get_new_spread_id(self, from_: str | None = None, to: str | None = None) -> str:
-        """Generate a unique ID for a new spread fork.
+    def _get_new_map_id(self, from_: str | None = None, to: str | None = None) -> str:
+        """Generate a unique ID for a new map fork.
 
         Args:
             from_: Optional source identifier to include in the ID
             to: Optional destination identifier to include in the ID
 
         Returns:
-            A unique spread fork ID
+            A unique map fork ID
         """
-        prefix = 'spread'
+        prefix = 'map'
         if from_ is not None:
             prefix += f'_from_{from_}'
         if to is not None:
@@ -744,13 +744,13 @@ def _normalize_forks(
         paths_to_handle.extend(edges_from_source)
 
         node = nodes[source_id]
-        if isinstance(node, Fork) and not node.is_spread:
+        if isinstance(node, Fork) and not node.is_map:
             new_edges[source_id] = edges_from_source
             continue  # broadcast fork; nothing to do
         if len(edges_from_source) == 1:
             new_edges[source_id] = edges_from_source
             continue
-        new_fork = Fork[Any, Any](id=ForkID(NodeID(f'{node.id}_broadcast_fork')), is_spread=False)
+        new_fork = Fork[Any, Any](id=ForkID(NodeID(f'{node.id}_broadcast_fork')), is_map=False)
         new_nodes[new_fork.id] = new_fork
         new_edges[source_id] = [Path(items=[BroadcastMarker(fork_id=new_fork.id, paths=edges_from_source)])]
         new_edges[new_fork.id] = edges_from_source
@@ -764,7 +764,7 @@ def _normalize_forks(
             if isinstance(item, BroadcastMarker):
                 assert item.fork_id in new_nodes
                 # if item.fork_id not in new_nodes:
-                #     new_nodes[new_fork.id] = Fork[Any, Any](id=item.fork_id, is_spread=False)
+                #     new_nodes[new_fork.id] = Fork[Any, Any](id=item.fork_id, is_map=False)
                 new_edges[item.fork_id] = [*item.paths]
                 paths_to_handle.extend(item.paths)
 
diff --git a/pydantic_graph/pydantic_graph/beta/mermaid.py b/pydantic_graph/pydantic_graph/beta/mermaid.py
@@ -27,7 +27,7 @@
 - `'BT'`: Bottom to top
 """
 
-NodeKind = Literal['broadcast', 'spread', 'join', 'start', 'end', 'step', 'decision', 'base_node']
+NodeKind = Literal['broadcast', 'map', 'join', 'start', 'end', 'step', 'decision', 'base_node']
 
 
 @dataclass
@@ -59,7 +59,7 @@ def _collect_edges(path: Path, last_source_id: NodeID) -> None:
         for item in path.items:
             if isinstance(item, SpreadMarker):
                 edges_by_source[last_source_id].append(MermaidEdge(last_source_id, item.fork_id, working_label))
-                return  # spread markers correspond to nodes already in the graph; downstream gets handled separately
+                return  # map markers correspond to nodes already in the graph; downstream gets handled separately
             elif isinstance(item, BroadcastMarker):
                 edges_by_source[last_source_id].append(MermaidEdge(last_source_id, item.fork_id, working_label))
                 return  # broadcast markers correspond to nodes already in the graph; downstream gets handled separately
@@ -82,7 +82,7 @@ def _collect_edges(path: Path, last_source_id: NodeID) -> None:
         elif isinstance(node, Join):
             kind = 'join'
         elif isinstance(node, Fork):
-            kind = 'spread' if node.is_spread else 'broadcast'
+            kind = 'map' if node.is_map else 'broadcast'
         elif isinstance(node, Decision):
             kind = 'decision'
             note = node.note
@@ -143,7 +143,7 @@ def render(
                 node_lines.append(line)
             elif node.kind == 'join':
                 node_lines = [f'  state {node.id} <<join>>']
-            elif node.kind == 'broadcast' or node.kind == 'spread':
+            elif node.kind == 'broadcast' or node.kind == 'map':
                 node_lines = [f'  state {node.id} <<fork>>']
             elif node.kind == 'decision':
                 node_lines = [f'  state {node.id} <<choice>>']
diff --git a/pydantic_graph/pydantic_graph/beta/node.py b/pydantic_graph/pydantic_graph/beta/node.py
@@ -66,14 +66,14 @@ class Fork(Generic[InputT, OutputT]):
     """Fork node that creates parallel execution branches.
 
     A Fork node splits the execution flow into multiple parallel branches,
-    enabling concurrent execution of downstream nodes. It can either spread
+    enabling concurrent execution of downstream nodes. It can either map
     a sequence across multiple branches or duplicate data to each branch.
     """
 
     id: ForkID
     """Unique identifier for this fork node."""
 
-    is_spread: bool
+    is_map: bool
     """Determines fork behavior.
 
     If True, InputT must be Sequence[OutputT] and each element is sent to a separate branch.
diff --git a/pydantic_graph/pydantic_graph/beta/paths.py b/pydantic_graph/pydantic_graph/beta/paths.py
@@ -1,7 +1,7 @@
 """Path and edge definition for graph navigation.
 
 This module provides the building blocks for defining paths through a graph,
-including transformations, spreads, broadcasts, and routing to destinations.
+including transformations, maps, broadcasts, and routing to destinations.
 Paths enable complex data flow patterns in graph execution.
 """
 
@@ -41,16 +41,16 @@ class TransformMarker:
 
 @dataclass
 class SpreadMarker:
-    """A marker indicating that iterable data should be spread across parallel paths.
+    """A marker indicating that iterable data should be map across parallel paths.
 
     Spread markers take iterable input and create parallel execution paths
     for each item in the iterable.
     """
 
     fork_id: ForkID
-    """Unique identifier for the fork created by this spread operation."""
+    """Unique identifier for the fork created by this map operation."""
     downstream_join_id: JoinID | None
-    """Optional identifier of a downstream join node that should be jumped to if spreading an empty iterable."""
+    """Optional identifier of a downstream join node that should be jumped to if mapping an empty iterable."""
 
 
 @dataclass
@@ -109,7 +109,7 @@ class Path:
 
     @property
     def last_fork(self) -> BroadcastMarker | SpreadMarker | None:
-        """Get the most recent fork or spread marker in this path.
+        """Get the most recent fork or map marker in this path.
 
         Returns:
             The last BroadcastMarker or SpreadMarker in the path, or None if no forks exist
@@ -134,7 +134,7 @@ class PathBuilder(Generic[StateT, DepsT, OutputT]):
     """A builder for constructing paths with method chaining.
 
     PathBuilder provides a fluent interface for creating paths by chaining
-    operations like transforms, spreads, and routing to destinations.
+    operations like transforms, maps, and routing to destinations.
 
     Type Parameters:
         StateT: The type of the graph state
@@ -147,7 +147,7 @@ class PathBuilder(Generic[StateT, DepsT, OutputT]):
 
     @property
     def last_fork(self) -> BroadcastMarker | SpreadMarker | None:
-        """Get the most recent fork or spread marker in the working path.
+        """Get the most recent fork or map marker in the working path.
 
         Returns:
             The last BroadcastMarker or SpreadMarker in the working items, or None if no forks exist
@@ -208,7 +208,7 @@ def transform(self, func: StepFunction[StateT, DepsT, OutputT, Any], /) -> PathB
         next_item = TransformMarker(func)
         return PathBuilder[StateT, DepsT, Any](working_items=[*self.working_items, next_item])
 
-    def spread(
+    def map(
         self: PathBuilder[StateT, DepsT, Iterable[Any]],
         *,
         fork_id: ForkID | None = None,
@@ -221,13 +221,13 @@ def spread(
 
         Args:
             fork_id: Optional ID for the fork, defaults to a generated value
-            downstream_join_id: Optional ID of a downstream join node which is involved when spreading empty iterables
+            downstream_join_id: Optional ID of a downstream join node which is involved when mapping empty iterables
 
         Returns:
             A new PathBuilder that operates on individual items from the iterable
         """
         next_item = SpreadMarker(
-            fork_id=NodeID(fork_id or 'spread_' + secrets.token_hex(8)), downstream_join_id=downstream_join_id
+            fork_id=NodeID(fork_id or 'map_' + secrets.token_hex(8)), downstream_join_id=downstream_join_id
         )
         return PathBuilder[StateT, DepsT, Any](working_items=[*self.working_items, next_item])
 
@@ -365,7 +365,7 @@ def to(
                 destinations=destinations,
             )
 
-    def spread(
+    def map(
         self: EdgePathBuilder[StateT, DepsT, Iterable[Any]],
         *,
         fork_id: ForkID | None = None,
@@ -375,14 +375,14 @@ def spread(
 
         Args:
             fork_id: Optional ID for the fork, defaults to a generated value
-            downstream_join_id: Optional ID of a downstream join node which is involved when spreading empty iterables
+            downstream_join_id: Optional ID of a downstream join node which is involved when mapping empty iterables
 
         Returns:
             A new EdgePathBuilder that operates on individual items from the iterable
         """
         return EdgePathBuilder(
             sources=self.sources,
-            path_builder=self.path_builder.spread(fork_id=fork_id, downstream_join_id=downstream_join_id),
+            path_builder=self.path_builder.map(fork_id=fork_id, downstream_join_id=downstream_join_id),
         )
 
     def transform(self, func: StepFunction[StateT, DepsT, OutputT, Any], /) -> EdgePathBuilder[StateT, DepsT, Any]:
