Skip to content

graflo.plot

Drawing what a manifest declares, and what reconciling two of them would do.

Four families, all rendered through Graphviz (the plot extra):

  • :class:~graflo.plot.plotter.ManifestPlotter — a manifest as it stands: vertex types and their edges, vertices and their fields, resources and the vertices they feed, and each resource's actor pipeline.
  • :func:~graflo.plot.merge.plot_merge_preview — what merging two manifests would do, and every way the declarations could refuse.
  • :func:~graflo.plot.equivalence.plot_equivalence and :func:~graflo.plot.equivalence.plot_equivalences — one equivalence as four small graphs: its members, attributes, identity and lookups.
  • :func:~graflo.plot.merge3.plot_merge3_preview and :func:~graflo.plot.merge3.plot_history — where two branches of one lineage collided, and the commit DAG they collided on.

Each plot_* function has a build_* counterpart returning a plain :mod:networkx graph, so what would be drawn can be inspected — or asserted against — without Graphviz installed.

Example

from graflo.plot import ManifestPlotter ManifestPlotter(graph_manifest=manifest, fig_path="figs").plot_vc2vc()

Modules:

Name Description
dot

A Graphviz graph as graflo's figures build it, written out as DOT text.

equivalence

Draw one equivalence as four small graphs, each about one thing.

merge

Draw a merge preview: the declaration graph, with its conflicts marked.

merge3

Draw a three-way merge: where two branches met, and the lineage they met on.

plotter

Graph visualization utilities for schema and data structures.

render

Turning a networkx graph into a file, and the Graphviz details that needs.

Attributes

OUTPUT_FORMATS = ('svg', 'pdf', 'png', 'dot') module-attribute

__all__ = ['OUTPUT_FORMATS', 'ManifestPlotter', 'StackExhausted', 'build_equivalence_view', 'build_history_graph', 'build_merge3_graph', 'build_preview_graph', 'plot_equivalence', 'plot_equivalences', 'plot_history', 'plot_merge3_preview', 'plot_merge_preview'] module-attribute

Classes

ManifestPlotter

Main class for schema visualization.

This class provides methods to visualize different aspects of a graph database schema, including vertex collections, resources, and their relationships.

Attributes:

Name Type Description
fig_path

Path to save visualizations

config

Schema configuration

schema

Schema instance

name

Schema name

prefix

Prefix for output files

