Graphinate 0.12.0__py3-none-any.whl

graphinate/builders/_networkx.py

@@ -0,0 +1,227 @@
+import operator
+from collections import Counter
+from collections.abc import Callable, Hashable, Mapping
+from typing import Any, Union
+
+import networkx as nx
+from loguru import logger
+from mappingtools.transformers import simplify
+from networkx.classes.reportviews import EdgeDataView, EdgeView, NodeDataView, NodeView
+
+from .. import color
+from ..enums import GraphType
+from ..modeling import GraphModel, Multiplicity
+from ..tools import utcnow
+from ..typing import NodeTypeAbsoluteId, UniverseNode
+from ._builder import Builder
+
+
+class NetworkxBuilder(Builder):
+    """Build a NetworkX Graph"""
+
+    def __init__(self, model: GraphModel, graph_type: GraphType = GraphType.Graph):
+        super().__init__(model, graph_type)
+        self._graph: nx.Graph | None = None
+
+    def _initialize_graph(self):
+        """Initialize an empty NetworkX graph with metadata and default attributes."""
+        self._graph: nx.Graph = self.graph_type.value(name=self.model.name,
+                                                      node_types=Counter(),
+                                                      edge_types=Counter())
+
+    def _graph_edges(self, data, default=None):
+        params = {'data': data, 'default': default}
+
+        if isinstance(self._graph, nx.MultiGraph):
+            params['keys'] = True
+
+        return self._graph.edges(**params)
+
+    def _populate_node_type(self, node_type: Union[Hashable, UniverseNode] = UniverseNode, **kwargs):
+        for parent_node_type, child_node_types in self.model.node_children_types(node_type).items():
+            for child_node_type in child_node_types:
+                node_type_absolute_id = (parent_node_type, child_node_type)
+                self._populate_nodes(node_type_absolute_id, **kwargs)
+
+    @staticmethod
+    def _parent_node_id(node_type_absolute_id: NodeTypeAbsoluteId, **kwargs: Any):
+        if node_type_absolute_id[0] is UniverseNode:
+            return UniverseNode
+
+        ids = []
+        for k, v in kwargs.items():
+            if k[:-3] == node_type_absolute_id[1]:
+                break
+            ids.append(v)
+
+        return tuple(ids)
+
+    def _populate_nodes(self, node_type_absolute_id: NodeTypeAbsoluteId, **kwargs: Any):
+        """Populate graph nodes based on the provided model and ID."""
+        for node_model in self.model.node_models[node_type_absolute_id]:
+            unique = node_model.uniqueness
+            for node in node_model.generator(**kwargs):
+                parent_node_id = self._parent_node_id(node_type_absolute_id, **kwargs)
+                node_lineage = (*parent_node_id, node.key) if parent_node_id is not UniverseNode else (node.key,)
+                node_id = (node.key,) if unique else node_lineage
+
+                label = node.key
+                if node_model.label is not None:
+                    label = node_model.label(node.value) if callable(node_model.label) else node_model.label
+
+                node_type = node.__class__.__name__.lower()
+                if node_type == 'tuple':
+                    node_type = node_model.type.lower()
+
+                if node_id in self._graph:
+                    logger.debug("Updating node. ID: {}, Label: {}", node_id, label)
+
+                    match node_model.multiplicity:
+                        case Multiplicity.ADD:
+                            self._graph.nodes[node_id]['value'] = [self._graph.nodes[node_id]['value'] + node.value]
+                        case Multiplicity.ALL:
+                            self._graph.nodes[node_id]['value'].append(node.value)
+                        case Multiplicity.FIRST:
+                            ...
+                        case Multiplicity.LAST:
+                            self._graph.nodes[node_id]['value'] = [node.value]
+
+                    self._graph.nodes[node_id]['magnitude'] += 1
+                    self._graph.nodes[node_id]['updated'] = utcnow()
+                else:
+                    logger.debug("Adding node. ID: {}, Label: {}", node_id, label)
+                    self._graph.add_node(node_id,
+                                         label=label,
+                                         type=node_type,
+                                         value=[node.value],
+                                         magnitude=1,
+                                         lineage=list(node_lineage),
+                                         created=utcnow())
+
+                    self._graph.graph['node_types'].update({node_type: 1})
+
+                if node_model.parent_type is not UniverseNode:
+                    logger.debug("Adding edge. Source: {}, Target: {}", parent_node_id, node_id)
+                    self._graph.add_edge(parent_node_id,
+                                         node_id,
+                                         created=utcnow())
+
+                new_kwargs = kwargs.copy()
+                new_kwargs[f"{node_type}_id"] = node.key
+                self._populate_node_type(node_model.type, **new_kwargs)
+
+    def _populate_edges(self, **kwargs: Any):
+        """Populate graph edges based on defined connections."""
+        for edge_model, edge_generators in self.model.edge_generators.items():
+            for edge_generator in edge_generators:
+                for edge in edge_generator(**kwargs):
+                    edge_id = ((edge.source,), (edge.target,))
+                    edge_label = edge.label(edge_id) if callable(edge.label) else edge.label
+                    edge_weight = edge.weight or 1.0
+                    edge_type = edge.type.lower()
+                    logger.debug("Adding edge. Source: {}, Target: {}", *edge_id)
+
+                    if isinstance(self._graph, nx.MultiGraph) or edge_id not in self._graph.edges:
+                        self._graph.add_edge(*edge_id,
+                                             label=edge_label,
+                                             type=edge_type,
+                                             value=[edge.value],
+                                             weight=edge_weight,
+                                             created=utcnow())
+                        self._graph.graph['edge_types'].update({edge_type: 1})
+                    else:
+                        self._graph.edges[edge_id]['value'].append(edge.value)
+                        self._graph.edges[edge_id]['weight'] += edge_weight
+                        self._graph.edges[edge_id]['updated'] = utcnow()
+
+    @staticmethod
+    def _rectified_values(name: str, default: Any, elements: Callable[
+        [str, Any], NodeView[Any] | EdgeView[Any] | NodeDataView[Any] | EdgeDataView], k: Callable[[Any], Any],
+                          v: Callable[[Any], Any]) -> dict:
+        if callable(default):
+            elem = elements(data=name, default=None)
+            return {k(e): default(k(e))
+                    for e in elem
+                    if (v(e) is None if isinstance(elem, NodeDataView) else v(e) is not None)}
+        elif isinstance(default, dict):
+            return default
+        elif default:
+            return {k(e): v(e) for e in elements(data=name, default=default) if v(e) == default}
+        else:  # default is None or empty collection
+            return {k(e): k(e) for e in elements(data=name, default=default) if v(e) is default}
+
+    def _rectify_node_attributes(self, **defaults):
+        for name, default in defaults.items():
+            if values := self._rectified_values(
+                    name,
+                    default,
+                    self._graph.nodes,
+                    operator.itemgetter(0),
+                    operator.itemgetter(1),
+            ):
+                nx.set_node_attributes(self._graph, values=values, name=name)
+
+        if default_type := defaults.get('type'):
+            type_count = sum(1 for n, d in self._graph.nodes(data='type') if d == default_type)
+            if type_count:
+                self._graph.graph['node_types'].update({default_type: type_count})
+
+    def _rectify_edge_attributes(self, **defaults):
+        for name, default in defaults.items():
+            if values := self._rectified_values(
+                    name,
+                    default,
+                    self._graph_edges,
+                    lambda x: tuple(x[:-1]),
+                    lambda x: x[-1]
+            ):
+                nx.set_edge_attributes(self._graph, values=values, name=name)
+
+        if default_type := defaults.get('type'):
+            type_count = sum(1 for *_, d in self._graph_edges(data='type') if d == default_type)
+            if type_count:
+                self._graph.graph['edge_types'].update({default_type: type_count})
+
+    def _finalize_graph(self, **node_attributes):
+        self._rectify_node_attributes(**node_attributes)
+
+        if 'color' not in node_attributes:
+            self._rectify_node_attributes(color=color.node_color_mapping(self._graph))
+
+        self._rectify_edge_attributes(**self.default_edge_attributes)
+
+        for counter_name in ('node_types', 'edge_types'):
+            counter = self._graph.graph[counter_name]
+            self._graph.graph[counter_name] = simplify(counter)
+
+        self._graph.graph['created'] = utcnow()
+
+    def _rectify_model(self, node_attributes: Mapping):
+        default_type = node_attributes.get('type')
+        default_label = node_attributes.get('label')
+        self.model.rectify(_type=default_type, parent_type=default_type, label=default_label)
+
+    def _build_graph(self, node_attributes: Mapping, **kwargs: Any):
+        self._initialize_graph()
+        self._populate_node_type(**kwargs)
+        self._populate_edges(**kwargs)
+        self._finalize_graph(**node_attributes)
+
+    def build(self, **kwargs: Any) -> nx.Graph:
+        """Build a NetworkX graph representation.
+
+        Args:
+            **kwargs:
+
+        Returns:
+            NetworkX Graph
+        """
+        super().build(**kwargs)
+
+        default_node_attributes = dict(**self.default_node_attributes)
+        if 'default_node_attributes' in kwargs:
+            default_node_attributes.update(kwargs.pop('default_node_attributes') or {})
+
+        self._rectify_model(default_node_attributes)
+        self._build_graph(default_node_attributes, **kwargs)
+        return self._graph

