st-graph-workbench 0.1.0__py3-none-any.whl

st_graph_workbench/__init__.py

@@ -0,0 +1,115 @@
+from st_graph_workbench.component.component import (
+    AnalysisAction,
+    CrudAction,
+    EditAction,
+    ElementsSync,
+    NodeAction,
+    PerformanceProfile,
+    SelectionMode,
+    ViewportAction,
+    graph_workbench,
+)
+from st_graph_workbench.component.styles import NodeStyle, EdgeStyle, StyleRule
+from st_graph_workbench.component.events import Event
+from st_graph_workbench.component.elements import (
+    delete_elements,
+    get_element,
+    update_element_data,
+    upsert_elements,
+)
+from st_graph_workbench.component.records import (
+    dataframe_to_records,
+    records_to_dataframe,
+)
+from st_graph_workbench.component.types import (
+    ConnectedDragConfig,
+    Element,
+    ElementId,
+    ElementIdInput,
+    Elements,
+    GraphCommand,
+    GraphEvent,
+    Layout,
+    ProgressiveLoadConfig,
+    Record,
+    ToolbarConfig,
+)
+from st_graph_workbench.component.commands import (
+    GraphCommandValidationError,
+    add_elements_command,
+    apply_graph_command,
+    apply_graph_commands,
+    clear_graph_command,
+    delete_elements_command,
+    set_elements_command,
+    update_data_command,
+    upsert_elements_command,
+    validate_graph_commands,
+    viewport_command,
+)
+from st_graph_workbench.component.validation import (
+    ElementValidationError,
+    validate_elements,
+)
+from st_graph_workbench.component.expansion import (
+    ExpansionConfig,
+    ExpansionController,
+    ExpansionOperation,
+    ExpansionProvider,
+    ExpansionRequest,
+    ExpansionResponse,
+)
+from st_graph_workbench.component.expansion_provider import InMemoryExpansionProvider
+
+__all__ = [
+    "ConnectedDragConfig",
+    "ExpansionConfig",
+    "ExpansionController",
+    "ExpansionOperation",
+    "ExpansionProvider",
+    "ExpansionRequest",
+    "ExpansionResponse",
+    "InMemoryExpansionProvider",
+    "graph_workbench",
+    "NodeStyle",
+    "EdgeStyle",
+    "StyleRule",
+    "Event",
+    "AnalysisAction",
+    "CrudAction",
+    "dataframe_to_records",
+    "delete_elements",
+    "Element",
+    "ElementId",
+    "ElementIdInput",
+    "ElementValidationError",
+    "Elements",
+    "EditAction",
+    "ElementsSync",
+    "GraphCommand",
+    "GraphCommandValidationError",
+    "GraphEvent",
+    "Layout",
+    "NodeAction",
+    "PerformanceProfile",
+    "ProgressiveLoadConfig",
+    "ToolbarConfig",
+    "SelectionMode",
+    "add_elements_command",
+    "apply_graph_command",
+    "apply_graph_commands",
+    "clear_graph_command",
+    "delete_elements_command",
+    "get_element",
+    "set_elements_command",
+    "update_data_command",
+    "update_element_data",
+    "upsert_elements",
+    "upsert_elements_command",
+    "records_to_dataframe",
+    "Record",
+    "validate_elements",
+    "validate_graph_commands",
+    "ViewportAction",
+    "viewport_command",
+]

st_graph_workbench/component/__init__.py

@@ -0,0 +1 @@
+"""Internal modules for the st-graph-workbench Streamlit component."""

st_graph_workbench/component/_expansion_contract.py

