cpg2py 1.0.5__py3-none-any.whl → 1.2.0__py3-none-any.whl

cpg2py/__init__.py

@@ -1,40 +1,103 @@
 from csv import DictReader
 from pathlib import Path
-from .cpg import _Graph
-from .abc import *
+from typing import Union
 
-def cpg_graph(node_csv: Path, edge_csv: Path, verbose: bool = False) -> "_Graph":
+from ._abc import Storage
+from ._abc import AbcEdgeQuerier, AbcGraphQuerier, AbcNodeQuerier
+from ._cpg import CpgEdge, CpgGraph, CpgNode
+from ._exceptions import CPGError, EdgeNotFoundError, NodeNotFoundError, TopFileNotFoundError
+from ._logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def storage_from_json(path: Union[Path, str]) -> Storage:
+    """
+    Creates a Storage instance populated from a JSON file.
+
+    Args:
+        path: Path to JSON file (Path or str).
+
+    Returns:
+        New Storage instance containing the graph.
+
+    Raises:
+        OSError: If the file cannot be read.
+        ValueError: If JSON structure is invalid (missing "nodes" or "edges").
+        KeyError: If an edge object is missing "from", "to", or "type".
+    """
+    storage = Storage()
+    storage.load_json(path)
+    return storage
+
+
+def cpg_graph(node_csv: Path, edge_csv: Path, verbose: bool = False) -> CpgGraph:
+    """
+    Creates a CPG graph from CSV files.
+
+    Args:
+        node_csv: Path to the nodes CSV file
+        edge_csv: Path to the edges CSV file
+        verbose: If True, log warnings for duplicate nodes/edges
+
+    Returns:
+        Graph instance loaded from CSV files
+    """
     storage = Storage()
-    with open(node_csv, 'r') as n_file: 
-        reader = DictReader(n_file, delimiter='\t')
-        for node_props in reader: 
-            nid = node_props.get("id:int", None) 
-            if nid is None: node_props.get("id") 
-            if not storage.add_node(nid) and verbose: 
-                print(f"WARN: Node {nid} already exists in the graph")
-            if not storage.set_node_props(nid, node_props) and verbose: 
-                print(f"WARN: Failed to set properties for node {nid}")
-    with open(edge_csv, 'r') as f:
-        reader = DictReader(f, delimiter='\t')
-        for edge_props in reader: 
-            f_nid = str(edge_props.get("start", None) )
-            if f_nid is None: f_nid = str(edge_props.get("start:str"))
+    with open(node_csv, "r", encoding="utf-8") as n_file:
+        reader = DictReader(n_file, delimiter="\t")
+        for node_props in reader:
+            nid = node_props.get("id:int", None)
+            if nid is None:
+                nid = node_props.get("id")
+            if nid is None:
+                continue
+            if not storage.add_node(nid) and verbose:
+                logger.warning("Node %s already exists in the graph", nid)
+            if not storage.set_node_props(nid, node_props) and verbose:
+                logger.warning("Failed to set properties for node %s", nid)
+    with open(edge_csv, "r", encoding="utf-8") as f:
+        reader = DictReader(f, delimiter="\t")
+        for edge_props in reader:
+            f_nid = str(edge_props.get("start", None))
+            if f_nid is None:
+                f_nid = str(edge_props.get("start:str"))
             t_nid = str(edge_props.get("end", None))
-            if t_nid is None: t_nid = str(edge_props.get("end:str"))
+            if t_nid is None:
+                t_nid = str(edge_props.get("end:str"))
             e_type = str(edge_props.get("type", None))
-            if e_type is None: e_type = str(edge_props.get("type:str"))
+            if e_type is None:
+                e_type = str(edge_props.get("type:str"))
             edge_id = (f_nid, t_nid, e_type)
-            if not storage.contains_node(edge_id[0]): 
+            if not storage.contains_node(edge_id[0]):
                 storage.add_node(edge_id[0])
-                if verbose: print(f"WARN: node {edge_id[0]} does not exists")
-            if not storage.contains_node(edge_id[1]): 
+                if verbose:
+                    logger.warning("Node %s does not exist", edge_id[0])
+            if not storage.contains_node(edge_id[1]):
                 storage.add_node(edge_id[1])
