Graphinate 0.12.0__py3-none-any.whl

graphinate/modeling.py

@@ -0,0 +1,337 @@
+import inspect
+import itertools
+from collections import defaultdict, namedtuple
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any, Union
+
+from .typing import Edge, Element, Extractor, Items, Node, NodeTypeAbsoluteId, UniverseNode
+
+
+class GraphModelError(Exception):
+    pass
+
+
+def element(element_type: str | None, field_names: Iterable[str] | None = None) -> Callable[[], Element]:
+    """Graph Element Supplier Callable
+
+    Args:
+        element_type:
+        field_names:
+
+    Returns:
+        Element Supplier Callable
+    """
+    return namedtuple(element_type, field_names) if element_type and field_names else tuple
+
+
+def extractor(obj: Any, key: Extractor | None = None) -> str | None:
+    """Extract data item from Element
+
+    Args:
+        obj:
+        key:
+
+    Returns:
+        Element data item
+    """
+    if key is None:
+        return obj
+
+    if callable(key):
+        return key(obj)
+
+    if isinstance(obj, Mapping) and isinstance(key, str):
+        return obj.get(key, key)
+
+    return key
+
+
+def elements(iterable: Iterable[Any],
+             element_type: Extractor | None = None,
+             **getters: Extractor) -> Iterable[Element]:
+    """Abstract Generator of Graph elements (nodes or edges)
+
+    Args:
+        iterable: source of payload
+        element_type: Optional[Extractor] source of type of the element. Defaults to Element Type name.
+        getters: Extractor node field sources
+
+    Returns:
+        Iterable of Elements.
+    """
+    for item in iterable:
+        _type = element_type(item) if element_type and callable(element_type) else element_type
+        if not _type.isidentifier():
+            raise ValueError(f"Invalid Type: {_type}. Must be a valid Python identifier.")
+
+        create_element = element(_type, getters.keys())
+        kwargs = {k: extractor(item, v) for k, v in getters.items()}
+        yield create_element(**kwargs)
+
+
+class Multiplicity(Enum):
+    ADD = auto()
+    ALL = auto()
+    FIRST = auto()
+    LAST = auto()
+
+
+@dataclass
+class NodeModel:
+    """Represents a Node Model
+
+    Args:
+        type: the type of the Node.
+        parent_type: the type of the node's parent. Defaults to UniverseNode.
+        parameters: parameters of the Node. Defaults to None.
+        label: label source. Defaults to None.
+        uniqueness: is the Node universally unique. Defaults to True.
+        multiplicity: Multiplicity of the Node. Defaults to ALL.
+        generator: Nodes generator method. Defaults to None.
+
+    Properties:
+        absolute_id: return the NodeModel absolute_id.
+    """
+
+    type: str
+    parent_type: str | UniverseNode | None = UniverseNode
+    parameters: set[str] | None = None
+    label: Callable[[Any], str | None] = None
+    uniqueness: bool = True
+    multiplicity: Multiplicity = Multiplicity.ALL
+    generator: Callable[[], Iterable[Node]] | None = None
+
+    @property
+    def absolute_id(self) -> NodeTypeAbsoluteId:
+        return self.parent_type, self.type
+
+
+class GraphModel:
+    """A Graph Model
+
+    Used to declaratively register Edge and/or Node data supplier functions by using
+    decorators.
+
+    Args:
+        name: the archetype name for Graphs generated based on the GraphModel.
+    """
+
+    def __init__(self, name: str):
+        self.name: str = name
+        self._node_models: dict[NodeTypeAbsoluteId, list[NodeModel]] = defaultdict(list)
+        self._node_children: dict[str, list[NodeModel]] = defaultdict(list)
+        self._edge_generators: dict[str, list[Callable[[], Iterable[Edge]]]] = defaultdict(list)
+        self._networkx_graph = None
+
+    def __add__(self, other: 'GraphModel') -> 'GraphModel':
+        graph_model = GraphModel(name=f"{self.name} + {other.name}")
+        for m in (self, other):
+            for k, v in m._node_models.items():
+                graph_model._node_models[k].extend(v)
+
+            for k, v in m._node_children.items():
+                graph_model._node_children[k].extend(v)
+
+            for k, v in m._edge_generators.items():
+                graph_model._edge_generators[k].extend(v)
+
+        return graph_model
+
+    @property
+    def node_models(self) -> dict[NodeTypeAbsoluteId, list[NodeModel]]:
+        """
+        Returns:
+            NodeModel for Node Types. Key values are NodeTypeAbsoluteId.
+        """
+        return self._node_models
+
+    @property
+    def edge_generators(self):
+        """
+        Returns:
+            Edge generator functions for Edge Types
+        """
+        return self._edge_generators
+
+    @property
+    def node_types(self) -> set[str]:
+        """
+        Returns:
+            Node Types
+        """
+        return {v.type for v in itertools.chain.from_iterable(self._node_models.values())}
+
+    def node_children_types(self, _type: str = UniverseNode) -> dict[str, list[str]]:
+        """Children Node Types for given input Node Type
+
+        Args:
+            _type:  Node Type. Default value is UNIVERSE_NODE.
+
+        Returns:
+            List of children Node Types.
+        """
+        return {k: v for k, v in self._node_children.items() if k == _type}
+
+    @staticmethod
+    def _validate_type(node_type: str):
+        if not callable(node_type) and not node_type.isidentifier():
+            raise ValueError(f"Invalid Type: {node_type}. Must be a valid Python identifier.")
+
+    def _validate_node_parameters(self, parameters: list[str]):
+        node_types = self.node_types
+        if not all(p.endswith('_id') and p == p.lower() and p[:-3] in node_types for p in parameters):
+            msg = ("Illegal Arguments. Argument should conform to the following rules: "
+                   "1) lowercase "
+                   "2) end with '_id' "
+                   "3) start with value that exists as registered node type")
+
+            raise GraphModelError(msg)
+
+    def node(self,
+             type_: Extractor | None = None,
+             parent_type: str | None = UniverseNode,
+             key: Extractor | None = None,
+             value: Extractor | None = None,
+             label: Extractor | None = None,
+             unique: bool = True,
+             multiplicity: Multiplicity = Multiplicity.ALL) -> Callable[[Items], None]:
+        """Decorator to Register a Generator of node payloads as a source for Graph Nodes.
+        It creates a NodeModel object.
+
+        Args:
+            type_: Optional source for the Node Type. Defaults to use Generator function
+                   name as the Node Type.
+            parent_type: Optional parent Node Type. Defaults to UNIVERSE_NODE
+
+            key: Optional source for Node IDs. Defaults to use the complete Node payload
+                 as Node ID.
+            value: Optional source for Node value field. Defaults to use the complete
+                   Node payload as Node ID.
+            label: Optional source for Node label field. Defaults to use a 'str'
+                   representation of the complete Node payload.
+            unique: is the Node universally unique. Defaults to True.
+            multiplicity: Multiplicity of the Node. Defaults to ALL.
+
+        Returns:
+            None
+        """
+
+        def register_node(f: Items):
+            node_type = type_ or f.__name__
+            self._validate_type(node_type)
+
+            model_type = f.__name__ if callable(node_type) else node_type
+
+            def node_generator(**kwargs: Any) -> Iterable[Node]:
+                yield from elements(f(**kwargs), node_type, key=key, value=value)
+
+            parameters = inspect.getfullargspec(f).args
+            node_model = NodeModel(type=model_type,
+                                   parent_type=parent_type,
+                                   parameters=set(parameters),
+                                   label=label,
+                                   uniqueness=unique,
+                                   multiplicity=multiplicity,
+                                   generator=node_generator)
+            self._node_models[node_model.absolute_id].append(node_model)
+            self._node_children[parent_type].append(model_type)
+
+            self._validate_node_parameters(parameters)
+
+        return register_node
+
+    def edge(self,
+             type_: Extractor | None = None,
+             source: Extractor = 'source',
+             target: Extractor = 'target',
+             label: Extractor | None = str,
+             value: Extractor | None = None,
+             weight: Union[float, Callable[[Any], float]] = 1.0,
+             ) -> Callable[[Items], None]:
+        """Decorator to Register a generator of edge payloads as a source of Graph Edges.
+         It creates an Edge generator function.
+
+        Args:
+            type_: Optional source for the Edge Type. Defaults to use Generator function
+                   name as the Edge Type.
+            source: Source for edge source Node ID.
+            target: Source for edge target Node ID.
+            label: Source for edge label.
+            value: Source for edge value.
+            weight: Source for edge weight.
+
+        Returns:
+            None.
+        """
+
+        def register_edge(f: Items):
+            edge_type = type_ or f.__name__
+            self._validate_type(edge_type)
+
+            model_type = f.__name__ if callable(edge_type) else edge_type
+
+            getters = {
+                'source': source,
+                'target': target,
+                'label': label,
+                'type': edge_type,
+                'value': value,
+                'weight': weight
+            }
+
+            def edge_generator(**kwargs: Any) -> Iterable[Edge]:
+                yield from elements(f(**kwargs), edge_type, **getters)
+
+            self._edge_generators[model_type].append(edge_generator)
+
+        return register_edge
+
+    def rectify(self, _type: Extractor | None = None,
+                parent_type: str | None = UniverseNode,
+                key: Extractor | None = None,
+                value: Extractor | None = None,
+                label: Extractor | None = None):
+        """
+        Rectify the model.
+        Add a default NodeModel in case of having just edge supplier/s and no node supplier/s.
+
+       Args:
+           _type
+           parent_type
+           key
+           value
+           label
+
+       Returns:
+           None
+        """
+        if self._edge_generators and not self._node_models:
+            @self.node(
+                type_=_type or 'node',
+                parent_type=parent_type or 'node',
+                unique=True,
+                key=key,
+                value=value,
+                label=label or str
+            )
+            def node():  # pragma: no cover
+                return
+                yield
+
+
+def model(name: str):
+    """
+    Create a graph model
+
+    Args:
+        name: model name
+
+    Returns:
+        GraphModel
+    """
+    return GraphModel(name=name)
+
+
+__all__ = ('GraphModel', 'Multiplicity', 'model')

