garphield 0.1.0__py3-none-any.whl

garphield/__init__.py

@@ -0,0 +1,85 @@
+"""Validated Python primitives for Garphield project files."""
+
+from ._canonical import CanonicalizationError, canonicalize_jcs_v1
+from ._bindings import AlgorithmSpec, BindingOptions, algorithm
+from ._html import save_html
+from ._identity import AttributeNameCodecV1, EdgeIdentityCodecV1, IdentityCodecV1
+from ._project import (
+    DuplicatePropertyError,
+    Project,
+    ProjectValidationError,
+    canonicalize_project_v1,
+    canonicalize_semantic_graph_v1,
+    load,
+)
+from ._transport import (
+    AnyWidgetTransportEndpoint,
+    TRANSPORT_RUNTIME_CONFIG_V1,
+    PreparedBudgetedJson,
+    TransportError,
+    TransportRuntimeConfigV1,
+    prepare_budgeted_json,
+    receive_budgeted_json,
+)
+from ._transforms import Transformation, TransformSpec, transform
+from ._view import GraphView
+from ._widget import (
+    OwnershipError,
+    ProjectWidget,
+    WidgetEnvironmentUnsupportedError,
+    WidgetNotDisplayedError,
+    WidgetTransportError,
+    show,
+    show_snowpark,
+)
+
+
+def __getattr__(name: str) -> object:
+    if name == "Tables":
+        from ._pandas import Tables
+
+        return Tables
+    if name == "IdentityCollisionError":
+        from ._networkx import IdentityCollisionError
+
+        return IdentityCollisionError
+    raise AttributeError(name)
+
+
+__all__ = [
+    "AttributeNameCodecV1",
+    "AlgorithmSpec",
+    "AnyWidgetTransportEndpoint",
+    "CanonicalizationError",
+    "BindingOptions",
+    "DuplicatePropertyError",
+    "EdgeIdentityCodecV1",
+    "IdentityCodecV1",
+    "GraphView",
+    "OwnershipError",
+    "Project",
+    "ProjectWidget",
+    "ProjectValidationError",
+    "PreparedBudgetedJson",
+    "TransportError",
+    "TransportRuntimeConfigV1",
+    "TransformSpec",
+    "Transformation",
+    "TRANSPORT_RUNTIME_CONFIG_V1",
+    "WidgetEnvironmentUnsupportedError",
+    "WidgetNotDisplayedError",
+    "WidgetTransportError",
+    "IdentityCollisionError",
+    "Tables",
+    "canonicalize_jcs_v1",
+    "algorithm",
+    "transform",
+    "canonicalize_project_v1",
+    "canonicalize_semantic_graph_v1",
+    "load",
+    "prepare_budgeted_json",
+    "receive_budgeted_json",
+    "show",
+    "show_snowpark",
+    "save_html",
+]

garphield/_bindings.py