Source code in graflo/plot/plotter.py
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
class ManifestPlotter:
    """Main class for schema visualization.

    This class provides methods to visualize different aspects of a graph database
    schema, including vertex collections, resources, and their relationships.

    Attributes:
        fig_path: Path to save visualizations
        config: Schema configuration
        schema: Schema instance
        name: Schema name
        prefix: Prefix for output files
    """

    def __init__(
        self,
        config_filename: str | os.PathLike[str] | None = None,
        fig_path: str | os.PathLike[str] = ".",
        output_format: str = "pdf",
        output_dpi: int | None = None,
        graph_manifest: GraphManifest | None = None,
    ):
        """Initialize the schema plotter.

        Args:
            config_filename: Optional path to schema configuration file
            fig_path: Path to save visualizations
            graph_manifest: Optional pre-built graph manifest
        """
        self.fig_path = fig_path
        self.output_format = output_format.lower()
        self.output_dpi = output_dpi

        manifest: GraphManifest
        if graph_manifest is not None:
            manifest = graph_manifest
            self.config = None
        elif config_filename is not None:
            self.config = FileHandle.load(config_filename)
            manifest = GraphManifest.from_config(self.config)
        else:
            raise ValueError(
                "ManifestPlotter requires either `config_filename` or `graph_manifest`."
            )

        manifest.finish_init()
        self.schema = manifest.require_schema()
        self.ingestion_model = manifest.require_ingestion_model()

        # A label, not a filename: merged names carry "+" and may carry spaces.
        self.name = Schema._slug_filename_token(self.schema.metadata.name)
        self.prefix = self.name
        # The one index over the schema's declared adjacency. Built here so
        # every plot reads the same traversal rather than each deriving its
        # own from `vertex_config` / `edge_config`.
        self.schema_graph = SchemaGraph.from_schema(self.schema)

    def _figure_path(self, stem: str) -> str:
        return os.path.join(self.fig_path, f"{stem}.{self.output_format}")

    def _versioned_stem(self, stem: str) -> str:
        metadata = getattr(self.schema, "metadata", None)
        version = getattr(metadata, "version", None)
        if version is None:
            return stem
        return f"{stem}-v{version}"

    def _draw(self, ag, stem: str, prog: str = "dot") -> None:
        draw(
            ag,
            self._figure_path(stem),
            output_format=self.output_format,
            prog=prog,
            dpi=self.output_dpi,
        )

    def _discover_edges_from_resources(
        self,
    ) -> tuple[dict[EdgeId, Edge], dict[EdgeId, str], dict[EdgeId, bool]]:
        """Discover edges from resources by walking through ActorWrappers.

        This method finds all EdgeActors in resources and extracts their edges,
        which may include edges with dynamic relations (EdgeActor derivation) that
        aren't fully represented in edge_config.

        Returns:
            discovered_edges: map edge_id → Edge
            relation_source_by_edge_id: document field for per-row relation (plot hint).
            relation_from_key_by_edge_id: True when an edge step derives relation from keys.
        """
        discovered_edges: dict[EdgeId, Edge] = {}
        relation_source_by_edge_id: dict[EdgeId, str] = {}
        relation_from_key_by_edge_id: dict[EdgeId, bool] = {}

        for resource_config in self.ingestion_model.resources:
            actors = ActorWrapper(*resource_config.pipeline).collect_actors()

            for actor in actors:
                if isinstance(actor, EdgeActor):
                    edge = actor.edge
                    # Dynamic EdgeActors resolve types at row time; skip for plot discovery.
                    if edge is None:
                        continue
                    edge_id = edge.edge_id
                    # Store the edge, preferring already discovered edges from edge_config
                    # but allowing resource edges to supplement
                    if edge_id not in discovered_edges:
                        discovered_edges[edge_id] = edge
                    if actor.relation_field is not None:
                        relation_source_by_edge_id[edge_id] = actor.relation_field
                    if actor.derivation.relation_from_key:
                        relation_from_key_by_edge_id[edge_id] = True

        return (
            discovered_edges,
            relation_source_by_edge_id,
            relation_from_key_by_edge_id,
        )

    @staticmethod
    def _edge_label(
        edge: Edge,
        *,
        relation_source_field: str | None = None,
        relation_from_key: bool = False,
    ) -> str | None:
        """Build the human-readable edge label for plotting."""
        if edge.relation is not None:
            return edge.relation
        if relation_source_field is not None:
            return f"[{relation_source_field}]"
        if relation_from_key:
            return "[key]"
        return None

    @staticmethod
    def _merge_edges(primary_edges: dict, supplemental_edges: dict) -> dict:
        """Merge edge dictionaries without replacing existing primary edges."""
        merged = dict(primary_edges)
        for edge_id, edge in supplemental_edges.items():
            merged.setdefault(edge_id, edge)
        return merged

    @staticmethod
    def _filter_edges_with_known_vertices(
        edges: dict,
        known_vertices: set[str],
    ) -> tuple[dict, dict]:
        """Split edges by whether both endpoints are known vertices."""
        valid_edges = {}
        invalid_edges = {}
        for edge_id, edge in edges.items():
            source, target, _ = edge_id
            if source in known_vertices and target in known_vertices:
                valid_edges[edge_id] = edge
            else:
                invalid_edges[edge_id] = edge
        return valid_edges, invalid_edges

    @staticmethod
    def _style_nodes(
        graph: nx.MultiDiGraph | nx.DiGraph,
        *,
        force_labels: bool = False,
        partition_by_vertex: dict[str, str] | None = None,
        partition_color_map: dict[str, str] | None = None,
    ) -> None:
        """Apply common visual styles to graph nodes."""
        for node_id in graph.nodes():
            props = graph.nodes()[node_id]
            node_type = props.get("type")
            if node_type is None:
                logger.warning(
                    "Skipping node style; missing 'type' for node %s", node_id
                )
                continue

            shape = NODE_SHAPE_BY_TYPE.get(node_type)
            color = NODE_COLOR_BY_TYPE.get(node_type)
            if shape is None or color is None:
                logger.warning(
                    "Skipping node style; unsupported node type %s for node %s",
                    node_type,
                    node_id,
                )
                continue

            updates: dict[str, object] = {
                "shape": shape,
                "color": color,
                "fillcolor": color,
                "style": "filled",
            }
            if force_labels and "label" in props:
                updates["forcelabel"] = True

            if (
                partition_by_vertex
                and partition_color_map
                and isinstance(node_id, str)
                and node_id.startswith(f"{AuxNodeType.VERTEX}:")
            ):
                vertex_name = node_id.split(":", maxsplit=1)[1]
                group = partition_by_vertex.get(vertex_name)
                if group is not None and group in partition_color_map:
                    updates["fillcolor"] = partition_color_map[group]

            for key, value in updates.items():
                graph.nodes[node_id][key] = value

    @staticmethod
    def _style_edges(
        graph: nx.MultiDiGraph | nx.DiGraph,
        *,
        default_style: str = "solid",
        source_type_style_map: dict[AuxNodeType, str] | None = None,
    ) -> None:
        """Apply common visual styles to graph edges."""
        if graph.is_multigraph():
            edge_iterator = graph.edges(keys=True)
        else:
            edge_iterator = ((source, target, None) for source, target in graph.edges())

        for source, target, key in edge_iterator:
            if graph.is_multigraph():
                edge_data = graph.edges[source, target, key]
            else:
                edge_data = graph.edges[source, target]
            updates: dict[str, object] = {
                "arrowhead": "vee",
                "style": default_style,
            }
            if source_type_style_map is not None:
                source_props = graph.nodes[source]
                source_type = source_props.get("type")
                if source_type in source_type_style_map:
                    updates["style"] = source_type_style_map[source_type]
            if "label" in edge_data:
                updates["label"] = edge_data["label"]
            for key_name, value in updates.items():
                if graph.is_multigraph():
                    graph.edges[source, target, key][key_name] = value
                else:
                    graph.edges[source, target][key_name] = value

    @staticmethod
    def _add_partition_subgraphs(
        ag,
        graph: nx.MultiDiGraph | nx.DiGraph,
        partition_by_vertex: dict[str, str],
    ) -> None:
        """Add Graphviz subgraphs grouping vertices by partition labels."""
        partition_to_nodes: dict[str, list[str]] = {}
        for node_id in graph.nodes():
            if not isinstance(node_id, str) or not node_id.startswith(
                f"{AuxNodeType.VERTEX}:"
            ):
                continue
            vertex_name = node_id.split(":", maxsplit=1)[1]
            group = partition_by_vertex.get(vertex_name)
            if group is None:
                continue
            partition_to_nodes.setdefault(group, []).append(node_id)

        for group in sorted(partition_to_nodes):
            ag.add_subgraph(
                partition_to_nodes[group],
                name=f"cluster_partition_{group}",
                rank="same",
                label=str(group),
            )

    def _add_resource_vertex_links(
        self,
        graph: nx.MultiDiGraph,
        resource,
    ) -> None:
        """Add a resource node and its vertex links to a graph."""
        resource_id = get_auxnode_id(
            AuxNodeType.RESOURCE,
            resource=resource.name,
            resource_type="resource",
        )
        graph.add_node(
            resource_id,
            type=AuxNodeType.RESOURCE,
            label=resource.name,
        )

        vertex_reasons = self._extract_resource_vertex_reasons(resource)
        for vertex_name, reasons in sorted(vertex_reasons.items()):
            vertex_id = get_auxnode_id(AuxNodeType.VERTEX, vertex=vertex_name)
            graph.add_node(
                vertex_id,
                type=AuxNodeType.VERTEX,
                label=vertex_name,
            )
            graph.add_edge(resource_id, vertex_id, label=", ".join(sorted(reasons)))

    @staticmethod
    def _node_id_to_vertex(node_id: str) -> str:
        """Extract vertex name from an AuxNodeType.VERTEX node ID."""
        return node_id.split(":", maxsplit=1)[1]

    def _build_partition_color_map(
        self,
        partition_values: set[str],
        partition_colors: dict[str, str] | None,
    ) -> dict[str, str]:
        """Build a deterministic color map for partition labels."""
        color_map = {}
        if partition_colors is not None:
            color_map.update(partition_colors)

        auto_keys = sorted(partition_values - set(color_map.keys()))
        for idx, key in enumerate(auto_keys):
            color_map[key] = partition_color_palette[idx % len(partition_color_palette)]
        return color_map

    @staticmethod
    def _partition_legend(
        graph: nx.MultiDiGraph | nx.DiGraph,
        partition_by_vertex: dict[str, str],
        partition_color_map: dict[str, str],
    ) -> list[tuple[str, dict[str, str]]]:
        """Legend entries for the vertex groups drawn in *graph*, by group name."""
        groups = {
            partition_by_vertex[vertex]
            for node_id in graph.nodes()
            if isinstance(node_id, str)
            and node_id.startswith(f"{AuxNodeType.VERTEX}:")
            and (vertex := node_id.split(":", maxsplit=1)[1]) in partition_by_vertex
        }
        entries = []
        for group in sorted(groups, key=_group_order):
            if group not in partition_color_map:
                continue
            meaning = group
            if group == f"{_LEVEL_PREFIX}0":
                meaning = "level 0 (sources)"
            elif group.startswith(_LEVEL_PREFIX):
                meaning = f"level {group.removeprefix(_LEVEL_PREFIX)}"
            entries.append(
                (
                    meaning,
                    {
                        "shape": NODE_SHAPE_BY_TYPE[AuxNodeType.VERTEX],
                        "style": "filled",
                        "color": NODE_COLOR_BY_TYPE[AuxNodeType.VERTEX],
                        "fillcolor": partition_color_map[group],
                    },
                )
            )
        return entries

    def _infer_vertex_levels(self, edges: list[tuple[str, str]]) -> dict[str, int]:
        """Infer robust DAG-like levels by collapsing SCCs then layering the DAG."""
        graph = nx.DiGraph()
        graph.add_nodes_from(self.schema_graph.vertex_types)
        graph.add_edges_from(edges)

        condensation = nx.condensation(graph)
        component_level: dict[int, int] = {}
        for component in nx.topological_sort(condensation):
            predecessors = list(condensation.predecessors(component))
            if not predecessors:
                component_level[component] = 0
                continue
            component_level[component] = (
                max(component_level[pred] for pred in predecessors) + 1
            )

        levels = {}
        member_map = condensation.graph["mapping"]
        for vertex in graph.nodes:
            levels[vertex] = component_level[member_map[vertex]]
        return levels

    def plot_vc2fields(self):
        """Plot vertex collections and their fields.

        Creates a visualization showing the relationship between vertex collections
        and their fields, including index fields. The visualization is saved as
        a PDF file.
        """
        g = nx.DiGraph()
        nodes = []
        edges = []
        vconf = self.schema.core_schema.vertex_config
        vertex_prefix_dict = shortest_unique_prefix_map(
            [v for v in self.schema.core_schema.vertex_config.vertex_set]
        )

        kwargs = {"vfield": True, "vertex_sh": vertex_prefix_dict}
        for k in vconf.vertex_set:
            index_fields = vconf.identity_fields(k)
            fields = vconf.property_names(k)
            kwargs["vertex"] = k
            nodes_collection = [
                (
                    get_auxnode_id(AuxNodeType.VERTEX, **kwargs),
                    {
                        "type": AuxNodeType.VERTEX,
                        "label": get_auxnode_id(
                            AuxNodeType.VERTEX, label=True, **kwargs
                        ),
                    },
                )
            ]
            nodes_fields = [
                (
                    get_auxnode_id(AuxNodeType.FIELD, field=item, **kwargs),
                    {
                        "type": (
                            AuxNodeType.FIELD_DEFINITION
                            if item in index_fields
                            else AuxNodeType.FIELD
                        ),
                        "label": get_auxnode_id(
                            AuxNodeType.FIELD, field=item, label=True, **kwargs
                        ),
                    },
                )
                for item in fields
            ]
            nodes += nodes_collection
            nodes += nodes_fields
            edges += [(x[0], y[0]) for x, y in product(nodes_collection, nodes_fields)]

        g.add_nodes_from(nodes)
        g.add_edges_from(edges)

        self._style_nodes(g, force_labels=True)
        self._style_edges(g)

        ag = to_dot(g)

        for k in vconf.vertex_set:
            level_index = [
                get_auxnode_id(
                    AuxNodeType.FIELD,
                    vertex=k,
                    field=item,
                    vfield=True,
                    vertex_sh=vertex_prefix_dict,
                )
                for item in vconf.identity_fields(k)
            ]
            index_subgraph = ag.add_subgraph(level_index, name=f"cluster_{k}:def")
            index_subgraph.graph_attr["style"] = "filled"
            index_subgraph.graph_attr["label"] = "definition"

        ag = ag.unflatten(levels=5, fans=True, chain=3)
        add_legend(ag, type_legend(g))
        self._draw(ag, self._versioned_stem(f"{self.prefix}_vc2fields"))

    def plot_resources(self):
        """Plot resource relationships.

        Creates visualizations for each resource in the schema, showing their
        internal structure and relationships. Each resource is saved as a
        separate PDF file.
        """
        resource_prefix_dict = shortest_unique_prefix_map(
            [resource.name for resource in self.ingestion_model.resources]
        )
        vertex_prefix_dict = shortest_unique_prefix_map(
            [v for v in self.schema.core_schema.vertex_config.vertex_set]
        )
        kwargs = {"vertex_sh": vertex_prefix_dict, "resource_sh": resource_prefix_dict}

        for resource_config in self.ingestion_model.resources:
            kwargs["resource"] = resource_config.name
            assemble_tree(
                ActorWrapper(*resource_config.pipeline),
                self._figure_path(f"{self.name}.resource-{resource_config.name}"),
                output_format=self.output_format,
                output_dpi=self.output_dpi,
            )

    def plot_source2vc(self):
        """Plot source to vertex collection mappings.

        Creates a visualization showing the relationship between source resources
        and vertex collections. The visualization is saved as a PDF file.
        """
        g = nx.MultiDiGraph()
        for resource in self.ingestion_model.resources:
            self._add_resource_vertex_links(g, resource)

        self._style_nodes(g, force_labels=True)
        self._style_edges(g)

        ag = to_dot(g)
        ag.graph_attr["rankdir"] = "LR"
        ag.graph_attr["splines"] = "spline"

        resource_nodes = [
            get_auxnode_id(
                AuxNodeType.RESOURCE,
                resource=resource.name,
                resource_type="resource",
            )
            for resource in self.ingestion_model.resources
        ]
        vertex_nodes = [
            get_auxnode_id(AuxNodeType.VERTEX, vertex=v)
            for v in sorted(self.schema.core_schema.vertex_config.vertex_set)
            if get_auxnode_id(AuxNodeType.VERTEX, vertex=v) in g.nodes
        ]
        if resource_nodes:
            ag.add_subgraph(resource_nodes, name="cluster_resources", rank="same")
        if vertex_nodes:
            ag.add_subgraph(vertex_nodes, name="cluster_vertices", rank="same")
        add_legend(ag, type_legend(g))

        self._draw(ag, self._versioned_stem(f"{self.prefix}_source2vc"))

    def _extract_resource_vertex_reasons(self, resource) -> dict[str, set[str]]:
        """Collect vertex references for a resource with lightweight reason labels."""
        vertex_reasons: dict[str, set[str]] = {}
        known_vertices = set(self.schema.core_schema.vertex_config.vertex_set)
        actors = ActorWrapper(*resource.pipeline).collect_actors()

        def _add(vertex_name: str, reason: str) -> None:
            if vertex_name not in known_vertices:
                return
            if vertex_name not in vertex_reasons:
                vertex_reasons[vertex_name] = set()
            vertex_reasons[vertex_name].add(reason)

        for actor in actors:
            for vertex_name in actor.references_vertices():
                _add(vertex_name, type(actor).__name__)

            if isinstance(actor, VertexRouterActor):
                for vertex_name in actor.type_map.values():
                    _add(vertex_name, "VertexRouterActor(type_map)")
                for vertex_name in actor.vertex_from_map:
                    _add(vertex_name, "VertexRouterActor(vertex_from_map)")
                for vertex_name in actor.config.vertex_types or []:
                    _add(vertex_name, "VertexRouterActor(vertex_types)")

        return vertex_reasons

    def plot_source2vc_detailed(self):
        """Plot per-resource source-to-vertex mappings as dedicated detail pages."""
        for resource in self.ingestion_model.resources:
            g = nx.MultiDiGraph()
            self._add_resource_vertex_links(g, resource)

            self._style_nodes(g, force_labels=True)
            self._style_edges(g)

            ag = to_dot(g)
            ag.graph_attr["rankdir"] = "LR"
            add_legend(ag, type_legend(g))
            self._draw(
                ag,
                self._versioned_stem(f"{self.name}.resource2vc-{resource.name}"),
            )

    def plot_vc2vc(
        self,
        prune_leaves: bool = False,
        partition: dict[str, str] | None = None,
        partition_colors: dict[str, str] | None = None,
        color_by_partition: bool = False,
        group_by_partition: bool = False,
        include_all_vertices: bool = True,
        group_by_inferred_level: bool = False,
    ):
        """Plot vertex collection relationships.

        Creates a visualization showing the relationships between vertex collections.
        Optionally prunes leaf nodes from the visualization.

        This method discovers edges from both edge_config and resources to ensure
        all relationships are visualized, including those with dynamic relations.

        Args:
            prune_leaves: Whether to remove leaf nodes from the visualization
            partition: Optional vertex->group mapping used for coloring/grouping
            partition_colors: Optional group->color mapping for partition values
            color_by_partition: Whether to color nodes using partition values
            group_by_partition: Whether to add Graphviz clusters for each group
            include_all_vertices: Whether to include vertices with no known edges
            group_by_inferred_level: Group by inferred graph level (SCC-aware)

        Example:
            >>> plotter.plot_vc2vc(prune_leaves=True)
        """
        g = nx.MultiDiGraph()
        nodes: list[tuple[str, dict[str, object]]] = []
        rendered_edges: list[tuple] = []

        (
            discovered_edges,
            relation_source_by_edge_id,
            relation_from_key_by_edge_id,
        ) = self._discover_edges_from_resources()
        # Declared edges from the index; discovered ones supplement it, since
        # an edge that only exists in a resource pipeline is not in the schema.
        configured_edges = {
            edge_id: self.schema_graph.edge(edge_id)
            for edge_id in self.schema_graph.edge_ids
        }
        all_edges = self._merge_edges(configured_edges, discovered_edges)

        known_vertices = set(self.schema_graph.vertex_types)
        valid_edges, invalid_edges = self._filter_edges_with_known_vertices(
            all_edges,
            known_vertices,
        )
        if invalid_edges:
            sampled_invalid = sorted(invalid_edges)[:5]
            logger.error(
                "plot_vc2vc ignored %s edge(s) with unknown vertices not in vertex_config; sample=%s",
                len(invalid_edges),
                sampled_invalid,
            )

        edge_pairs = [(source, target) for (source, target, _relation) in valid_edges]
        for edge_id, edge in valid_edges.items():
            label = self._edge_label(
                edge,
                relation_source_field=relation_source_by_edge_id.get(edge_id),
                relation_from_key=relation_from_key_by_edge_id.get(edge_id, False),
            )
            source, target = edge_id[0], edge_id[1]
            source_id = get_auxnode_id(AuxNodeType.VERTEX, vertex=source)
            target_id = get_auxnode_id(AuxNodeType.VERTEX, vertex=target)
            if label is None:
                rendered_edges.append((source_id, target_id))
            else:
                rendered_edges.append((source_id, target_id, {"label": label}))

        # Create nodes for vertices involved in edges, optionally including all schema vertices
        vertices_in_edges = {
            vertex
            for (source, target, _relation) in valid_edges
            for vertex in (source, target)
        }
        all_vertices = (
            set(self.schema_graph.vertex_types)
            if include_all_vertices
            else vertices_in_edges
        )

        effective_partition = partition.copy() if partition is not None else {}
        if group_by_inferred_level:
            inferred_levels = self._infer_vertex_levels(edge_pairs)
            effective_partition.update(
                {
                    vertex: f"{_LEVEL_PREFIX}{level}"
                    for vertex, level in inferred_levels.items()
                }
            )

        for v in sorted(all_vertices):
            nodes += [
                (
                    get_auxnode_id(AuxNodeType.VERTEX, vertex=v),
                    {
                        "type": AuxNodeType.VERTEX,
                        "label": get_auxnode_id(
                            AuxNodeType.VERTEX, vertex=v, label=True
                        ),
                    },
                )
            ]

        g.add_nodes_from(nodes)
        g.add_edges_from(rendered_edges)

        if prune_leaves:
            out_deg = g.out_degree()
            in_deg = g.in_degree()

            nodes_to_remove = {k for k, v in out_deg if v == 0} & {
                k for k, v in in_deg if v < 2
            }
            g.remove_nodes_from(nodes_to_remove)

        partition_color_map = (
            self._build_partition_color_map(
                partition_values=set(effective_partition.values()),
                partition_colors=partition_colors,
            )
            if effective_partition and color_by_partition
            else {}
        )

        self._style_nodes(
            g,
            partition_by_vertex=effective_partition if partition_color_map else None,
            partition_color_map=partition_color_map if partition_color_map else None,
        )
        self._style_edges(g, source_type_style_map=EDGE_STYLE_BY_SOURCE_TYPE)

        ag = to_dot(g)
        if group_by_partition and effective_partition:
            self._add_partition_subgraphs(ag, g, effective_partition)
        if partition_color_map:
            legend = self._partition_legend(g, effective_partition, partition_color_map)
        else:
            legend = type_legend(g)
        add_legend(ag, legend)

        self._draw(ag, self._versioned_stem(f"{self.prefix}_vc2vc"))