graphinate/renderers/__init__.py

@@ -0,0 +1,5 @@
+import networkx_mermaid.formatters as mermaid
+
+from . import graphql, matplotlib
+
+__all__ = ('graphql', 'matplotlib', 'mermaid')

graphinate/renderers/graphql.py

@@ -0,0 +1,111 @@
+import contextlib
+import webbrowser
+from typing import Any
+
+import strawberry
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import RedirectResponse
+from starlette.schemas import SchemaGenerator
+from starlette.types import ASGIApp
+from strawberry.asgi import GraphQL
+
+from graphinate.server.starlette import routes
+
+DEFAULT_PORT: int = 8072
+
+GRAPHQL_ROUTE_PATH = "/graphql"
+
+
+def _openapi_schema(request: Request) -> ASGIApp:
+    """
+    Generates an OpenAPI schema for the GraphQL API and other routes.
+
+    Args:
+        request (Request): The HTTP request object.
+
+    Returns:
+        ASGIApp: An OpenAPI response containing the schema for the specified routes.
+    """
+    schema_data = {
+        'openapi': '3.0.0',
+        'info': {'title': 'Graphinate API', 'version': '0.10.1'},
+        'paths': {
+            '/graphql': {'get': {'responses': {200: {'description': 'GraphQL'}}}},
+            '/graphiql': {'get': {'responses': {200: {'description': 'GraphiQL UI.'}}}},
+            '/metrics': {'get': {'responses': {200: {'description': 'Prometheus metrics.'}}}},
+            '/viewer': {'get': {'responses': {200: {'description': '3D Force-Directed Graph Viewer'}}}},
+            '/voyager': {'get': {'responses': {200: {'description': 'Voyager GraphQL Schema Viewer'}}}}
+        }
+    }
+
+    schema = SchemaGenerator(schema_data)
+    return schema.OpenAPIResponse(request=request)
+
+
+def _graphql_app(graphql_schema: strawberry.Schema) -> strawberry.asgi.GraphQL:
+    """
+    Creates a Strawberry GraphQL app with the provided schema.
+    Args:
+        graphql_schema:
+
+    Returns:
+        strawberry.asgi.GraphQL: The GraphQL app configured with the provided schema.
+    """
+    graphql_app = GraphQL(graphql_schema, graphql_ide='apollo-sandbox')
+    return graphql_app
+
+
+def _starlette_app(graphql_app: strawberry.asgi.GraphQL | None = None,
+                   port: int = DEFAULT_PORT,
+                   **kwargs: Any) -> Starlette:
+    def open_url(endpoint):
+        webbrowser.open(f'http://localhost:{port}/{endpoint}')
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette):  # pragma: no cover
+        if kwargs.get('browse'):
+            open_url('viewer')
+        yield
+
+    app = Starlette(
+        lifespan=lifespan,
+        routes=routes()
+    )
+
+    from starlette_prometheus import PrometheusMiddleware, metrics
+    app.add_middleware(PrometheusMiddleware)
+    app.add_route("/metrics", metrics)
+
+    if graphql_app:
+        app.add_route(GRAPHQL_ROUTE_PATH, graphql_app)
+        app.add_websocket_route(GRAPHQL_ROUTE_PATH, graphql_app)
+        app.add_route("/schema", route=_openapi_schema, include_in_schema=False)
+        app.add_route("/openapi.json", route=_openapi_schema, include_in_schema=False)
+
+    def redirect_to_viewer(request):
+        return RedirectResponse(url='/viewer')
+
+    app.add_route('/', redirect_to_viewer)
+
+    return app
+
+
+def server(graphql_schema: strawberry.Schema, port: int = DEFAULT_PORT, **kwargs: Any):
+    """
+    Args:
+        graphql_schema: The Strawberry GraphQL schema.
+        port: The port number to run the server on. Defaults to 8072.
+
+    Returns:
+    """
+
+    graphql_app = _graphql_app(graphql_schema)
+
+    app = _starlette_app(graphql_app, port=port, **kwargs)
+
+    import uvicorn
+    uvicorn.run(app, host='0.0.0.0', port=port)
+
+
+__all__ = ['server']

