Graphinate 0.12.0__py3-none-any.whl

graphinate/__init__.py

@@ -0,0 +1,18 @@
+from . import builders, renderers
+from .builders import build
+from .enums import GraphType
+from .modeling import GraphModel, Multiplicity, model
+from .renderers import graphql, matplotlib, mermaid
+
+__all__ = (
+    'GraphModel',
+    'GraphType',
+    'Multiplicity',
+    'build',
+    'builders',
+    'graphql',
+    'matplotlib',
+    'mermaid',
+    'model',
+    'renderers'
+)

graphinate/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli  # pragma: no cover
+
+if __name__ == '__main__':  # pragma: no cover
+    cli()

graphinate/builders/__init__.py

@@ -0,0 +1,55 @@
+"""Builder Classes: Abstraction Layer to Generate Graph Data Structures
+
+This module defines builder base classes and implementations that construct graph
+data structures from a `GraphModel`. It supports generating various graph formats,
+including NetworkX, D3, Mermaid, and GraphQL schema representations.
+
+Attributes:
+    - **GraphRepresentation:** Types of representations the builder can produce.
+    - **GraphType:** Enumeration for different graph types (directed, undirected, etc.).
+
+Main Classes:
+    - `GraphType`    : Enum defining networkx-compatible graph types.
+    - `Builder`      : Abstract base class for custom graph builders.
+    - `NetworkxBuilder` : A builder class for constructing Graph representations using NetworkX.
+    - `D3Builder`    : Builder class transforming graphs into D3-compatible structures.
+    - `MermaidBuilder`: Supports MermaidJS diagram generation.
+    - `GraphQLBuilder`: Constructs GraphQL schema representations of graphs.
+"""
+
+__all__ = ['Builder', 'D3Builder', 'GraphQLBuilder', 'MermaidBuilder', 'NetworkxBuilder', 'build']
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..enums import GraphType
+from ..modeling import GraphModel
+from ._builder import Builder
+from ._d3 import D3Builder
+from ._graphql import GraphQLBuilder
+from ._mermaid import MermaidBuilder
+from ._networkx import NetworkxBuilder
+
+
+def build(builder_cls: type[Builder],
+          graph_model: GraphModel,
+          graph_type: GraphType = GraphType.Graph,
+          default_node_attributes: Mapping | None = None,
+          **kwargs: Any) -> Any:
+    """
+    Build a graph from a graph model
+
+    Args:
+        builder_cls: builder class type
+        graph_model: a GraphModel instance
+        graph_type: type of the generated graph
+        default_node_attributes: default node attributes
+        **kwargs: node id values
+
+    Returns:
+         Graph data structure
+    """
+
+    builder = builder_cls(graph_model, graph_type)
+    materialized_graph = builder.build(default_node_attributes=default_node_attributes, **kwargs)
+    return materialized_graph

graphinate/builders/_builder.py

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ..converters import edge_label_converter, node_label_converter
+from ..enums import GraphType
+from ..modeling import GraphModel
+from ..typing import GraphRepresentation
+
+
+class Builder(ABC):
+    """Abstract Base Class for Graph Builders.
+
+    This class acts as a blueprint for all concrete builders that generate graph-like
+    data structures from a given `GraphModel`.
+
+    Attributes:
+        default_node_attributes (Mapping): Default attributes for all nodes.
+        default_edge_attributes (Mapping): Default attributes for all edges.
+    """
+
+    default_node_attributes: Mapping = MappingProxyType({
+        'type': 'node',
+        'label': node_label_converter,
+        'value': [],
+        'lineage': None
+    })
+
+    default_edge_attributes: Mapping = MappingProxyType({
+        'type': 'edge',
+        'label': edge_label_converter,
+        'value': [],
+        'weight': 1.0
+    })
+
+    def __init__(self, model: GraphModel, graph_type: GraphType = GraphType.Graph):
+        """Initialize a Builder instance with a specific graph model and type.
+
+        Args:
+            model (GraphModel): The model defining the graph's structure and data.
+            graph_type (GraphType): Enum specifying the type of the graph.
+        """
+
+        self._cached_build_kwargs: dict[str, Any] = {}
+        self.model = model
+        self.graph_type = graph_type
+
+    @abstractmethod
+    def build(self, **kwargs: Any) -> GraphRepresentation:
+        """Build the graph representation.
+
+        Subclasses must override this method to implement specific build logic.
+
+        Args:
+            **kwargs: Any additional parameters for the build process.
+        """
+        self._cached_build_kwargs = MappingProxyType(kwargs)

graphinate/builders/_d3.py

@@ -0,0 +1,61 @@
+import json
+from collections.abc import Iterable, Mapping
+from datetime import datetime, timedelta
+from typing import Any, Literal
+
+import mappingtools
+import networkx as nx
+
+from .. import color
+from ..enums import GraphType
+from ..modeling import GraphModel
+from ._networkx import NetworkxBuilder
+
+
+def _convert(obj: Any) -> Any:
+    """if obj is a not python scalar (e.g. it's some sort of container)
+    then return it as is otherwise convert it to a JSON string"""
+    match obj:
+        case bytes():
+            return obj.decode()
+        case datetime():
+            return obj.isoformat()
+        case timedelta():
+            return f"{obj.total_seconds()} s"
+        case Mapping() | Iterable() | str():
+            return obj
+        case _:
+            return json.dumps(obj, default=str)
+
+
+class D3Builder(NetworkxBuilder):
+    """Build a D3 Graph"""
+
+    def __init__(self, model: GraphModel, graph_type: GraphType = GraphType.Graph):
+        super().__init__(model, graph_type)
+
+    def build(self, values_format: Literal['json', 'python'] = 'python', **kwargs: Any) -> dict:
+        """
+        Args:
+            values_format: Literal['python', 'json'] - The format of the values
+            **kwargs:
+
+        Returns:
+            D3 Graph
+        """
+        super().build(**kwargs)
+        color.convert_colors_to_hex(self._graph)
+        d3graph: dict = self.from_networkx(self._graph)
+
+        match values_format:
+            case 'json':
+                return mappingtools.transformers.strictify(d3graph, value_converter=_convert)
+            case 'python':
+                return d3graph
+            case _:
+                raise ValueError(f"Invalid values format: {values_format}")
+
+    @staticmethod
+    def from_networkx(nx_graph: nx.Graph) -> dict:
+        d3_graph: dict = nx.node_link_data(nx_graph, nodes='nodes', edges='links')
+        return d3_graph