Attributes

config = None instance-attribute
fig_path = fig_path instance-attribute
ingestion_model = manifest.require_ingestion_model() instance-attribute
name = Schema._slug_filename_token(self.schema.metadata.name) instance-attribute
output_dpi = output_dpi instance-attribute
output_format = output_format.lower() instance-attribute
prefix = self.name instance-attribute
schema = manifest.require_schema() instance-attribute
schema_graph = SchemaGraph.from_schema(self.schema) instance-attribute

Methods:

__init__(config_filename=None, fig_path='.', output_format='pdf', output_dpi=None, graph_manifest=None)

Initialize the schema plotter.

Parameters:

Name Type Description Default
config_filename str | PathLike[str] | None

Optional path to schema configuration file

None
fig_path str | PathLike[str]

Path to save visualizations

'.'
graph_manifest GraphManifest | None

Optional pre-built graph manifest

None
Source code in graflo/plot/plotter.py
def __init__(
    self,
    config_filename: str | os.PathLike[str] | None = None,
    fig_path: str | os.PathLike[str] = ".",
    output_format: str = "pdf",
    output_dpi: int | None = None,
    graph_manifest: GraphManifest | None = None,
):
    """Initialize the schema plotter.

    Args:
        config_filename: Optional path to schema configuration file
        fig_path: Path to save visualizations
        graph_manifest: Optional pre-built graph manifest
    """
    self.fig_path = fig_path
    self.output_format = output_format.lower()
    self.output_dpi = output_dpi

    manifest: GraphManifest
    if graph_manifest is not None:
        manifest = graph_manifest
        self.config = None
    elif config_filename is not None:
        self.config = FileHandle.load(config_filename)
        manifest = GraphManifest.from_config(self.config)
    else:
        raise ValueError(
            "ManifestPlotter requires either `config_filename` or `graph_manifest`."
        )

    manifest.finish_init()
    self.schema = manifest.require_schema()
    self.ingestion_model = manifest.require_ingestion_model()

    # A label, not a filename: merged names carry "+" and may carry spaces.
    self.name = Schema._slug_filename_token(self.schema.metadata.name)
    self.prefix = self.name
    # The one index over the schema's declared adjacency. Built here so
    # every plot reads the same traversal rather than each deriving its
    # own from `vertex_config` / `edge_config`.
    self.schema_graph = SchemaGraph.from_schema(self.schema)
