synkit 1.6.5__py3-none-win_amd64.whl

synkit/Vis/visual_model.py

@@ -0,0 +1,520 @@
+from __future__ import annotations
+
+"""Representation-aware visual adapters for SynKit graphs.
+
+This module is intentionally lightweight: it detects the graph representation
+and converts raw NetworkX attributes into stable labels/colors that drawing
+backends can consume.  The adapters never mutate the input graph.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Hashable, Iterable, Literal, Mapping
+
+import networkx as nx
+
+VisualKind = Literal[
+    "molecule",
+    "legacy_its",
+    "tuple_its",
+    "compact_mtg",
+    "mechanism_dag",
+    "unknown",
+]
+
+
+@dataclass(frozen=True)
+class VisualNode:
+    """Drawing-ready node information."""
+
+    node_id: Hashable
+    label: str
+    element: str | None = None
+    atom_map: int | None = None
+    badges: tuple[str, ...] = ()
+    changed: bool = False
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VisualEdge:
+    """Drawing-ready edge information."""
+
+    source: Hashable
+    target: Hashable
+    label: str = ""
+    state: str = "unchanged"
+    color: str = "#2f3437"
+    width: float = 2.0
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VisualGraph:
+    """A compact, immutable view of graph content for renderers."""
+
+    kind: VisualKind
+    nodes: tuple[VisualNode, ...]
+    edges: tuple[VisualEdge, ...]
+    title: str = ""
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+BOND_SYMBOLS = {
+    None: "∅",
+    0: "∅",
+    0.0: "∅",
+    1: "—",
+    1.0: "—",
+    1.5: ":",
+    2: "=",
+    2.0: "=",
+    3: "≡",
+    3.0: "≡",
+}
+
+EDGE_COLORS = {
+    "unchanged": "#6b7280",
+    "formed": "#15803d",
+    "broken": "#b91c1c",
+    "order_changed": "#ca8a04",
+    "transient": "#7c3aed",
+    "unknown": "#2f3437",
+}
+
+NODE_TIMELINE_ATTRS = (
+    "aromatic",
+    "hcount",
+    "charge",
+    "radical",
+    "lone_pairs",
+    "present",
+)
+EDGE_TIMELINE_ATTRS = ("order", "kekule_order", "sigma_order", "pi_order")
+ELECTRON_NODE_ATTRS = ("charge", "hcount", "lone_pairs", "radical")
+
+
+def detect_visual_kind(graph: nx.Graph) -> VisualKind:
+    """Return the visualization representation kind for ``graph``.
+
+    :param graph: NetworkX graph to inspect.
+    :type graph: nx.Graph
+    :return: Detected graph kind.
+    :rtype: VisualKind
+    """
+
+    if not isinstance(graph, nx.Graph):
+        return "unknown"
+
+    if _looks_like_mechanism_dag(graph):
+        return "mechanism_dag"
+    if _looks_like_compact_mtg(graph):
+        return "compact_mtg"
+    if _looks_like_tuple_its(graph):
+        return "tuple_its"
+    if _looks_like_legacy_its(graph):
+        return "legacy_its"
+    if _looks_like_molecule(graph):
+        return "molecule"
+    return "unknown"
+
+
+def to_visual_graph(
+    graph: nx.Graph,
+    *,
+    kind: VisualKind | None = None,
+    mode: Literal["compact", "electron", "sigma_pi", "timeline"] = "compact",
+    show_atom_map: bool = True,
+    title: str = "",
+) -> VisualGraph:
+    """Adapt a SynKit graph to drawing-ready labels.
+
+    :param graph: NetworkX graph to adapt.
+    :type graph: nx.Graph
+    :param kind: Optional explicit representation kind.
+    :type kind: Optional[VisualKind]
+    :param mode: Label density. ``sigma_pi`` and ``timeline`` are mostly useful
+        for tuple ITS and compact MTG.
+    :type mode: str
+    :param show_atom_map: Include atom-map numbers in node labels when present.
+    :type show_atom_map: bool
+    :param title: Optional title carried to renderer metadata.
+    :type title: str
+    :return: Immutable visual graph model.
+    :rtype: VisualGraph
+    """
+
+    detected = kind or detect_visual_kind(graph)
+    nodes = tuple(
+        _adapt_node(node_id, attrs, detected, mode=mode, show_atom_map=show_atom_map)
+        for node_id, attrs in graph.nodes(data=True)
+    )
+    edges = tuple(
+        _adapt_edge(u, v, attrs, detected, mode=mode)
+        for u, v, attrs in graph.edges(data=True)
+    )
+    return VisualGraph(
+        kind=detected,
+        nodes=nodes,
+        edges=edges,
+        title=title,
+        metadata={
+            "mode": mode,
+            "node_count": graph.number_of_nodes(),
+            "edge_count": graph.number_of_edges(),
+        },
+    )
+
+
+def summarize_visual_graph(visual: VisualGraph) -> Dict[str, Any]:
+    """Return a notebook-friendly summary of a visual graph."""
+
+    return {
+        "kind": visual.kind,
+        "title": visual.title,
+        "metadata": dict(visual.metadata),
+        "nodes": [
+            {
+                "id": node.node_id,
+                "label": node.label,
+                "badges": list(node.badges),
+                "changed": node.changed,
+            }
+            for node in visual.nodes
+        ],
+        "edges": [
+            {
+                "source": edge.source,
+                "target": edge.target,
+                "label": edge.label,
+                "state": edge.state,
+                "color": edge.color,
+            }
+            for edge in visual.edges
+        ],
+    }
+
+
+def _looks_like_molecule(graph: nx.Graph) -> bool:
+    return bool(graph.nodes) and all(
+        "element" in attrs and not _is_pair(attrs.get("element"))
+        for _, attrs in graph.nodes(data=True)
+    )
+
+
+def _looks_like_legacy_its(graph: nx.Graph) -> bool:
+    if not graph.edges:
+        return False
+    has_pair_order = any(
+        _is_pair(attrs.get("order")) for _, _, attrs in graph.edges(data=True)
+    )
+    has_tuple_electron_edges = any(
+        key in attrs
+        for _, _, attrs in graph.edges(data=True)
+        for key in ("sigma_order", "pi_order", "kekule_order")
+    )
+    return has_pair_order and not has_tuple_electron_edges
+
+
+def _looks_like_tuple_its(graph: nx.Graph) -> bool:
+    if not graph.nodes and not graph.edges:
+        return False
+    node_pair = any(
+        _is_pair(attrs.get(key))
+        for _, attrs in graph.nodes(data=True)
+        for key in ("element", "hcount", "charge", "lone_pairs", "radical", "present")
+    )
+    edge_pair = any(
+        _is_pair(attrs.get(key))
+        for _, _, attrs in graph.edges(data=True)
+        for key in ("sigma_order", "pi_order", "kekule_order")
+    )
+    return node_pair or edge_pair
+
+
+def _looks_like_compact_mtg(graph: nx.Graph) -> bool:
+    graph_steps = graph.graph.get("steps")
+    if isinstance(graph_steps, int) and graph_steps >= 2:
+        return True
+    has_steps_attr = any(
+        "steps" in attrs for _, attrs in graph.nodes(data=True)
+    ) or any("steps" in attrs for _, _, attrs in graph.edges(data=True))
+    if not has_steps_attr:
+        return False
+    has_timeline = any(
+        _is_timeline(attrs.get(key))
+        for _, attrs in graph.nodes(data=True)
+        for key in NODE_TIMELINE_ATTRS
+    ) or any(
+        _is_timeline(attrs.get(key))
+        for _, _, attrs in graph.edges(data=True)
+        for key in EDGE_TIMELINE_ATTRS
+    )
+    return has_timeline
+
+
+def _looks_like_mechanism_dag(graph: nx.Graph) -> bool:
+    if not graph.is_directed():
+        return False
+    graph_kind = str(graph.graph.get("kind", "")).lower()
+    if graph_kind in {"mechanism_dag", "mechanism", "reaction_dag"}:
+        return True
+    return any(
+        attrs.get("kind") in {"reaction", "step", "species"}
+        for _, attrs in graph.nodes(data=True)
+    )
+
+
+def _adapt_node(
+    node_id: Hashable,
+    attrs: Mapping[str, Any],
+    kind: VisualKind,
+    *,
+    mode: str,
+    show_atom_map: bool,
+) -> VisualNode:
+    element = _first_present(attrs.get("element"))
+    atom_map = _first_present(attrs.get("atom_map"))
+    label = str(element or node_id)
+    if show_atom_map and atom_map not in (None, 0):
+        label = f"{label}:{atom_map}"
+    elif show_atom_map and atom_map == 0:
+        label = f"{label}:{node_id}"
+
+    badges = _node_badges(attrs, kind, mode)
+    changed = bool(badges) or any(
+        _is_changed_pair(attrs.get(key)) for key in ELECTRON_NODE_ATTRS
+    )
+    return VisualNode(
+        node_id=node_id,
+        label=label,
+        element=str(element) if element is not None else None,
+        atom_map=int(atom_map) if isinstance(atom_map, int) else None,
+        badges=tuple(badges),
+        changed=changed,
+        raw=dict(attrs),
+    )
+
+
+def _adapt_edge(
+    u: Hashable,
+    v: Hashable,
+    attrs: Mapping[str, Any],
+    kind: VisualKind,
+    *,
+    mode: str,
+) -> VisualEdge:
+    if kind == "compact_mtg":
+        label = _mtg_edge_label(attrs, mode)
+        state = _timeline_edge_state(attrs)
+    elif kind == "tuple_its":
+        label = _tuple_its_edge_label(attrs, mode)
+        state = _pair_edge_state(_preferred_edge_pair(attrs))
+    elif kind == "legacy_its":
+        pair = attrs.get("order", (None, None))
+        label = _pair_label(pair)
+        state = _pair_edge_state(pair)
+    else:
+        order = attrs.get("order")
+        label = _bond_symbol(order)
+        state = "unchanged"
+
+    return VisualEdge(
+        source=u,
+        target=v,
+        label=label,
+        state=state,
+        color=EDGE_COLORS.get(state, EDGE_COLORS["unknown"]),
+        width=(
+            3.0 if state in {"formed", "broken", "order_changed", "transient"} else 2.0
+        ),
+        raw=dict(attrs),
+    )
+
+
+def _node_badges(attrs: Mapping[str, Any], kind: VisualKind, mode: str) -> list[str]:
+    badges: list[str] = []
+    if kind in {"tuple_its", "compact_mtg"}:
+        for key in ELECTRON_NODE_ATTRS:
+            value = attrs.get(key)
+            if kind == "compact_mtg" and _is_timeline(value):
+                if _timeline_changes(value) or mode in {"electron", "timeline"}:
+                    badges.append(f"{_short_node_key(key)}:{_format_timeline(value)}")
+            elif _is_pair(value):
+                if value[0] != value[1] or mode in {"electron", "timeline"}:
+                    badges.append(f"{_short_node_key(key)}:{_format_pair(value)}")
+            elif mode in {"electron", "timeline"} and value not in (None, 0, False):
+                badges.append(f"{_short_node_key(key)}:{value}")
+    elif kind == "molecule":
+        for key in ("charge", "radical", "lone_pairs"):
+            value = attrs.get(key)
+            if value not in (None, 0, False):
+                badges.append(f"{_short_node_key(key)}:{value}")
+    return badges
+
+
+def _tuple_its_edge_label(attrs: Mapping[str, Any], mode: str) -> str:
+    if mode == "sigma_pi":
+        sigma = attrs.get("sigma_order")
+        pi = attrs.get("pi_order")
+        return f"σ{_format_pair(sigma)} π{_format_pair(pi)}"
+    pair = attrs.get("kekule_order", attrs.get("order"))
+    return _pair_label(pair)
+
+
+def _mtg_edge_label(attrs: Mapping[str, Any], mode: str) -> str:
+    if mode == "sigma_pi":
+        parts = []
+        for key in ("sigma_order", "pi_order"):
+            value = attrs.get(key)
+            if _is_timeline(value) and (_timeline_changes(value) or mode == "timeline"):
+                parts.append(f"{_short_edge_key(key)}:{_format_timeline(value)}")
+        return " ".join(parts) or _format_timeline(
+            attrs.get("kekule_order", attrs.get("order"))
+        )
+    if mode == "timeline":
+        parts = []
+        for key in EDGE_TIMELINE_ATTRS:
+            value = attrs.get(key)
+            if _is_timeline(value):
+                parts.append(f"{_short_edge_key(key)}:{_format_timeline(value)}")
+        return " ".join(parts)
+    value = attrs.get("kekule_order", attrs.get("order"))
+    return _format_timeline(value) if _is_timeline(value) else _bond_symbol(value)
+
+
+def _preferred_edge_pair(attrs: Mapping[str, Any]) -> Any:
+    return attrs.get("kekule_order", attrs.get("order"))
+
+
+def _pair_edge_state(pair: Any) -> str:
+    if not _is_pair(pair):
+        return "unknown"
+    before, after = pair
+    before = _none_order(before)
+    after = _none_order(after)
+    if before == after:
+        return "unchanged"
+    if before == 0 and after > 0:
+        return "formed"
+    if before > 0 and after == 0:
+        return "broken"
+    return "order_changed"
+
+
+def _timeline_edge_state(attrs: Mapping[str, Any]) -> str:
+    timeline = attrs.get("kekule_order", attrs.get("order"))
+    if not _is_timeline(timeline):
+        return "unknown"
+    numeric = [_none_order(v) for v in timeline if _is_order_value(v)]
+    if not numeric or len(set(numeric)) == 1:
+        return "unchanged"
+    if numeric[0] == numeric[-1] and len(set(numeric)) > 1:
+        return "transient"
+    if numeric[0] == 0 and numeric[-1] > 0:
+        return "formed"
+    if numeric[0] > 0 and numeric[-1] == 0:
+        return "broken"
+    return "order_changed"
+
+
+def _pair_label(pair: Any) -> str:
+    if not _is_pair(pair):
+        return _bond_symbol(pair)
+    return f"{_bond_symbol(pair[0])}>{_bond_symbol(pair[1])}"
+
+
+def _format_pair(pair: Any) -> str:
+    if not _is_pair(pair):
+        return str(pair)
+    return f"{_format_value(pair[0])}>{_format_value(pair[1])}"
+
+
+def _format_timeline(value: Any) -> str:
+    if not _is_timeline(value):
+        return str(value)
+    return "-".join(_format_value(item) for item in value)
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        return "∅"
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def _bond_symbol(order: Any) -> str:
+    return BOND_SYMBOLS.get(order, _format_value(order))
+
+
+def _short_node_key(key: str) -> str:
+    return {
+        "charge": "q",
+        "hcount": "H",
+        "lone_pairs": "lp",
+        "radical": "rad",
+    }.get(key, key)
+
+
+def _short_edge_key(key: str) -> str:
+    return {
+        "order": "ord",
+        "kekule_order": "kek",
+        "sigma_order": "σ",
+        "pi_order": "π",
+    }.get(key, key)
+
+
+def _is_pair(value: Any) -> bool:
+    return (
+        isinstance(value, tuple)
+        and len(value) == 2
+        and not any(isinstance(item, (set, list, tuple, dict)) for item in value)
+    )
+
+
+def _is_timeline(value: Any) -> bool:
+    return (
+        isinstance(value, tuple)
+        and len(value) >= 3
+        and not any(isinstance(item, (set, list, tuple, dict)) for item in value)
+    )
+
+
+def _is_changed_pair(value: Any) -> bool:
+    return _is_pair(value) and value[0] != value[1]
+
+
+def _timeline_changes(value: Any) -> bool:
+    return _is_timeline(value) and len(set(value)) > 1
+
+
+def _is_order_value(value: Any) -> bool:
+    return value is None or isinstance(value, (int, float))
+
+
+def _none_order(value: Any) -> float:
+    return 0.0 if value is None else float(value)
+
+
+def _first_present(value: Any) -> Any:
+    if _is_pair(value):
+        return value[0] if value[0] is not None else value[1]
+    if _is_timeline(value):
+        for item in value:
+            if item is not None:
+                return item
+        return None
+    return value
+
+
+def iter_changed_edges(visual: VisualGraph) -> Iterable[VisualEdge]:
+    """Yield edges whose visual state is not unchanged."""
+
+    return (edge for edge in visual.edges if edge.state != "unchanged")
+
+
+def iter_changed_nodes(visual: VisualGraph) -> Iterable[VisualNode]:
+    """Yield nodes with at least one visual badge/change marker."""
+
+    return (node for node in visual.nodes if node.changed)

synkit/__init__.py

@@ -0,0 +1,3 @@
+from .version import __version__
+
+__all__ = ["__version__"]

synkit/_native.py

@@ -0,0 +1,91 @@
+"""Shared discovery and installed-file verification for bundled C ABI libraries."""
+
+import base64
+from functools import lru_cache
+import hashlib
+from importlib.metadata import distribution
+import json
+import os
+from pathlib import Path
+import sys
+
+
+def bundled_library(package_dir, stem):
+    """Locate one packaged library without compiling or downloading anything."""
+    name = (
+        stem + ".dll"
+        if sys.platform == "win32"
+        else (
+            "lib" + stem + ".dylib"
+            if sys.platform == "darwin"
+            else "lib" + stem + ".so"
+        )
+    )
+    path = Path(package_dir).resolve() / "lib" / name
+    if not path.is_file():
+        raise FileNotFoundError(f"No bundled {stem} library is installed")
+    return path
+
+
+@lru_cache(maxsize=8)
+def _conda_record_digest(library_file):
+    """Read the owning Conda package's checksum after prefix relocation."""
+    package = Path(__file__).resolve().parent
+    library_file.relative_to(package)
+    for prefix in package.parents:
+        metadata = prefix / "conda-meta"
+        if metadata.is_dir():
+            return _conda_prefix_digest(prefix, library_file)
+    return None
+
+
+def _conda_prefix_digest(prefix, library_file):
+    relative = os.path.normcase(library_file.relative_to(prefix).as_posix())
+    for filename in sorted((prefix / "conda-meta").glob("synkit-*.json")):
+        try:
+            record = json.loads(filename.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise RuntimeError("Cannot read installed SynKit Conda metadata") from exc
+        if record.get("name") != "synkit":
+            continue
+        for entry in record.get("paths_data", {}).get("paths", ()):
+            if os.path.normcase(entry.get("_path", "")) != relative:
+                continue
+            # Conda and Mamba record bytes after relocation/code signing here.
+            digest = entry.get("sha256_in_prefix") or entry.get("sha256")
+            if (
+                isinstance(digest, str)
+                and len(digest) == 64
+                and all(c in "0123456789abcdefABCDEF" for c in digest)
+            ):
+                return digest.lower()
+            raise RuntimeError(f"The bundled library has no installed Conda SHA-256 record: {relative}")
+    return None
+
+
+@lru_cache(maxsize=8)
+def _wheel_record_digest(library_file):
+    installed = distribution("synkit")
+    relative = (
+        "synkit/" + library_file.relative_to(Path(__file__).resolve().parent).as_posix()
+    )
+    for entry in installed.files or ():
+        if (
+            str(entry) == relative
+            and Path(installed.locate_file(entry)).resolve() == library_file
+        ):
+            if entry.hash is not None and entry.hash.mode == "sha256":
+                return base64.urlsafe_b64decode(entry.hash.value + "==").hex()
+    raise RuntimeError(
+        f"The bundled library has no installed wheel SHA-256 record: {relative}"
+    )
+
+
+def verify_wheel_library(path):
+    """Check final installed bytes against their Conda or wheel SHA-256 record."""
+    path = Path(path).resolve()
+    expected = _conda_record_digest(path) or _wheel_record_digest(path)
+    actual = hashlib.sha256(path.read_bytes()).hexdigest()
+    if actual != expected:
+        raise RuntimeError(f"Bundled native library checksum mismatch: {path.name}")
+    return actual

synkit/examples.py

@@ -0,0 +1,50 @@
+# synkit/examples.py
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib.resources import files, as_file
+
+from synkit.IO import load_database  # adjust if the import path differs
+
+
+def _sanitize_slug(slug: str) -> str:
+    if ".." in slug or slug.startswith(("/", "\\")):
+        raise ValueError(f"Invalid example name: {slug!r}")
+    return slug
+
+
+def list_examples() -> list[str]:
+    """
+    Returns all available example slugs (without extensions), e.g. ['paracetamol', ...]
+    """
+    data_dir = files("synkit").joinpath("Data")
+    slugs: set[str] = set()
+    for p in data_dir.iterdir():
+        if not p.is_file():
+            continue
+        if p.name.endswith(".json.gz"):
+            slugs.add(p.name[: -len(".json.gz")])
+        elif p.name.endswith(".json"):
+            slugs.add(p.name[: -len(".json")])
+    return sorted(slugs)
+
+
+@lru_cache(maxsize=32)
+def load_example(slug: str):
+    """
+    Load an example by slug, preferring compressed (.json.gz) over plain (.json).
+    Delegates actual parsing to synkit.IO.load_database.
+    """
+    slug = _sanitize_slug(slug)
+    data_dir = files("synkit").joinpath("Data")
+    candidates = [f"{slug}.json.gz", f"{slug}.json"]
+    for name in candidates:
+        resource = data_dir.joinpath(name)
+        if resource.is_file():
+            # importlib.resources may keep resources inside archives; as_file gives a real path
+            with as_file(resource) as real_path:
+                return load_database(real_path)
+    raise FileNotFoundError(
+        f"Example '{slug}' not found (looked for {', '.join(candidates)})"
+    )

synkit/version.py

@@ -0,0 +1,23 @@
+"""Installed and source-checkout version discovery."""
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+try:
+    # A source checkout can coexist with an older installed distribution.
+    # Prefer its adjacent project metadata; installed wheels do not include
+    # the repository-level pyproject and therefore fall through naturally.
+    pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    __version__ = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"][
+        "version"
+    ]
+except (KeyError, OSError, tomllib.TOMLDecodeError):
+    try:
+        __version__ = version("synkit")
+    except PackageNotFoundError:
+        __version__ = "1.6.5"