-                if verbose: print(f"WARN: node {edge_id[1]} does not exists")
-            if not storage.add_edge(edge_id): 
-                if verbose: print(f"WARN: Edge {f_nid} -> {t_nid} already exists in the graph")
-            if not storage.set_edge_props(edge_id, edge_props): 
-                if verbose: print(f"WARN: Failed to set properties for edge {edge_id}")
-        return _Graph(storage)
+                if verbose:
+                    logger.warning("Node %s does not exist", edge_id[1])
+            if not storage.add_edge(edge_id):
+                if verbose:
+                    logger.warning("Edge %s -> %s already exists in the graph", f_nid, t_nid)
+            if not storage.set_edge_props(edge_id, edge_props):
+                if verbose:
+                    logger.warning("Failed to set properties for edge %s", edge_id)
+    return CpgGraph(storage)
 
 
-__all__ = ['cpg_graph', 'AbcGraphQuerier', 'AbcNodeQuerier', 'AbcEdgeQuerier', 'Storage']
+__all__ = [
+    "cpg_graph",
+    "storage_from_json",
+    "CpgGraph",
+    "CpgNode",
+    "CpgEdge",
+    "AbcGraphQuerier",
+    "AbcNodeQuerier",
+    "AbcEdgeQuerier",
+    "Storage",
+    "CPGError",
+    "NodeNotFoundError",
+    "EdgeNotFoundError",
+    "TopFileNotFoundError",
+]

cpg2py/{abc → _abc}/__init__.py

@@ -1,6 +1,6 @@
+from .edge import AbcEdgeQuerier
 from .graph import AbcGraphQuerier
 from .node import AbcNodeQuerier
-from .edge import AbcEdgeQuerier
 from .storage import Storage
 
-__all__ = ["Storage", "AbcGraphQuerier", "AbcNodeQuerier", "AbcEdgeQuerier"]
+__all__ = ["Storage", "AbcGraphQuerier", "AbcNodeQuerier", "AbcEdgeQuerier"]

cpg2py/_abc/edge.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import abc
+from typing import Any, Dict, Optional, Tuple
+
+from .._exceptions import EdgeNotFoundError
+from .storage import Storage
+
+
+class AbcEdgeQuerier(abc.ABC):
+    """
+    Abstract base class for edge property access, queries, and updates.
+    """
+
+    def __init__(self, graph: Storage, f_nid: str, t_nid: str, e_type: str) -> None:
+        """
+        Initializes edge querier and validates edge existence.
+
+        Args:
+            graph: Storage instance containing the graph.
+            f_nid: Source node ID.
+            t_nid: Target node ID.
+            e_type: Edge type string.
+
+        Raises:
+            EdgeNotFoundError: If edge does not exist in the graph.
+        """
+        self.__graph: Storage = graph
+        self.__edge_id: Tuple[str, str, str] = (str(f_nid), str(t_nid), str(e_type))
+        if not graph.contains_edge(self.__edge_id):
+            raise EdgeNotFoundError(f_nid, t_nid, e_type)
+
+    @property
+    def edge_id(self) -> Tuple[str, str, str]:
+        """
+        Returns the edge identifier tuple (from_nid, to_nid, edge_type).
+        """
+        return self.__edge_id
+
+    @property
+    def from_nid(self) -> str:
+        """Returns the source node identifier."""
+        return self.__edge_id[0]
+
+    @property
+    def to_nid(self) -> str:
+        """Returns the target node identifier."""
+        return self.__edge_id[1]
+
+    @property
+    def edge_type(self) -> str:
+        """Returns the edge type string."""
+        return self.__edge_id[2]
+
+    @property
+    def properties(self) -> Optional[Dict[str, Any]]:
+        """Returns all edge properties dictionary, or None if not found."""
+        return self.__graph.get_edge_props(self.__edge_id)
+
+    def get_property(self, *prop_names: str) -> Optional[Any]:
+        """
+        Returns first found property value trying multiple name alternatives.
+
+        Args:
+            prop_names: Property name alternatives to try.
+
+        Returns:
+            First found value, or None if none found.
+        """
+        prop_values = (self.__graph.get_edge_prop(self.__edge_id, p_name) for p_name in prop_names)
+        return next((value for value in prop_values if value is not None), None)
+
+    def set_property(self, key: str, value: Any) -> bool:
+        """
+        Sets single edge property value.
+
+        Args:
+            key: Property key.
+            value: Property value.
+
+        Returns:
+            True if property was set, False if edge does not exist.
+        """
+        return self.__graph.set_edge_prop(self.__edge_id, key, value)
+
+    def set_properties(self, props: Dict[str, Any]) -> bool:
+        """
+        Updates multiple edge properties at once.
+
+        Args:
+            props: Dictionary of property key-value pairs.
+
+        Returns:
+            True if properties were updated, False if edge does not exist.
+        """
+        return self.__graph.set_edge_props(self.__edge_id, props)