plot_resources()

Plot resource relationships.

Creates visualizations for each resource in the schema, showing their internal structure and relationships. Each resource is saved as a separate PDF file.

Source code in graflo/plot/plotter.py
def plot_resources(self):
    """Plot resource relationships.

    Creates visualizations for each resource in the schema, showing their
    internal structure and relationships. Each resource is saved as a
    separate PDF file.
    """
    resource_prefix_dict = shortest_unique_prefix_map(
        [resource.name for resource in self.ingestion_model.resources]
    )
    vertex_prefix_dict = shortest_unique_prefix_map(
        [v for v in self.schema.core_schema.vertex_config.vertex_set]
    )
    kwargs = {"vertex_sh": vertex_prefix_dict, "resource_sh": resource_prefix_dict}

    for resource_config in self.ingestion_model.resources:
        kwargs["resource"] = resource_config.name
        assemble_tree(
            ActorWrapper(*resource_config.pipeline),
            self._figure_path(f"{self.name}.resource-{resource_config.name}"),
            output_format=self.output_format,
            output_dpi=self.output_dpi,
        )
plot_source2vc()

Plot source to vertex collection mappings.

Creates a visualization showing the relationship between source resources and vertex collections. The visualization is saved as a PDF file.

Source code in graflo/plot/plotter.py
def plot_source2vc(self):
    """Plot source to vertex collection mappings.

    Creates a visualization showing the relationship between source resources
    and vertex collections. The visualization is saved as a PDF file.
    """
    g = nx.MultiDiGraph()
    for resource in self.ingestion_model.resources:
        self._add_resource_vertex_links(g, resource)

    self._style_nodes(g, force_labels=True)
    self._style_edges(g)

    ag = to_dot(g)
    ag.graph_attr["rankdir"] = "LR"
    ag.graph_attr["splines"] = "spline"

    resource_nodes = [
        get_auxnode_id(
            AuxNodeType.RESOURCE,
            resource=resource.name,
            resource_type="resource",
        )
        for resource in self.ingestion_model.resources
    ]
    vertex_nodes = [
        get_auxnode_id(AuxNodeType.VERTEX, vertex=v)
        for v in sorted(self.schema.core_schema.vertex_config.vertex_set)
        if get_auxnode_id(AuxNodeType.VERTEX, vertex=v) in g.nodes
    ]
    if resource_nodes:
        ag.add_subgraph(resource_nodes, name="cluster_resources", rank="same")
    if vertex_nodes:
        ag.add_subgraph(vertex_nodes, name="cluster_vertices", rank="same")
    add_legend(ag, type_legend(g))

    self._draw(ag, self._versioned_stem(f"{self.prefix}_source2vc"))