@@ -0,0 +1,322 @@
+"""NetworkX-shaped visual binding normalization for notebook views."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Iterable, Mapping, Sequence, Set
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from ._project import Project
+from ._scalars import normalize_scalar
+
+JsonScalar = str | int | float | bool | None
+VariableData = (
+    str
+    | Mapping[object, object]
+    | Iterable[object]
+    | Set[object]
+    | Callable[..., object]
+)
+
+
+@dataclass(frozen=True)
+class AlgorithmSpec:
+    """An explicit browser-side graph algorithm used as a visual source."""
+
+    name: str
+    params: Mapping[str, JsonScalar] = field(default_factory=dict)
+
+
+def algorithm(name: str, /, **params: JsonScalar) -> AlgorithmSpec:
+    """Describe a browser-side algorithm without confusing it with a field."""
+
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("algorithm name must be a non-empty string")
+    normalized = {
+        key: normalize_scalar(value, f"/algorithm/{name}/{key}")
+        for key, value in params.items()
+    }
+    return AlgorithmSpec(name=name, params=normalized)
+
+
+@dataclass(frozen=True)
+class BindingOptions:
+    node_color: VariableData | AlgorithmSpec | None = None
+    node_size: VariableData | AlgorithmSpec | None = None
+    node_label: VariableData | None = None
+    edge_color: VariableData | AlgorithmSpec | None = None
+    edge_width: VariableData | AlgorithmSpec | None = None
+    pos: Mapping[object, Sequence[float]] | None = None
+    layout: Literal["force", "levels", "geo", "quality"] | None = None
+
+
+_CHANNELS = (
+    ("node_color", "color", "node"),
+    ("node_size", "size", "node"),
+    ("node_label", "nodeLabel", "node"),
+    ("edge_color", "edgeColor", "edge"),
+    ("edge_width", "edgeWidth", "edge"),
+)
+_NUMERIC_CHANNELS = {"size", "edgeWidth"}
+_ALGORITHM_RESULTS = {
+    "degree": "num",
+    "betweenness": "num",
+    "closeness": "num",
+    "pagerank": "num",
+    "louvain": "cat",
+    "k_core": "num",
+}
+
+
+def _call_value(function: Callable[..., object], args: tuple[object, ...]) -> object:
+    try:
+        signature = inspect.signature(function)
+    except (TypeError, ValueError):
+        return function(args[0])
+    positional = [
+        parameter
+        for parameter in signature.parameters.values()
+        if parameter.kind
+        in (parameter.POSITIONAL_ONLY, parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if any(
+        parameter.kind == parameter.VAR_POSITIONAL
+        for parameter in signature.parameters.values()
+    ):
+        return function(*args)
+    return function(*args[: len(positional)])
+
+
+def _partition_values(
+    value: object,
+    items: list[object],
+) -> dict[object, int] | None:
+    if not isinstance(value, (list, tuple)) or not value:
+        return None
+    if not all(isinstance(group, (set, frozenset)) for group in value):
+        return None
+    known = set(items)
+    assigned: dict[object, int] = {}
+    for index, group in enumerate(value):
+        for item in group:
+            if item not in known:
+                raise ValueError(f"partition contains unknown node {item!r}")
+            if item in assigned:
+                raise ValueError(f"partition contains node {item!r} twice")
+            assigned[item] = index
+    return assigned
+
+
+def _mapping_values(value: object, items: list[object]) -> list[object] | None:
+    if isinstance(value, Mapping):
+        return [value[item] for item in items]
+    if isinstance(value, (str, bytes, list, tuple, set, frozenset)):
+        return None
+    if not hasattr(value, "__getitem__"):
+        return None
+    try:
+        return [value[item] for item in items]  # type: ignore[index]
+    except (KeyError, TypeError, IndexError):
+        return None
+
+
+def _node_values(graph: Any, value: VariableData) -> tuple[list[object], str]:
+    nodes = list(graph.nodes)
+    partition = _partition_values(value, nodes)
+    if partition is not None:
+        missing = [node for node in nodes if node not in partition]
+        if missing:
+            raise ValueError(f"partition omits node {missing[0]!r}")
+        return [partition[node] for node in nodes], "cat"
+    if isinstance(value, (set, frozenset)):
+        unknown = set(value).difference(nodes)
+        if unknown:
+            raise ValueError(f"set contains unknown node {next(iter(unknown))!r}")
+        return [node in value for node in nodes], "set"
+    mapped = _mapping_values(value, nodes)
+    if mapped is not None:
+        return mapped, _infer_result(mapped)
+    if callable(value):
+        values = [_call_value(value, (node, dict(graph.nodes[node]))) for node in nodes]
+        return values, _infer_result(values)
+    values = list(value)
+    if len(values) != len(nodes):
+        raise ValueError(
+            f"node binding has {len(values)} values for {len(nodes)} nodes"
+        )
+    return values, _infer_result(values)
+
+
+def _edge_rows(
+    graph: Any,
+) -> list[tuple[object, object, object | None, dict[str, object]]]:
+    if graph.is_multigraph():
+        return [
+            (source, target, key, dict(attrs))
+            for source, target, key, attrs in graph.edges(keys=True, data=True)
+        ]
+    return [
+        (source, target, None, dict(attrs))
+        for source, target, attrs in graph.edges(data=True)
+    ]
+
+
+def _edge_values(graph: Any, value: VariableData) -> tuple[list[object], str]:
+    rows = _edge_rows(graph)
+    if callable(value):
+        values = [
+            _call_value(value, (source, target, attrs))
+            for source, target, _key, attrs in rows
+        ]
+        return values, _infer_result(values)
+    if isinstance(value, Mapping):
+        values = []
+        for source, target, key, _attrs in rows:
+            candidates = (
+                ((source, target, key), (target, source, key))
+                if key is not None
+                else ((source, target), (target, source))
+            )
+            found = next(
+                (candidate for candidate in candidates if candidate in value), None
+            )
+            if found is None:
+                raise ValueError(f"edge binding has no value for {(source, target)!r}")
+            values.append(value[found])
+        return values, _infer_result(values)
+    values = list(value)
+    if len(values) != len(rows):
+        raise ValueError(f"edge binding has {len(values)} values for {len(rows)} edges")
+    return values, _infer_result(values)
+
+
+def _infer_result(values: Sequence[object]) -> str:
+    non_null = [value for value in values if value is not None]
+    if non_null and all(
+        isinstance(value, (int, float)) and not isinstance(value, bool)
+        for value in non_null
+    ):
+        return "num"
+    return "cat"
+
+
+def _unique_attribute(graph: Any, target: str, channel: str) -> str:
+    base = f"__garphield_{channel}"
+    name = base
+    suffix = 1
+    if target == "node":
+        occupied = {key for _node, attrs in graph.nodes(data=True) for key in attrs}
+    else:
+        occupied = {
+            key for *_identity, attrs in graph.edges(data=True) for key in attrs
+        }
+    while name in occupied:
+        name = f"{base}_{suffix}"
+        suffix += 1
+    return name
+
+
+def _internal_attribute(project: Project, target: str, logical: str) -> str:
+    config = project.to_dict()["config"]
+    manifest = config.get("interop", {})
+    maps = manifest.get("attributeNames", {})
+    table = maps.get("nodes" if target == "node" else "edges", {})
+    for internal, decoded in table.items():
+        if decoded == logical:
+            return internal
+    return logical
+
+
+def project_from_graph(graph: Any, options: BindingOptions) -> Project:
+    """Create a Project from a copied graph and declarative visual bindings."""
+
+    working = graph.copy()
+    pending: list[tuple[str, str, str, object]] = []
+    for option_name, channel, target in _CHANNELS:
+        value = getattr(options, option_name)
+        if value is None:
+            continue
+        if isinstance(value, AlgorithmSpec):
+            if target == "edge":
+                raise ValueError("browser-side edge algorithms are not supported")
+            result_type = _ALGORITHM_RESULTS.get(value.name, "cat")
+            pending.append((channel, target, result_type, value))
+            continue
+        if isinstance(value, str):
+            pending.append((channel, target, "field", value))
+            continue
+        logical = _unique_attribute(working, target, channel)
+        values, inferred = (
+            _node_values(working, value)
+            if target == "node"
+            else _edge_values(working, value)
+        )
+        if target == "node":
+            for node, child in zip(working.nodes, values, strict=True):
+                working.nodes[node][logical] = child
+        else:
+            rows = _edge_rows(working)
+            for (source, target_node, key, _attrs), child in zip(
+                rows, values, strict=True
+            ):
+                if key is None:
+                    working.edges[source, target_node][logical] = child
+                else:
+                    working.edges[source, target_node, key][logical] = child
+        result_type = "num" if channel in _NUMERIC_CHANNELS else inferred
+        pending.append((channel, target, result_type, logical))
+
+    if options.pos is not None:
+        for node in working.nodes:
+            if node not in options.pos:
+                raise ValueError(f"pos omits node {node!r}")
+            position = options.pos[node]
+            if len(position) < 2:
+                raise ValueError(f"pos for node {node!r} must contain x and y")
+            working.nodes[node]["x"] = position[0]
+            working.nodes[node]["y"] = position[1]
+
+    project = Project.from_networkx(working)
+    document = project.to_dict()
+    bindings: list[dict[str, object]] = []
+    for channel, target, result_type, source_value in pending:
+        if isinstance(source_value, AlgorithmSpec):
+            source: dict[str, object] = {
+                "kind": "algorithm",
+                "id": source_value.name,
+            }
+            if source_value.params:
+                source["params"] = dict(source_value.params)
+        else:
+            internal = _internal_attribute(project, target, str(source_value))
+            source = {
+                "kind": "field",
+                "id": f"{'e' if target == 'edge' else ''}field:{internal}",
+                **({"target": "edge"} if target == "edge" else {}),
+            }
+            if result_type == "field":
+                rows = document["datasets"][0]["graph"][
+                    "nodes" if target == "node" else "edges"
+                ]
+                values = [row.get(internal) for row in rows]
+                result_type = (
+                    "num" if channel in _NUMERIC_CHANNELS else _infer_result(values)
+                )
+        bindings.append(
+            {"channel": channel, "source": source, "resultType": result_type}
+        )
+    if bindings:
+        document["config"]["bindings"] = bindings
+    if options.layout is not None:
+        document["config"]["layout"] = options.layout
+    return Project.from_dict(document)
+
+
+__all__ = [
+    "AlgorithmSpec",
+    "BindingOptions",
+    "VariableData",
+    "algorithm",
+    "project_from_graph",
+]

garphield/_canonical.py

@@ -0,0 +1,88 @@
+"""The one RFC 8785/JCS canonical-byte boundary used by the package."""
+
+from __future__ import annotations
+
+import math
+
+import rfc8785
+
+
+class CanonicalizationError(ValueError):
+    """A JSON value cannot be represented by the v1 canonicalizer."""
+
+    def __init__(self, message: str, path: str = "/") -> None:
+        self.path = path
+        super().__init__(f"JSON Pointer {path}: {message}")
+
+
+def _pointer(path: str, component: object) -> str:
+    escaped = str(component).replace("~", "~0").replace("/", "~1")
+    return f"/{escaped}" if path == "/" else f"{path}/{escaped}"
+
+
+def _validate_json_value(value: object, path: str = "/", seen: set[int] | None = None) -> None:
+    """Validate the plain I-JSON tree accepted by the pinned JCS library."""
+
+    if seen is None:
+        seen = set()
+    if value is None or isinstance(value, bool):
+        return
+    if isinstance(value, str):
+        for index, character in enumerate(value):
+            code = ord(character)
+            if 0xD800 <= code <= 0xDFFF:
+                raise CanonicalizationError(
+                    "lone surrogate is not valid UTF-8", _pointer(path, index)
+                )
+        return
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        if isinstance(value, int) and abs(value) > 9007199254740991:
+            raise CanonicalizationError(
+                "integer exceeds the safe JSON number domain", path
+            )
+        if isinstance(value, float) and not math.isfinite(value):
+            raise CanonicalizationError("non-finite number is not valid JCS", path)
+        return
+    if isinstance(value, dict):
+        identity = id(value)
+        if identity in seen:
+            raise CanonicalizationError("cyclic value is not valid JSON", path)
+        seen.add(identity)
+        try:
+            for key, child in value.items():
+                if not isinstance(key, str):
+                    raise CanonicalizationError("object keys must be strings", path)
+                _validate_json_value(child, _pointer(path, key), seen)
+        finally:
+            seen.remove(identity)
+        return
+    if isinstance(value, list):
+        identity = id(value)
+        if identity in seen:
+            raise CanonicalizationError("cyclic value is not valid JSON", path)
+        seen.add(identity)
+        try:
+            for index, child in enumerate(value):
+                _validate_json_value(child, _pointer(path, index), seen)
+        finally:
+            seen.remove(identity)
+        return
+    raise CanonicalizationError(
+        f"unsupported value type {type(value).__name__}", path
+    )
+
+
+def validate_json_value(value: object) -> None:
+    """Validate a plain JSON value before schema or canonical processing."""
+
+    _validate_json_value(value)
+
+
+def canonicalize_jcs_v1(value: object) -> bytes:
+    """Return RFC 8785 canonical UTF-8 bytes using the pinned implementation."""
+
+    _validate_json_value(value)
+    try:
+        return rfc8785.dumps(value)
+    except rfc8785.CanonicalizationError as error:
+        raise CanonicalizationError(str(error)) from error

garphield/_chrome.py

@@ -0,0 +1,57 @@
+"""Shared language-level validation for lightweight embed chrome."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from urllib.parse import ParseResult, parse_qsl, urlencode, urlparse, urlunparse
+
+CHROME_SLOTS = ("minimap", "toolbar")
+
+
+def normalize_chrome(chrome: Sequence[str] | None) -> list[str] | None:
+    """Return canonical chrome order, preserving None as renderer defaults."""
+
+    if chrome is None:
+        return None
+    values = list(chrome)
+    unknown = [slot for slot in values if slot not in CHROME_SLOTS]
+    if unknown:
+        raise ValueError(
+            "unsupported chrome slot(s): "
+            + ", ".join(repr(slot) for slot in dict.fromkeys(unknown))
+        )
+    return [slot for slot in CHROME_SLOTS if slot in values]
+
+
+def validate_embed_url(value: str | None) -> str:
+    """Validate and return an absolute HTTP(S) embed URL."""
+
+    url = value or "https://garphield.com/embed"
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError("app_url must be an absolute HTTP(S) URL")
+    if not parsed.path.rstrip("/").endswith("/embed"):
+        raise ValueError("app_url must point to the Garphield /embed route")
+    return url
+
+
+def build_embed_url(value: str | None, chrome: Sequence[str] | None = None) -> str:
+    """Apply the optional chrome query without disturbing other URL options."""
+
+    normalized = normalize_chrome(chrome)
+    validated = validate_embed_url(value)
+    if normalized is None:
+        return validated
+    parsed = urlparse(validated)
+    query = [(key, value) for key, value in parse_qsl(parsed.query, keep_blank_values=True) if key != "chrome"]
+    query.append(("chrome", ",".join(normalized)))
+    return urlunparse(
+        ParseResult(
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            parsed.params,
+            urlencode(query, safe=","),
+            parsed.fragment,
+        )
+    )