graphinate/renderers/matplotlib.py

@@ -0,0 +1,82 @@
+from typing import Any
+
+import networkx as nx
+from matplotlib import pyplot
+
+from ..color import node_color_mapping
+
+
+def draw(graph: nx.Graph,
+         with_node_labels: bool = True,
+         with_edge_labels: bool = False,
+         **kwargs: Any) -> None:
+    """
+    Draws the given networkx graph with optional node and edge labels.
+
+    Args:
+        graph (nx.Graph): The input graph to be drawn.
+        with_node_labels (bool): Whether to display node labels. Default is True.
+        with_edge_labels (bool): Whether to display edge labels. Default is False.
+
+    Returns:
+        None
+    """
+    pos = nx.planar_layout(graph) if nx.is_planar(graph) else None
+    pos = nx.spring_layout(graph, pos=pos) if pos else nx.spring_layout(graph)
+
+    draw_params = {}
+    if with_node_labels:
+        draw_params.update(
+            {
+                'with_labels': True,
+                'labels': nx.get_node_attributes(graph, 'label'),
+                'font_size': 6,
+                'font_color': 'blue',
+                # 'horizontalalignment':'left',
+                # 'verticalalignment':'bottom',
+                # 'bbox': {
+                #     'boxstyle': 'round',
+                #     'fc': (0.02, 0.02, 0.02),
+                #     'lw': 0,
+                #     'alpha': 0.15,
+                #     'path_effects': [patheffects.withStroke(linewidth=1, foreground="red")]
+                # }
+            }
+        )
+
+    node_color = list(node_color_mapping(graph).values())
+    nx.draw(graph, pos, node_color=node_color, **draw_params)
+    if with_edge_labels:
+        nx.draw_networkx_edge_labels(graph,
+                                     pos,
+                                     edge_labels=nx.get_edge_attributes(graph, 'label'),
+                                     font_color='red',
+                                     font_size=6)
+
+
+def plot(graph: nx.Graph,
+         with_node_labels: bool = True,
+         with_edge_labels: bool = False,
+         **kwargs: Any) -> None:
+    """
+    Plots the given networkx graph with optional node and edge labels.
+
+    Args:
+        graph (nx.Graph): The input graph to be plotted.
+        with_node_labels (bool): Whether to display node labels. Default is True.
+        with_edge_labels (bool): Whether to display edge labels. Default is False.
+
+    Returns:
+        None
+    """
+    draw(graph, with_node_labels, with_edge_labels, **kwargs)
+
+    ax = pyplot.gca()
+    ax.margins(0.10)
+
+    fig = pyplot.gcf()
+    fig.suptitle(graph.name)
+    fig.tight_layout()
+
+    # pyplot.axis("off")
+    pyplot.show()