plot_source2vc_detailed()

Plot per-resource source-to-vertex mappings as dedicated detail pages.

Source code in graflo/plot/plotter.py
def plot_source2vc_detailed(self):
    """Plot per-resource source-to-vertex mappings as dedicated detail pages."""
    for resource in self.ingestion_model.resources:
        g = nx.MultiDiGraph()
        self._add_resource_vertex_links(g, resource)

        self._style_nodes(g, force_labels=True)
        self._style_edges(g)

        ag = to_dot(g)
        ag.graph_attr["rankdir"] = "LR"
        add_legend(ag, type_legend(g))
        self._draw(
            ag,
            self._versioned_stem(f"{self.name}.resource2vc-{resource.name}"),
        )
plot_vc2fields()

Plot vertex collections and their fields.

Creates a visualization showing the relationship between vertex collections and their fields, including index fields. The visualization is saved as a PDF file.

Source code in graflo/plot/plotter.py
def plot_vc2fields(self):
    """Plot vertex collections and their fields.

    Creates a visualization showing the relationship between vertex collections
    and their fields, including index fields. The visualization is saved as
    a PDF file.
    """
    g = nx.DiGraph()
    nodes = []
    edges = []
    vconf = self.schema.core_schema.vertex_config
    vertex_prefix_dict = shortest_unique_prefix_map(
        [v for v in self.schema.core_schema.vertex_config.vertex_set]
    )

    kwargs = {"vfield": True, "vertex_sh": vertex_prefix_dict}
    for k in vconf.vertex_set:
        index_fields = vconf.identity_fields(k)
        fields = vconf.property_names(k)
        kwargs["vertex"] = k
        nodes_collection = [
            (
                get_auxnode_id(AuxNodeType.VERTEX, **kwargs),
                {
                    "type": AuxNodeType.VERTEX,
                    "label": get_auxnode_id(
                        AuxNodeType.VERTEX, label=True, **kwargs
                    ),
                },
            )
        ]
        nodes_fields = [
            (
                get_auxnode_id(AuxNodeType.FIELD, field=item, **kwargs),
                {
                    "type": (
                        AuxNodeType.FIELD_DEFINITION
                        if item in index_fields
                        else AuxNodeType.FIELD
                    ),
                    "label": get_auxnode_id(
                        AuxNodeType.FIELD, field=item, label=True, **kwargs
                    ),
                },
            )
            for item in fields
        ]
        nodes += nodes_collection
        nodes += nodes_fields
        edges += [(x[0], y[0]) for x, y in product(nodes_collection, nodes_fields)]

    g.add_nodes_from(nodes)
    g.add_edges_from(edges)

    self._style_nodes(g, force_labels=True)
    self._style_edges(g)

    ag = to_dot(g)

    for k in vconf.vertex_set:
        level_index = [
            get_auxnode_id(
                AuxNodeType.FIELD,
                vertex=k,
                field=item,
                vfield=True,
                vertex_sh=vertex_prefix_dict,
            )
            for item in vconf.identity_fields(k)
        ]
        index_subgraph = ag.add_subgraph(level_index, name=f"cluster_{k}:def")
        index_subgraph.graph_attr["style"] = "filled"
        index_subgraph.graph_attr["label"] = "definition"

    ag = ag.unflatten(levels=5, fans=True, chain=3)
    add_legend(ag, type_legend(g))
    self._draw(ag, self._versioned_stem(f"{self.prefix}_vc2fields"))
plot_vc2vc(prune_leaves=False, partition=None, partition_colors=None, color_by_partition=False, group_by_partition=False, include_all_vertices=True, group_by_inferred_level=False)

Plot vertex collection relationships.

Creates a visualization showing the relationships between vertex collections. Optionally prunes leaf nodes from the visualization.

This method discovers edges from both edge_config and resources to ensure all relationships are visualized, including those with dynamic relations.

Parameters:

Name Type Description Default
prune_leaves bool

Whether to remove leaf nodes from the visualization

False
partition dict[str, str] | None

Optional vertex->group mapping used for coloring/grouping

None
partition_colors dict[str, str] | None

Optional group->color mapping for partition values

None
color_by_partition bool

Whether to color nodes using partition values

False
group_by_partition bool

Whether to add Graphviz clusters for each group

False
include_all_vertices bool

Whether to include vertices with no known edges

True
group_by_inferred_level bool

Group by inferred graph level (SCC-aware)

False
Example

plotter.plot_vc2vc(prune_leaves=True)