graphinate/cli.py

@@ -0,0 +1,123 @@
+import importlib
+import json
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+import click
+from strawberry import Schema
+
+from . import GraphModel, builders, graphql
+from .renderers.graphql import DEFAULT_PORT
+
+
+def _get_kwargs(ctx: click.Context) -> dict:
+    return dict([item.strip('--').split('=') for item in ctx.args if item.startswith("--")])  # NOSONAR
+
+
+def import_from_string(import_str: str) -> GraphModel:
+    """Import an object from a string reference {module-name}:{variable-name}
+    For example, if `model: GraphModel = GraphModel(...)` is a variable defined in an app.py file,
+     then the reference would be app:model.
+    """
+
+    if not isinstance(import_str, str):
+        raise ImportFromStringError(f"{import_str} is not a string")
+
+    module_name, _, attrs_names_str = import_str.partition(':')
+    if not module_name or not attrs_names_str:
+        message = f"Import string '{import_str}' must be in format '<module>:<attribute>'."
+        raise ImportFromStringError(message)
+
+    try:
+        module: ModuleType = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != module_name:
+            raise exc from None
+        message = f"Could not import module '{module_name}'."
+        raise ImportFromStringError(message) from exc
+
+    instance_candidate: ModuleType | GraphModel = module
+    try:
+        for attr_name in attrs_names_str.split('.'):
+            instance_candidate = getattr(instance_candidate, attr_name)
+    except AttributeError as e:
+        message = f"Attribute '{attrs_names_str}' not found in import string reference '{import_str}'."
+        raise ImportFromStringError(message) from e
+
+    if isinstance(instance_candidate, GraphModel):
+        return instance_candidate
+    else:
+        raise ImportFromStringError(f"GraphModel instance cannot be determined from reference '{import_str}'")
+
+
+class ImportFromStringError(Exception):
+    pass
+
+
+class GraphModelType(click.ParamType):
+    name = "MODEL"
+
+    def convert(self,
+                value: Any,
+                param: click.Parameter | None,
+                ctx: click.Context) -> GraphModel:  # type: ignore[override]
+        if isinstance(value, GraphModel):
+            return value
+
+        try:
+            return import_from_string(value)
+        except Exception as e:
+            self.fail(str(e))
+
+
+model_option = click.option('-m', '--model',
+                            type=GraphModelType(),
+                            help="A GraphModel instance reference {module-name}:{GraphModel-instance-variable-name}"
+                                 " For example given a var `model=GraphModel()` defined in app.py file, then the"
+                                 " reference would be app:model")
+
+
+@click.group()
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    ctx.ensure_object(dict)
+
+
+@cli.command()
+@model_option
+@click.pass_context
+def save(ctx: click.Context, model: GraphModel) -> None:
+    file_path = Path(f"{model.name}.d3_graph.json")
+
+    if file_path.is_absolute():
+        raise click.ClickException("Please provide a relative file path for saving the graph.")
+
+    if file_path.parent != Path('.'):
+        raise click.ClickException("Saving to subdirectories is not supported. Please provide a file name only.")
+
+    if file_path.exists():
+        click.confirm(f"The file '{file_path}' already exists. Do you want to overwrite it?", abort=True)
+
+    kwargs = _get_kwargs(ctx)
+    with open(file_path, mode='w') as fp:
+        graph = builders.D3Builder(model, **kwargs).build()
+        json.dump(graph, fp=fp, default=str, **kwargs)
+
+
+@cli.command()
+@model_option
+@click.option('-p', '--port', type=int, default=DEFAULT_PORT, help='Port number.')
+@click.option('-b', '--browse', type=bool, default=False, help='Open server address in browser.')
+@click.pass_context
+def server(ctx: click.Context, model: GraphModel, port: int, browse: bool) -> None:
+    message = """
+     ██████╗ ██████╗  █████╗ ██████╗ ██╗  ██╗██╗███╗   ██╗ █████╗ ████████╗███████╗
+    ██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║  ██║██║████╗  ██║██╔══██╗╚══██╔══╝██╔════╝
+    ██║  ███╗██████╔╝███████║██████╔╝███████║██║██╔██╗ ██║███████║   ██║   █████╗
+    ██║   ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║██║██║╚██╗██║██╔══██║   ██║   ██╔══╝
+    ╚██████╔╝██║  ██║██║  ██║██║     ██║  ██║██║██║ ╚████║██║  ██║   ██║   ███████╗
+     ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝   ╚═╝   ╚══════╝"""
+    click.echo(message)
+    schema: Schema = builders.GraphQLBuilder(model).build()
+    graphql.server(schema, port=port, browse=browse, **_get_kwargs(ctx))