@@ -0,0 +1,106 @@
+"""Shared record and filter validation for expansion controllers and providers."""
+
+from copy import deepcopy
+from datetime import datetime, timezone
+import json
+import math
+from typing import Any
+
+from ._ids import normalize_id
+from .types import Elements
+from .validation import validate_elements
+
+
+def positive_limit(value: int, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer.")
+    return value
+
+
+def normalize_elements(elements: Elements, *, strict: bool = True) -> Elements:
+    validate_elements(elements, strict=strict)
+    elements = deepcopy(elements)
+    for group in ("nodes", "edges"):
+        elements.setdefault(group, [])
+        for record in elements[group]:
+            data = record["data"]
+            fields = (
+                ("id", "source", "target") if group == "edges" else ("id", "parent")
+            )
+            for name in fields:
+                if name == "parent" and data.get(name) in (None, ""):
+                    data.pop(name, None)
+                elif name in data:
+                    data[name] = normalize_id(data[name], option_name=name)
+    try:
+        json.dumps(elements, allow_nan=False)
+    except (TypeError, ValueError) as error:
+        raise ValueError(
+            "Expansion records must contain JSON-compatible finite values."
+        ) from error
+    for node in elements["nodes"]:
+        if "position" not in node:
+            continue
+        position = node["position"]
+        if not isinstance(position, dict) or any(
+            isinstance(position.get(axis), bool)
+            or not isinstance(position.get(axis), (int, float))
+            or not math.isfinite(float(position[axis]))
+            for axis in ("x", "y")
+        ):
+            raise ValueError(
+                f"Node {node['data']['id']} position requires finite numeric x and y."
+            )
+    return elements
+
+
+def parse_instant(value: Any) -> datetime:
+    instant = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    return instant.replace(tzinfo=timezone.utc) if instant.tzinfo is None else instant
+
+
+def normalize_query(value: dict[str, Any] | None) -> dict[str, Any]:
+    if value is not None and not isinstance(value, dict):
+        raise ValueError("Expansion filters must be a dictionary.")
+    result = deepcopy(value or {})
+    unknown = set(result) - {
+        "direction",
+        "relationships",
+        "attributes",
+        "time_field",
+        "time_from",
+        "time_to",
+    }
+    if unknown:
+        raise ValueError(f"Unknown expansion filters: {sorted(unknown)}")
+    result.setdefault("direction", "both")
+    if result["direction"] not in ("both", "incoming", "outgoing"):
+        raise ValueError("direction must be both, incoming or outgoing.")
+    relationships = result.get("relationships", [])
+    if not isinstance(relationships, list) or any(
+        not isinstance(x, str) for x in relationships
+    ):
+        raise ValueError("relationships must be a list of strings.")
+    result["relationships"] = sorted(set(relationships))
+    result.setdefault("attributes", {})
+    result.setdefault("time_field", "observed_at")
+    if not isinstance(result["attributes"], dict):
+        raise ValueError("attributes must be a dictionary of exact-match properties.")
+    if not isinstance(result["time_field"], str) or not result["time_field"].strip():
+        raise ValueError("time_field must be a nonempty property name.")
+    bounds = {}
+    for name in ("time_from", "time_to"):
+        if result.get(name) in (None, ""):
+            continue
+        try:
+            if not isinstance(result[name], str):
+                raise ValueError
+            bounds[name] = parse_instant(result[name])
+        except (TypeError, ValueError) as error:
+            raise ValueError(
+                f"{name} must be an ISO-8601 date or timestamp."
+            ) from error
+    if len(bounds) == 2 and bounds["time_from"] > bounds["time_to"]:
+        raise ValueError("time_from must not be later than time_to.")
+    json.dumps(result, allow_nan=False)
+    return result

st_graph_workbench/component/_ids.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+
+from st_graph_workbench.component.types import ElementIdInput
+
+
+def normalize_id(value: object, *, option_name: str) -> str:
+    """Normalize one supported scalar identifier to a string."""
+    if value is None or value == "":
+        raise TypeError(f"`{option_name}` values cannot be empty.")
+    if isinstance(value, str | bool | int):
+        return str(value)
+    if isinstance(value, float) and math.isfinite(value):
+        return str(value)
+    raise TypeError(
+        f"`{option_name}` values must be non-empty string, finite number, "
+        f"or boolean IDs, not `{type(value).__name__}`."
+    )
+
+
+def normalize_id_list(values: ElementIdInput, *, option_name: str) -> list[str]:
+    """Normalize one scalar ID or an iterable of IDs to string IDs."""
+    if values is None:
+        return []
+    if isinstance(values, str | bool | int | float):
+        return [normalize_id(values, option_name=option_name)]
+    if isinstance(values, Mapping):
+        raise TypeError(
+            f"`{option_name}` must be one scalar ID or an iterable of ID values, "
+            "not a dict."
+        )
+    if not isinstance(values, Iterable):
+        raise TypeError(
+            f"`{option_name}` must be one scalar ID or an iterable of ID values, "
+            f"not `{type(values).__name__}`."
+        )
+    return [normalize_id(value, option_name=option_name) for value in values]
+
+
+def normalize_id_set(values: ElementIdInput, *, option_name: str) -> set[str]:
+    """Normalize one scalar ID or an iterable of IDs to a set of string IDs."""
+    return set(normalize_id_list(values, option_name=option_name))

st_graph_workbench/component/_typing.py

@@ -0,0 +1,6 @@
+from typing import Any, Set, get_args
+
+
+def literal_choices(literal_alias: Any) -> Set[str]:
+    """Return string values declared by a `typing.Literal` alias."""
+    return {str(choice) for choice in get_args(literal_alias)}

st_graph_workbench/component/_warnings.py

@@ -0,0 +1,8 @@
+import warnings
+
+
+class GraphWorkbenchDeprecationWarning(DeprecationWarning):
+    """Warning category for deprecated st-graph-workbench compatibility APIs."""
+
+
+warnings.simplefilter("once", GraphWorkbenchDeprecationWarning)