Source code in graflo/plot/plotter.py
def plot_vc2vc(
    self,
    prune_leaves: bool = False,
    partition: dict[str, str] | None = None,
    partition_colors: dict[str, str] | None = None,
    color_by_partition: bool = False,
    group_by_partition: bool = False,
    include_all_vertices: bool = True,
    group_by_inferred_level: bool = False,
):
    """Plot vertex collection relationships.

    Creates a visualization showing the relationships between vertex collections.
    Optionally prunes leaf nodes from the visualization.

    This method discovers edges from both edge_config and resources to ensure
    all relationships are visualized, including those with dynamic relations.

    Args:
        prune_leaves: Whether to remove leaf nodes from the visualization
        partition: Optional vertex->group mapping used for coloring/grouping
        partition_colors: Optional group->color mapping for partition values
        color_by_partition: Whether to color nodes using partition values
        group_by_partition: Whether to add Graphviz clusters for each group
        include_all_vertices: Whether to include vertices with no known edges
        group_by_inferred_level: Group by inferred graph level (SCC-aware)

    Example:
        >>> plotter.plot_vc2vc(prune_leaves=True)
    """
    g = nx.MultiDiGraph()
    nodes: list[tuple[str, dict[str, object]]] = []
    rendered_edges: list[tuple] = []

    (
        discovered_edges,
        relation_source_by_edge_id,
        relation_from_key_by_edge_id,
    ) = self._discover_edges_from_resources()
    # Declared edges from the index; discovered ones supplement it, since
    # an edge that only exists in a resource pipeline is not in the schema.
    configured_edges = {
        edge_id: self.schema_graph.edge(edge_id)
        for edge_id in self.schema_graph.edge_ids
    }
    all_edges = self._merge_edges(configured_edges, discovered_edges)

    known_vertices = set(self.schema_graph.vertex_types)
    valid_edges, invalid_edges = self._filter_edges_with_known_vertices(
        all_edges,
        known_vertices,
    )
    if invalid_edges:
        sampled_invalid = sorted(invalid_edges)[:5]
        logger.error(
            "plot_vc2vc ignored %s edge(s) with unknown vertices not in vertex_config; sample=%s",
            len(invalid_edges),
            sampled_invalid,
        )

    edge_pairs = [(source, target) for (source, target, _relation) in valid_edges]
    for edge_id, edge in valid_edges.items():
        label = self._edge_label(
            edge,
            relation_source_field=relation_source_by_edge_id.get(edge_id),
            relation_from_key=relation_from_key_by_edge_id.get(edge_id, False),
        )
        source, target = edge_id[0], edge_id[1]
        source_id = get_auxnode_id(AuxNodeType.VERTEX, vertex=source)
        target_id = get_auxnode_id(AuxNodeType.VERTEX, vertex=target)
        if label is None:
            rendered_edges.append((source_id, target_id))
        else:
            rendered_edges.append((source_id, target_id, {"label": label}))

    # Create nodes for vertices involved in edges, optionally including all schema vertices
    vertices_in_edges = {
        vertex
        for (source, target, _relation) in valid_edges
        for vertex in (source, target)
    }
    all_vertices = (
        set(self.schema_graph.vertex_types)
        if include_all_vertices
        else vertices_in_edges
    )

    effective_partition = partition.copy() if partition is not None else {}
    if group_by_inferred_level:
        inferred_levels = self._infer_vertex_levels(edge_pairs)
        effective_partition.update(
            {
                vertex: f"{_LEVEL_PREFIX}{level}"
                for vertex, level in inferred_levels.items()
            }
        )

    for v in sorted(all_vertices):
        nodes += [
            (
                get_auxnode_id(AuxNodeType.VERTEX, vertex=v),
                {
                    "type": AuxNodeType.VERTEX,
                    "label": get_auxnode_id(
                        AuxNodeType.VERTEX, vertex=v, label=True
                    ),
                },
            )
        ]

    g.add_nodes_from(nodes)
    g.add_edges_from(rendered_edges)

    if prune_leaves:
        out_deg = g.out_degree()
        in_deg = g.in_degree()

        nodes_to_remove = {k for k, v in out_deg if v == 0} & {
            k for k, v in in_deg if v < 2
        }
        g.remove_nodes_from(nodes_to_remove)

    partition_color_map = (
        self._build_partition_color_map(
            partition_values=set(effective_partition.values()),
            partition_colors=partition_colors,
        )
        if effective_partition and color_by_partition
        else {}
    )

    self._style_nodes(
        g,
        partition_by_vertex=effective_partition if partition_color_map else None,
        partition_color_map=partition_color_map if partition_color_map else None,
    )
    self._style_edges(g, source_type_style_map=EDGE_STYLE_BY_SOURCE_TYPE)

    ag = to_dot(g)
    if group_by_partition and effective_partition:
        self._add_partition_subgraphs(ag, g, effective_partition)
    if partition_color_map:
        legend = self._partition_legend(g, effective_partition, partition_color_map)
    else:
        legend = type_legend(g)
    add_legend(ag, legend)

    self._draw(ag, self._versioned_stem(f"{self.prefix}_vc2vc"))

StackExhausted

Bases: RuntimeError

Graphviz's layout recursed deeper than the WebAssembly stack allows.

Source code in graflo/plot/render.py
class StackExhausted(RuntimeError):
    """Graphviz's layout recursed deeper than the WebAssembly stack allows."""

Functions:

build_equivalence_view(preview, target, view)

One view of one equivalence as a networkx graph, or None when it shows nothing.

Every node carries the preview id it stands for as preview_id, and every edge its style as kind. The boxes graph attribute maps a box id to (label, side, [node, ...]); ranks lists node groups drawn in one rank, in order.

Parameters:

Name Type Description Default
preview MergePreview

The whole preview, from preview_merge or declared_preview.

required
target str | int

A cluster id, or a position in the op's vertex_equivalences.

required
view View

One of :data:VIEWS.

required

Raises:

Type Description
KeyError

target names no equivalence.

Source code in graflo/plot/equivalence.py
def build_equivalence_view(
    preview: MergePreview, target: str | int, view: View
) -> nx.MultiDiGraph | None:
    """One view of one equivalence as a networkx graph, or ``None`` when it shows nothing.

    Every node carries the preview id it stands for as ``preview_id``, and
    every edge its style as ``kind``. The ``boxes`` graph attribute maps a
    box id to ``(label, side, [node, ...])``; ``ranks`` lists node groups
    drawn in one rank, in order.

    Args:
        preview: The whole preview, from ``preview_merge`` or ``declared_preview``.
        target: A cluster id, or a position in the op's ``vertex_equivalences``.
        view: One of :data:`VIEWS`.

    Raises:
        KeyError: *target* names no equivalence.
    """
    fig = _build(preview, target, view)
    if fig is None:
        return None
    fig.graph.graph["boxes"] = fig.boxes
    fig.graph.graph["ranks"] = fig.ranks
    return fig.graph

build_history_graph(history, *, heads=(), merge_base=None)

The commit DAG as a networkx graph.

Parameters:

Name Type Description Default
history Any

A :class:~graflo.architecture.evolution.history.History.

required
heads Collection[str]

Commit ids to mark as the sides being reconciled.

()
merge_base str | None

The common ancestor, marked as such.

None

Returns:

Type Description
DiGraph

A graph with one node per commit, edges pointing parent to child.

Source code in graflo/plot/merge3.py
def build_history_graph(
    history: Any,
    *,
    heads: Collection[str] = (),
    merge_base: str | None = None,
) -> nx.DiGraph:
    """The commit DAG as a networkx graph.

    Args:
        history: A :class:`~graflo.architecture.evolution.history.History`.
        heads: Commit ids to mark as the sides being reconciled.
        merge_base: The common ancestor, marked as such.

    Returns:
        A graph with one node per commit, edges pointing parent to child.
    """
    graph = nx.DiGraph()
    graph.graph["graph"] = {
        "rankdir": "LR",
        "fontname": "Helvetica",
        "labelloc": "t",
        "label": "commit history",
    }
    graph.graph["node"] = {"fontname": "Helvetica", "style": "filled"}
    graph.graph["edge"] = {"fontname": "Helvetica"}

    head_ids = set(heads)
    for commit in history.commits:
        role = (
            "base"
            if commit.id == merge_base
            else "head"
            if commit.id in head_ids
            else commit.kind
        )
        fill = {
            "base": "#FFE5B4",
            "head": "#B7D1DF",
        }.get(role, "#FFFFFF")
        label = commit.id[:8]
        if commit.label:
            label = f"{label}\\n{commit.label}"
        if commit.id == merge_base:
            label = f"{label}\\n(merge base)"
        graph.add_node(
            sanitize_id(commit.id),
            label=label,
            shape=COMMIT_SHAPE.get(commit.kind, "box"),
            fillcolor=fill,
            commit=commit.id,
            role=role,
        )
    for commit in history.commits:
        for position, parent in enumerate(commit.parents):
            graph.add_edge(
                sanitize_id(parent),
                sanitize_id(commit.id),
                # A commit's ops are a diff from its *first* parent; the other
                # parents are lineage, not derivation.
                style="solid" if position == 0 else "dashed",
                color="#2C3E50" if position == 0 else "#95A5A6",
            )
    return graph

build_merge3_graph(preview)