graphinate/server/starlette/__init__.py

@@ -0,0 +1,31 @@
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from starlette.routing import BaseRoute, Mount
+from starlette.staticfiles import StaticFiles
+
+from ..web import paths_mapping
+from .views import favicon_route
+
+
+def _mount_static_files(named_paths: Mapping[str, Path]) -> list[Mount]:
+    mounts = []
+    for name, path in named_paths.items():
+        if not name.startswith('__'):
+            index_file = path / 'index.html'
+            static_files = StaticFiles(directory=path, html=index_file.exists(), check_dir=True)
+            mount = Mount(path=f"/{name}", app=static_files, name=name)
+            mounts.append(mount)
+    return mounts
+
+
+def routes() -> Sequence[BaseRoute]:
+    route_list: list[BaseRoute] = [
+        *_mount_static_files(paths_mapping),
+        favicon_route()
+    ]
+
+    return route_list
+
+
+__all__ = ('routes',)

graphinate/server/starlette/views.py

@@ -0,0 +1,17 @@
+import functools
+
+from starlette.requests import Request
+from starlette.responses import FileResponse
+from starlette.routing import Route
+
+from ..web import get_static_path
+
+
+def favicon(request: Request) -> FileResponse:
+    path = get_static_path('images/logo-128.png').absolute().as_posix()
+    return FileResponse(path)
+
+
+@functools.cache
+def favicon_route() -> Route:
+    return Route('/favicon.ico', endpoint=favicon, include_in_schema=False)