graphinate/color.py

@@ -0,0 +1,100 @@
+import functools
+from collections.abc import Mapping, Sequence
+from typing import Union
+
+import matplotlib as mpl
+import networkx as nx
+import numpy as np
+
+
+@functools.lru_cache
+def node_color_mapping(graph: nx.Graph, cmap: Union[str, mpl.colors.Colormap] = "tab20") -> Mapping:
+    """Map node types to RGBA colors based on a colormap.
+    Args:
+        graph: nx.Graph - The input graph for which node colors need to be mapped.
+        cmap: Union[str, mpl.colors.Colormap], optional - The colormap used to map values to RGBA colors.
+              Default is "tab20".
+    Returns:
+        Mapping - A dictionary mapping nodes to their corresponding RGBA colors based on the colormap.
+
+    .. note::
+        The graph should have a 'node_types' attribute containing the types of nodes.
+        The colormap can be specified as a string or a matplotlib colormap object.
+    """
+    if not graph.nodes:
+        return {}
+
+    node_type_keys = graph.graph.get('node_types', {}).keys()
+
+    if len(node_type_keys) > 1 and 'node' in node_type_keys:
+        # Create a new list of keys, preserving order, but excluding 'node'
+        final_keys = [k for k in node_type_keys if k != 'node']
+    else:
+        final_keys = list(node_type_keys)
+
+    type_lookup = {t: i for i, t in enumerate(final_keys)}
+
+    color_values_ndarray = np.fromiter(
+        (type_lookup.get(graph.nodes[node].get('type'), 0) for node in graph.nodes),
+        dtype=int,
+        count=len(graph),
+    )
+    if len(color_values_ndarray) > 1:
+        low, high = color_values_ndarray.min(), color_values_ndarray.max()
+    else:
+        low = high = 0
+
+    norm = mpl.colors.Normalize(vmin=low, vmax=high, clip=True)
+    mapper = mpl.cm.ScalarMappable(norm=norm, cmap=cmap)
+    colors = mapper.to_rgba(color_values_ndarray).tolist()
+
+    color_mapping = dict(zip(graph.nodes, colors))
+    return color_mapping
+
+
+def color_hex(color: Union[str, Sequence[Union[float, int]]]) -> Union[str, Sequence[Union[float, int]]]:
+    """Get HEX color code
+
+    Args:
+        color: input color
+    Returns:
+         Color HEX code
+
+    .. note::
+        If the input is a tuple or list, it should contain either three floats (0-1) or three ints (0-255).
+        The function will convert these to a HEX color code.
+    """
+    if isinstance(color, (tuple, list)):
+        rgb = color[:3]
+
+        if all(isinstance(c, float) and 0 <= c <= 1 for c in rgb):
+            rgb = tuple(int(c * 255) for c in rgb)
+        elif all(isinstance(c, int) and 0 <= c <= 255 for c in rgb):
+            rgb = tuple(rgb)
+        else:
+            msg = "Input values should either be a float between 0 and 1 or an int between 0 and 255"
+            raise ValueError(msg)
+
+        r, g, b = rgb
+        return f'#{r:02x}{g:02x}{b:02x}'
+
+    else:
+        return color
+
+
+def convert_colors_to_hex(graph: nx.Graph, color: str = 'color') -> None:
+    """Convert all color labels in the graph to hexadecimal format.
+
+    Args:
+        graph (nx.Graph): The input graph with node attributes.
+        color (str): The attribute name for the color. Default is 'color'.
+
+    Returns:
+        None: The function modifies the graph in place.
+
+    .. note::
+       This function assumes that the color attribute is present in the node data.
+    """
+
+    color_values = {node: color_hex(data[color]) for node, data in graph.nodes(data=True) if color in data}
+    nx.set_node_attributes(graph, values=color_values, name=color)