The slot tree as a networkx graph, styled but not drawn.

Parameters:

Name Type Description Default
preview Merge3Preview

What :func:~graflo.architecture.evolution.preview.build_merge3_preview returned.

required

Returns:

Type Description
DiGraph

A graph whose attributes are Graphviz attributes; every node carries

DiGraph

its slot path as slot.

Source code in graflo/plot/merge3.py
def build_merge3_graph(preview: Merge3Preview) -> nx.DiGraph:
    """The slot tree as a networkx graph, styled but not drawn.

    Args:
        preview: What
            :func:`~graflo.architecture.evolution.preview.build_merge3_preview`
            returned.

    Returns:
        A graph whose attributes are Graphviz attributes; every node carries
        its slot path as ``slot``.
    """
    graph = nx.DiGraph()
    verdict = "clean" if preview.clean else f"{preview.conflicts} conflict(s) to decide"
    graph.graph["graph"] = {
        "rankdir": "LR",
        "fontname": "Helvetica",
        "labelloc": "t",
        "label": f"three-way merge — {verdict}",
    }
    graph.graph["node"] = {"fontname": "Helvetica", "fontsize": str(FONT_SIZE)}
    graph.graph["edge"] = {"fontname": "Helvetica", "color": "#95A5A6"}

    taken: dict[str, str] = {}
    for node in preview.nodes:
        graph.add_node(
            sanitize_id(node.id, taken),
            **_slot_node(node),
            slot=node.id,
            contested=str(node.contested).lower(),
        )
    for node in preview.nodes:
        if node.parent is None or node.parent not in taken:
            continue
        graph.add_edge(
            taken[node.parent],
            taken[node.id],
            penwidth="1.6" if node.contested else "1.0",
            color=SLOT_COLOR["contested"] if node.contested else "#95A5A6",
        )
    return graph

build_preview_graph(preview, *, max_rows=12, legend=True, fusion=False)

The preview as a networkx graph, styled but not yet drawn.

Only classes, relations and merged names become nodes: attributes are rows on their owner, addressed by port. Every node carries the preview id it came from as preview_id, so a caller can map back.

Parameters:

Name Type Description Default
preview MergePreview

What :func:~graflo.architecture.evolution.preview.preview_merge returned.

required
max_rows int

Attribute rows to draw per class before summarising the rest.

12
legend bool

Whether to include the findings legend.

True
fusion bool

Whether to draw the edge from each attribute that keeps its name; off by default, since on a whole merge it ties every row.

False

Returns:

Type Description
MultiDiGraph

A graph whose node and edge attributes are Graphviz attributes.

Source code in graflo/plot/merge.py
def build_preview_graph(
    preview: MergePreview,
    *,
    max_rows: int = 12,
    legend: bool = True,
    fusion: bool = False,
) -> nx.MultiDiGraph:
    """The preview as a networkx graph, styled but not yet drawn.

    Only classes, relations and merged names become nodes: attributes are
    rows on their owner, addressed by port. Every node carries the preview id
    it came from as ``preview_id``, so a caller can map back.

    Args:
        preview: What :func:`~graflo.architecture.evolution.preview.preview_merge` returned.
        max_rows: Attribute rows to draw per class before summarising the rest.
        legend: Whether to include the findings legend.
        fusion: Whether to draw the edge from each attribute that keeps its
            name; off by default, since on a whole merge it ties every row.

    Returns:
        A graph whose node and edge attributes are Graphviz attributes.
    """
    graph = nx.MultiDiGraph()
    graph.graph["graph"] = {
        "rankdir": "LR",
        "splines": "spline",
        "fontname": "Helvetica",
        "labelloc": "t",
        "label": _title(preview),
    }
    graph.graph["node"] = {"fontname": "Helvetica", "fontsize": str(FONT_SIZE)}
    graph.graph["edge"] = {"fontname": "Helvetica", "fontsize": "9"}

    node_flags, edge_flags, badges = _flags(preview)
    edges = _drawn_edges(preview, fusion=fusion)
    nodes = {n.id: n for n in preview.nodes}
    taken = _class_nodes(
        graph,
        preview,
        node_flags=node_flags,
        badges=badges,
        max_rows=max_rows,
        keep=_endpoints(edges),
    )
    for edge in edges:
        ends = _edge_ends(nodes, taken, edge)
        if ends is not None:
            _attach(graph, *ends, _edge_attrs(edge, edge_flags.get(edge.id)))

    if legend:
        graph.add_node("legend", **_legend(preview), kind="legend", preview_id="legend")
    return graph

plot_equivalence(preview, target, directory, *, views=VIEWS, output_format='svg', stem=None, prog='dot', dpi=None)

Draw views of one equivalence into directory; a view with nothing to show is skipped.

Files are <stem>.<view>.<format>; stem defaults to <kind>-<merged name>, e.g. vertex-Machine.identity.svg.

Parameters:

Name Type Description Default
preview MergePreview

The whole preview, from preview_merge or declared_preview.

required
target str | int

A cluster id, or a position in the op's vertex_equivalences.

required
directory str | PathLike[str]

Where to write; created if missing.

required
views Sequence[View]

Which views to draw.

VIEWS
output_format str

svg, png, pdf or dot.

'svg'
stem str | None

File name stem.

None
prog str

Graphviz layout program.

'dot'
dpi int | None

Raster resolution, for png.

None

Returns:

Type Description
dict[View, Path]

The path written per view.

Raises:

Type Description
KeyError

target names no equivalence.

RuntimeError

Rendering is unavailable or failed; the message says why.

Source code in graflo/plot/equivalence.py
def plot_equivalence(
    preview: MergePreview,
    target: str | int,
    directory: str | os.PathLike[str],
    *,
    views: Sequence[View] = VIEWS,
    output_format: str = "svg",
    stem: str | None = None,
    prog: str = "dot",
    dpi: int | None = None,
) -> dict[View, Path]:
    """Draw *views* of one equivalence into *directory*; a view with nothing to show is skipped.

    Files are ``<stem>.<view>.<format>``; *stem* defaults to
    ``<kind>-<merged name>``, e.g. ``vertex-Machine.identity.svg``.

    Args:
        preview: The whole preview, from ``preview_merge`` or ``declared_preview``.
        target: A cluster id, or a position in the op's ``vertex_equivalences``.
        directory: Where to write; created if missing.
        views: Which views to draw.
        output_format: ``svg``, ``png``, ``pdf`` or ``dot``.
        stem: File name stem.
        prog: Graphviz layout program.
        dpi: Raster resolution, for ``png``.

    Returns:
        The path written per view.

    Raises:
        KeyError: *target* names no equivalence.
        RuntimeError: Rendering is unavailable or failed; the message says why.
    """
    out = Path(directory)
    focused = preview.focus(target)
    cluster = _cluster(focused)
    stem = stem or _slug(f"{cluster.kind}-{cluster.into or cluster.id}")
    written: dict[View, Path] = {}
    for view in views:
        graph = build_equivalence_view(preview, target, view)
        if graph is None:
            continue
        written[view] = _draw(
            graph,
            out / f"{stem}.{view}.{output_format}",
            output_format=output_format,
            prog=prog,
            dpi=dpi,
        )
    return written

plot_equivalences(preview, directory, *, select=(), views=VIEWS, output_format='svg', prog='dot', dpi=None)

Draw every selected equivalence into directory, with index.json and summary.md.

Parameters:

Name Type Description Default
preview MergePreview

The whole preview, after its outcome is folded in, so the finding positions in the index match preview.findings.

required
directory str | PathLike[str]