garphield/_codegen.py

@@ -0,0 +1,98 @@
+"""Deterministic exact Python replay for validated Garphield Projects."""
+
+from __future__ import annotations
+
+import json
+import keyword
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._project import Project
+
+
+def _validate_variable(variable: str) -> None:
+    if not variable.isidentifier() or keyword.iskeyword(variable):
+        raise ValueError("variable must be a valid non-keyword Python identifier")
+
+
+def exact_code(project: "Project", *, variable: str = "project", display: bool = True) -> str:
+    _validate_variable(variable)
+
+    payload = json.dumps(
+        project.to_dict(),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    )
+
+    lines = [
+        "import json",
+        "from garphield import Project",
+        "",
+        f"{variable} = Project.from_dict(json.loads({payload!r}))",
+    ]
+    if display:
+        lines.append(f"view = {variable}.widget()")
+    return "\n".join(lines) + "\n"
+
+
+def idiomatic_code(
+    project: "Project", *, variable: str = "project", display: bool = True
+) -> str:
+    """Emit readable transform calls over a lossless exact base project."""
+
+    from ._project import Project
+    from ._transforms import transform_catalog
+
+    _validate_variable(variable)
+    transformations = project.transformations
+    if any(entry.name not in transform_catalog() for entry in transformations):
+        return exact_code(project, variable=variable, display=display)
+    if not transformations:
+        return exact_code(project, variable=variable, display=display)
+
+    removed_ids = {entry.id for entry in transformations}
+    document = project.to_dict()
+    config = document.get("config")
+    if isinstance(config, dict):
+        stack = config.get("filterStack")
+        if isinstance(stack, list):
+            config["filterStack"] = [
+                entry
+                for entry in stack
+                if not (
+                    isinstance(entry, Mapping) and entry.get("id") in removed_ids
+                )
+            ]
+        current = config.get("current")
+        state = current.get("state") if isinstance(current, dict) else None
+        current_stack = state.get("filterStack") if isinstance(state, dict) else None
+        if isinstance(current_stack, list):
+            state["filterStack"] = [
+                entry
+                for entry in current_stack
+                if not (
+                    isinstance(entry, Mapping) and entry.get("id") in removed_ids
+                )
+            ]
+
+    base = exact_code(Project.from_dict(document), variable=variable, display=False)
+    lines = ["import garphield as gf", base.rstrip(), "", "# Garphield transformations"]
+    for entry in transformations:
+        arguments = ", ".join(
+            f"{name}={value!r}" for name, value in sorted(entry.params.items())
+        )
+        spec = (
+            f"gf.transform({json.dumps(entry.name)}"
+            f'{", " if arguments else ""}{arguments})'
+        )
+        lines.append(
+            f"{variable} = {variable}.with_transform("
+            f"{spec}, mode={json.dumps(entry.mode)}, id={json.dumps(entry.id)}, "
+            f"enabled={entry.enabled!r})"
+        )
+    if display:
+        lines.append(f"view = {variable}.widget()")
+    return "\n".join(lines) + "\n"

garphield/_colab.py

@@ -0,0 +1,34 @@
+"""Small adapter for Colab's documented ``proxyPort`` callback."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+
+def proxy_port_adapter() -> Callable[[int], str]:
+    """Return a callable backed by ``google.colab.kernel.proxyPort``.
+
+    The import is intentionally lazy so importing Garphield remains safe in a
+    regular Python process. Colab owns the proxy URL and may change its host or
+    token between calls; the adapter therefore does not cache a result.
+    """
+
+    from google.colab import kernel  # type: ignore[import-not-found]
+
+    callback = kernel.proxyPort
+
+    def proxy_port(port: int) -> str:
+        if isinstance(port, bool) or not isinstance(port, int) or port <= 0 or port > 65535:
+            raise ValueError("Colab proxy port must be an integer from 1 through 65535")
+        value = callback(port)
+        if not isinstance(value, str):
+            raise TypeError("google.colab.kernel.proxyPort must return a URL string")
+        return value
+
+    return proxy_port
+
+
+def proxy_port(port: int) -> str:
+    """Resolve one port through the live Colab kernel callback."""
+
+    return proxy_port_adapter()(port)