graphinate/constants.py

@@ -0,0 +1,4 @@
+DEFAULT_NODE_DELIMITER = ' ∋ '
+DEFAULT_EDGE_DELIMITER = ' ⟹ '
+
+__all__ = ['DEFAULT_EDGE_DELIMITER', 'DEFAULT_NODE_DELIMITER']

graphinate/converters.py

@@ -0,0 +1,94 @@
+import ast
+import base64
+import decimal
+import math
+from types import MappingProxyType
+from typing import Any, Union
+
+import strawberry
+
+from .constants import DEFAULT_EDGE_DELIMITER, DEFAULT_NODE_DELIMITER
+
+__all__ = [
+    'InfNumber',
+    'decode_edge_id',
+    'decode_id',
+    'edge_label_converter',
+    'encode_edge_id',
+    'encode_id',
+    'infnum_to_value',
+    'label_converter',
+    'node_label_converter',
+    'value_to_infnum',
+]
+
+InfNumber = Union[float, int, decimal.Decimal]
+
+INFINITY_MAPPING: MappingProxyType[str, InfNumber] = MappingProxyType({
+    'Infinity': math.inf,
+    '+Infinity': math.inf,
+    '-Infinity': -math.inf
+})
+
+MATH_INF_MAPPING: MappingProxyType[InfNumber, str] = MappingProxyType({
+    math.inf: 'Infinity',
+    -math.inf: '-Infinity'
+})
+
+
+def value_to_infnum(value: str | InfNumber) -> InfNumber:
+    return INFINITY_MAPPING.get(value, value)
+
+
+def infnum_to_value(value: InfNumber) -> InfNumber | str:
+    return MATH_INF_MAPPING.get(value, value)
+
+
+def label_converter(value: Any, delimiter: str) -> str | None:
+    if value is not None:
+        return delimiter.join(str(v) for v in value) if isinstance(value, tuple) else str(value)
+    return value
+
+
+def node_label_converter(value: Any) -> str | None:
+    return label_converter(value, delimiter=DEFAULT_NODE_DELIMITER)
+
+
+def edge_label_converter(value: Any) -> str | None:
+    return label_converter(tuple(node_label_converter(n) for n in value), delimiter=DEFAULT_EDGE_DELIMITER)
+
+
+def encode(value: Any, encoding: str = 'utf-8') -> str:
+    obj_s: str = repr(value)
+    obj_b: bytes = obj_s.encode(encoding)
+    enc_b: bytes = base64.urlsafe_b64encode(obj_b)
+    enc_s: str = enc_b.decode(encoding)
+    return enc_s
+
+
+def decode(value: str, encoding: str = 'utf-8') -> Any:
+    enc_b: bytes = value.encode(encoding)
+    obj_b: bytes = base64.urlsafe_b64decode(enc_b)
+    obj_s: str = obj_b.decode(encoding)
+    obj: Any = ast.literal_eval(obj_s)
+    return obj
+
+
+def encode_id(graph_node_id: tuple,
+              encoding: str = 'utf-8') -> str:
+    return encode(graph_node_id, encoding)
+
+
+def decode_id(graphql_node_id: strawberry.ID,
+              encoding: str = 'utf-8') -> tuple[str, ...]:
+    return decode(graphql_node_id, encoding)
+
+
+def encode_edge_id(edge: tuple, encoding: str = 'utf-8') -> str:
+    encoded_edge = tuple(encode_id(n, encoding) for n in edge)
+    return encode_id(encoded_edge, encoding)
+
+
+def decode_edge_id(graphql_edge_id: strawberry.ID, encoding: str = 'utf-8') -> tuple:
+    encoded_edge: tuple = decode_id(graphql_edge_id, encoding)
+    return tuple(decode_id(enc_node) for enc_node in encoded_edge)