Where to write; created if missing.

required
select Sequence[str]

Patterns restricting the equivalences (see :func:select_targets).

()
views Sequence[View]

Which views to draw.

VIEWS
output_format str

svg, png, pdf or dot.

'svg'
prog str

Graphviz layout program.

'dot'
dpi int | None

Raster resolution, for png.

None

Returns:

Type Description
Path

The path of index.json.

Source code in graflo/plot/equivalence.py
def plot_equivalences(
    preview: MergePreview,
    directory: str | os.PathLike[str],
    *,
    select: Sequence[str] = (),
    views: Sequence[View] = VIEWS,
    output_format: str = "svg",
    prog: str = "dot",
    dpi: int | None = None,
) -> Path:
    """Draw every selected equivalence into *directory*, with ``index.json`` and ``summary.md``.

    Args:
        preview: The whole preview, after its outcome is folded in, so the
            finding positions in the index match ``preview.findings``.
        directory: Where to write; created if missing.
        select: Patterns restricting the equivalences (see :func:`select_targets`).
        views: Which views to draw.
        output_format: ``svg``, ``png``, ``pdf`` or ``dot``.
        prog: Graphviz layout program.
        dpi: Raster resolution, for ``png``.

    Returns:
        The path of ``index.json``.
    """
    from graflo.architecture.evolution.preview_focus import finding_positions

    out = Path(directory)
    out.mkdir(parents=True, exist_ok=True)
    taken: set[str] = set()
    entries: list[dict[str, Any]] = []
    held: set[int] = set()
    for cluster in _clusters(preview):
        held.update(finding_positions(preview, cluster.id))
    for target in select_targets(preview, select):
        cluster = next(c for c in preview.clusters if c.id == target)
        stem, n = _slug(f"{cluster.kind}-{cluster.into or cluster.id}"), 2
        unique = stem
        while unique.lower() in taken:
            unique, n = f"{stem}-{n}", n + 1
        taken.add(unique.lower())
        files = plot_equivalence(
            preview,
            target,
            out,
            views=views,
            output_format=output_format,
            stem=unique,
            prog=prog,
            dpi=dpi,
        )
        entries.append(
            {
                **_describe(preview, cluster),
                "views": {view: path.name for view, path in files.items()},
                "findings": [
                    _finding(preview, i) for i in finding_positions(preview, target)
                ],
            }
        )
    rest = [_finding(preview, i) for i in range(len(preview.findings)) if i not in held]
    index = out / "index.json"
    index.write_text(
        json.dumps(
            {
                "version": INDEX_VERSION,
                "left": preview.left_name,
                "right": preview.right_name,
                "outcome": preview.outcome.model_dump(mode="json"),
                "format": output_format,
                "summary": "summary.md",
                "equivalences": entries,
                "other_findings": rest,
            },
            indent=2,
        )
        + "\n"
    )
    (out / "summary.md").write_text(_summary(preview, entries, rest))
    return index

plot_history(history, path, *, heads=(), merge_base=None, output_format=None, prog='dot', dpi=None)

Draw the commit DAG of history to path.

Parameters:

Name Type Description Default
history Any

A :class:~graflo.architecture.evolution.history.History.

required
path str | PathLike[str]

Where to write; the suffix picks the format.

required
heads Collection[str]

Commit ids to mark as the sides being reconciled.

()
merge_base str | None

The common ancestor, marked as such.

None
output_format str | None

Override the format the suffix implies.

None
prog str

Graphviz layout program.

'dot'
dpi int | None

Raster resolution, for png.

None

Returns:

Type Description
Path

The path written.

Source code in graflo/plot/merge3.py
def plot_history(
    history: Any,
    path: str | os.PathLike[str],
    *,
    heads: Collection[str] = (),
    merge_base: str | None = None,
    output_format: str | None = None,
    prog: str = "dot",
    dpi: int | None = None,
) -> Path:
    """Draw the commit DAG of *history* to *path*.

    Args:
        history: A :class:`~graflo.architecture.evolution.history.History`.
        path: Where to write; the suffix picks the format.
        heads: Commit ids to mark as the sides being reconciled.
        merge_base: The common ancestor, marked as such.
        output_format: Override the format the suffix implies.
        prog: Graphviz layout program.
        dpi: Raster resolution, for ``png``.

    Returns:
        The path written.
    """
    graph = build_history_graph(history, heads=heads, merge_base=merge_base)
    return draw(to_dot(graph), path, output_format=output_format, prog=prog, dpi=dpi)

plot_merge3_preview(preview, path, *, output_format=None, prog='dot', dpi=None)

Draw the slot tree of preview to path.

Parameters:

Name Type Description Default
preview Merge3Preview

What build_merge3_preview returned.

required
path str | PathLike[str]

Where to write; the suffix picks the format (svg/pdf/png/dot).

required
output_format str | None

Override the format the suffix implies.

None
prog str

Graphviz layout program.

'dot'
dpi int | None

Raster resolution, for png.

None

Returns:

Type Description
Path

The path written.

Source code in graflo/plot/merge3.py
def plot_merge3_preview(
    preview: Merge3Preview,
    path: str | os.PathLike[str],
    *,
    output_format: str | None = None,
    prog: str = "dot",
    dpi: int | None = None,
) -> Path:
    """Draw the slot tree of *preview* to *path*.

    Args:
        preview: What ``build_merge3_preview`` returned.
        path: Where to write; the suffix picks the format (svg/pdf/png/dot).
        output_format: Override the format the suffix implies.
        prog: Graphviz layout program.
        dpi: Raster resolution, for ``png``.

    Returns:
        The path written.
    """
    graph = build_merge3_graph(preview)
    return draw(to_dot(graph), path, output_format=output_format, prog=prog, dpi=dpi)

plot_merge_preview(preview, path, *, output_format=None, prog='dot', dpi=None, max_rows=12, legend=True)

Draw preview to path.

Parameters:

Name Type Description Default
preview MergePreview

What preview_merge returned.

required
path str | PathLike[str]

Where to write; the suffix picks the format (svg/pdf/png/dot).

required
output_format str | None

Override the format the suffix implies.

None
prog str

Graphviz layout program.

'dot'
dpi int | None

Raster resolution, for png.

None
max_rows int

Attribute rows per class before the rest are summarised.

12
legend bool

Whether to draw the findings legend.

True

Returns:

Type Description
Path

The path written.

Raises:

Type Description
RuntimeError

Rendering is unavailable or failed; the message says why.

ValueError

The format is not one this can write.

Source code in graflo/plot/merge.py
def plot_merge_preview(
    preview: MergePreview,
    path: str | os.PathLike[str],
    *,
    output_format: str | None = None,
    prog: str = "dot",
    dpi: int | None = None,
    max_rows: int = 12,
    legend: bool = True,
) -> Path:
    """Draw *preview* to *path*.

    Args:
        preview: What ``preview_merge`` returned.
        path: Where to write; the suffix picks the format (svg/pdf/png/dot).
        output_format: Override the format the suffix implies.
        prog: Graphviz layout program.
        dpi: Raster resolution, for ``png``.
        max_rows: Attribute rows per class before the rest are summarised.
        legend: Whether to draw the findings legend.

    Returns:
        The path written.

    Raises:
        RuntimeError: Rendering is unavailable or failed; the message says why.
        ValueError: The format is not one this can write.
    """
    graph = build_preview_graph(preview, max_rows=max_rows, legend=legend)
    dot = to_dot(graph)
    _side_groups(graph, dot)
    return draw(dot, path, output_format=output_format, prog=prog, dpi=dpi)