graphinate/server/web/__init__.py

@@ -0,0 +1,25 @@
+import inspect
+import pathlib
+from collections.abc import Generator, Mapping
+from typing import Any
+
+
+def current_file() -> pathlib.Path | None:
+    """Returns current file name"""
+    if (current_frame := inspect.currentframe()) and current_frame.f_back is not None:
+        return pathlib.Path(inspect.getfile(current_frame.f_back))
+    return None
+
+
+def _current_file_peers() -> Generator[tuple[str, pathlib.Path], Any, None]:
+    _current_file = current_file()
+    if _current_file is not None:
+        for p in _current_file.parent.iterdir():
+            yield p.name, p
+
+
+paths_mapping: Mapping[str, pathlib.Path] = dict(_current_file_peers())
+
+
+def get_static_path(relative_path: str) -> pathlib.Path:
+    return paths_mapping['static'] / relative_path

graphinate/server/web/elements/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+
+    <title>Graphinate - OpanAPI Elements UI</title>
+    <!-- Embed elements Elements via Web Component -->
+    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"
+            integrity="sha384-yR4p7dGVb43Z+zDGOg8xyIj71nVRZvN/IpUbptwjAtxcq+IcVQ+mNMiL7ppakjKc"></script>
+    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css"
+          integrity="sha384-fgRmJCkCe8Qyv2rSIDjIvkm779dv+HZbSa/ptwSeufq8qJZo/xsi79N8Rb6xTIMO">
+</head>
+<body>
+
+<elements-api
+        apiDescriptionUrl="/schema"
+        router="hash"
+        layout="sidebar"
+/>
+
+</body>
+</html>