graphinate/enums.py

@@ -0,0 +1,44 @@
+from enum import Enum
+
+import networkx as nx
+from typing_extensions import Self
+
+
+class GraphType(Enum):
+    """Graph Types
+
+    The choice of graph class depends on the structure of the graph you want to represent.
+
+    | **Graph Type** | **Type**   | **Self-loops allowed** | **Parallel edges allowed** |
+    |----------------|------------|:----------------------:|:--------------------------:|
+    | Graph          | Undirected | Yes                    | No                         |
+    | DiGraph        | Directed   | Yes                    | No                         |
+    | MultiGraph     | Undirected | Yes                    | Yes                        |
+    | MultiDiGraph   | Directed   | Yes                    | Yes                        |
+
+    See more here: [NetworkX Reference](https://networkx.org/documentation/stable/reference/classes)
+    """
+
+    Graph = nx.Graph
+    DiGraph = nx.DiGraph
+    MultiDiGraph = nx.MultiDiGraph
+    MultiGraph = nx.MultiGraph
+
+    @classmethod
+    def of(cls, graph: nx.Graph) -> Self:
+        """Determine the graph type based on structure and properties.
+
+        Args:
+            graph (nx.Graph): A NetworkX graph object.
+
+        Returns:
+            GraphType: An instance of this Enum matching the input graph.
+        """
+        if graph.is_directed() and graph.is_multigraph():
+            return cls.MultiDiGraph
+        elif graph.is_directed():
+            return cls.DiGraph
+        elif graph.is_multigraph():
+            return cls.MultiGraph
+        else:
+            return cls.Graph