cpg2py/_abc/graph.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import abc
+from collections import deque
+from typing import Callable, Deque, Generic, Iterable, List, Optional, TypeVar
+
+from .edge import AbcEdgeQuerier
+from .node import AbcNodeQuerier
+from .storage import Storage
+
+# Type variables for generic graph querier
+# Covariant: subtypes can be used where base types are expected
+_NodeType = TypeVar("_NodeType", bound=AbcNodeQuerier, covariant=True)
+_EdgeType = TypeVar("_EdgeType", bound=AbcEdgeQuerier, covariant=True)
+
+# Type variables for concrete implementations (invariant)
+_ConcreteNodeType = TypeVar("_ConcreteNodeType", bound=AbcNodeQuerier)
+_ConcreteEdgeType = TypeVar("_ConcreteEdgeType", bound=AbcEdgeQuerier)
+
+
+class AbcGraphQuerier(abc.ABC, Generic[_ConcreteNodeType, _ConcreteEdgeType]):
+    """
+    Abstract base class for graph query operations.
+
+    Provides interface for querying nodes, edges, and traversing graph structures.
+
+    This is a generic class that allows type-safe operations based on the concrete
+    node and edge types. When you create a concrete implementation, specify the
+    node and edge types:
+
+    Example:
+        class MyGraph(AbcGraphQuerier[MyNode, MyEdge]):
+            ...
+
+    Type Parameters:
+        _ConcreteNodeType: The concrete node type returned by node() and related methods
+        _ConcreteEdgeType: The concrete edge type returned by edge() and used in conditions
+    """
+
+    __NodeCondition = Callable[[_NodeType], bool]
+    __EdgeCondition = Callable[[_EdgeType], bool]
+
+    __always_true = lambda _: True
+
+    __NodesResult = Iterable[_ConcreteNodeType]
+    __EdgesResult = Iterable[_ConcreteEdgeType]
+
+    def __init__(self, target: Storage, maxdepth: int = -1) -> None:
+        """
+        Initializes a graph querier.
+
+        Args:
+            target: Storage instance containing the graph
+            maxdepth: Maximum depth for traversal operations (-1 for unlimited)
+        """
+        self.__graph: Storage = target
+        self.__maxdepth: int = maxdepth
+
+    @property
+    def storage(self) -> Storage:
+        """
+        Returns the underlying storage instance.
+
+        Returns:
+            Storage instance
+        """
+        return self.__graph
+
+    @abc.abstractmethod
+    def node(self, whose_id_is: str) -> Optional[_ConcreteNodeType]:
+        """
+        Returns a node by its ID.
+
+        Args:
+            whose_id_is: Node ID to look up
+
+        Returns:
+            Node instance if found, None otherwise
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def edge(self, fid: str, tid: str, eid: str) -> Optional[_ConcreteEdgeType]:
+        """
+        Returns an edge by its source, target, and edge type.
+
+        Args:
+            fid: Source node ID
+            tid: Target node ID
+            eid: Edge type/ID
+
+        Returns:
+            Edge instance if found, None otherwise
+        """
+        raise NotImplementedError
+
+    def nodes(
+        self, who_satisifies: __NodeCondition = __always_true
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns all nodes matching the condition.
+
+        Args:
+            who_satisifies: Node condition filter
+
+        Yields:
+            Nodes matching the condition
+        """
+        for nid in self.__graph.get_nodes():
+            cur_node = self.node(whose_id_is=nid)
+            if cur_node and who_satisifies(cur_node):
+                yield cur_node
+
+    def first_node(
+        self, who_satisifies: __NodeCondition = __always_true
+    ) -> Optional[_ConcreteNodeType]:
+        """
+        Returns the first node matching the condition.
+
+        Args:
+            who_satisifies: Node condition filter
+
+        Returns:
+            First matching node, or None if no match
+        """
+        return next(self.nodes(who_satisifies), None)
+
+    def edges(
+        self, who_satisifies: __EdgeCondition = __always_true
+    ) -> Iterable[_ConcreteEdgeType]:
+        """
+        Returns all edges matching the condition.
+
+        Args:
+            who_satisifies: Edge condition filter
+
+        Yields:
+            Edges matching the condition
+        """
+        for from_id, to_id, edge_id in self.__graph.get_edges():
+            cur_edge = self.edge(from_id, to_id, edge_id)
+            if cur_edge and who_satisifies(cur_edge):
+                yield cur_edge
+
+    def succ(
+        self, of: _ConcreteNodeType, who_satisifies: __EdgeCondition = __always_true
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns successor nodes connected to the input node.
+
+        Args:
+            of: Source node
+            who_satisifies: Edge condition filter
+
+        Yields:
+            Successor nodes matching the condition
+        """
+        for src, dst, edge_type in self.__graph.out_edges(of.node_id):
+            edge = self.edge(src, dst, edge_type)
+            if edge and who_satisifies(edge):
+                node = self.node(whose_id_is=dst)
+                if node:
+                    yield node
+
+    def prev(
+        self, of: _ConcreteNodeType, who_satisifies: __EdgeCondition = __always_true
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns predecessor nodes connected to the input node.
+
+        Args:
+            of: Target node
+            who_satisifies: Edge condition filter
+
+        Yields:
+            Predecessor nodes matching the condition
+        """
+        for src, dst, edge_type in self.__graph.in_edges(of.node_id):
+            edge = self.edge(src, dst, edge_type)
+            if edge and who_satisifies(edge):
+                node = self.node(whose_id_is=src)
+                if node:
+                    yield node
+
+    def __bfs_search(
+        self, root: _ConcreteNodeType, condition: __EdgeCondition, reverse: bool
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns nodes from src node by BFS order (src node not included).
+
+        Args:
+            root: Starting node
+            condition: Edge condition filter
+            reverse: If True, traverse backwards
+
+        Yields:
+            Nodes in BFS order (excluding root)
+        """
+        if root is None:
+            return
+        visited_nids: List[str] = []
+        nodes_queue: Deque[_ConcreteNodeType] = deque([root, None])
+        depth = self.__maxdepth
+        while depth != 0 and len(nodes_queue) > 1:
+            cur_node = nodes_queue.popleft()
+            if cur_node is None:
+                nodes_queue.append(None)
+                depth -= 1
+            elif cur_node.node_id not in visited_nids:
+                visited_nids.append(cur_node.node_id)
+                if not reverse:
+                    n_nodes = self.succ(cur_node, condition)
+                else:
+                    n_nodes = self.prev(cur_node, condition)
+                nodes_queue.extend(n_nodes)
+                if root.node_id != cur_node.node_id:
+                    yield cur_node
+
+    def descendants(
+        self, src: _ConcreteNodeType, condition: __EdgeCondition = __always_true
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns descendants from src node by BFS order (src node not included).
+
+        Args:
+            src: Source node
+            condition: Edge condition filter
+
+        Yields:
+            Descendant nodes in BFS order
+        """
+        return self.__bfs_search(src, condition, reverse=False)
+
+    def ancestors(
+        self, src: _ConcreteNodeType, condition: __EdgeCondition = __always_true
+    ) -> Iterable[_ConcreteNodeType]:
+        """
+        Returns ancestors from src node by BFS order (src node not included).
+
+        Args:
+            src: Source node
+            condition: Edge condition filter
+
+        Yields:
+            Ancestor nodes in BFS order
+        """
+        return self.__bfs_search(src, condition, reverse=True)

cpg2py/_abc/node.py

@@ -0,0 +1,75 @@
+import abc
+from typing import Any, Dict, Optional
+
+from .._exceptions import NodeNotFoundError
+from .storage import Storage
+
+
+class AbcNodeQuerier(abc.ABC):
+    """
+    Abstract base class for node property access, queries, and updates.
+    """
+
+    def __init__(self, graph: Storage, nid: str) -> None:
+        """
+        Initializes node querier and validates node existence.
+
+        Args:
+            graph: Storage instance containing the graph.
+            nid: Node identifier.
+
+        Raises:
+            NodeNotFoundError: If node does not exist in the graph.
+        """
+        self.__nid: str = str(nid)
+        self.__graph: Storage = graph
+        if not graph.contains_node(self.__nid):
+            raise NodeNotFoundError(str(nid))
+
+    @property
+    def node_id(self) -> str:
+        """Returns the node identifier."""
+        return self.__nid
+
+    @property
+    def properties(self) -> Optional[Dict[str, Any]]:
+        """Returns all node properties dictionary, or None if not found."""
+        return self.__graph.get_node_props(self.__nid)
+
+    def get_property(self, *prop_names: str) -> Optional[Any]:
+        """
+        Returns first found property value trying multiple name alternatives.
+
+        Args:
+            prop_names: Property name alternatives to try.
+
+        Returns:
+            First found value, or None if none found.
+        """
+        prop_values = (self.__graph.get_node_prop(self.__nid, p_name) for p_name in prop_names)
+        return next((value for value in prop_values if value is not None), None)
+
+    def set_property(self, key: str, value: Any) -> bool:
+        """
+        Sets single node property value.
+
+        Args:
+            key: Property key.
+            value: Property value.
+
+        Returns:
+            True if property was set, False if node does not exist.
+        """
+        return self.__graph.set_node_prop(self.__nid, key, value)
+
+    def set_properties(self, props: Dict[str, Any]) -> bool:
+        """
+        Updates multiple node properties at once.
+
+        Args:
+            props: Dictionary of property key-value pairs.
+
+        Returns:
+            True if properties were updated, False if node does not exist.
+        """
+        return self.__graph.set_node_props(self.__nid, props)