cpg2py 1.1.0__tar.gz → 1.2.0__tar.gz

{cpg2py-1.1.0 → cpg2py-1.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Yichao Xu
+Copyright (c) 2025 samhsu-dev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

cpg2py-1.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: cpg2py
+Version: 1.2.0
+Summary: A graph-based data structure designed for querying CSV files in Joern format in Python
+Author-email: samhsu-dev <yxu166@jhu.edu>
+License: MIT License
+        
+        Copyright (c) 2025 samhsu-dev
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/samhsu-dev/cpg2py
+Project-URL: Repository, https://github.com/samhsu-dev/cpg2py
+Project-URL: Documentation, https://github.com/samhsu-dev/cpg2py
+Keywords: Joern,CPG,Graph,CSV
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: pylint>=2.17.0; extra == "dev"
+Dynamic: license-file
+
+# cpg2py
+
+Python graph query engine for Code Property Graphs from Joern CSV exports. Directed multi-graph with generic ABCs for custom node/edge/graph types.
+
+**Features**: Load from `nodes.csv` + `rels.csv`; query/update nodes and edges (`get_property`, `set_property`, `set_properties`); traverse succ/prev/children/parent/flow_to/flow_from; JSON persistence (`save_json`, `load_json`, `storage_from_json`). Concrete types: `CpgGraph`, `CpgNode`, `CpgEdge`.
+
+---
+
+## Installation
+
+```bash
+pip install cpg2py
+```
+
+From source (e.g. with [uv](https://github.com/astral-sh/uv)):
+
+```bash
+git clone https://github.com/samhsu-dev/cpg2py.git && cd cpg2py
+uv sync --dev
+uv run pytest tests/
+```
+
+---
+
+## Input format
+
+- **nodes.csv**: tab-delimited; must include node id (e.g. `id:int` or `id`). Other columns become node properties.
+- **rels.csv**: tab-delimited; columns `start`, `end`, `type` (or `start:str`, `end:str`, `type:str`).
+
+---
+
+## Usage
+
+**Load from CSV**
+
+```python
+from pathlib import Path
+from cpg2py import cpg_graph, CpgGraph, CpgNode, CpgEdge
+
+graph: CpgGraph = cpg_graph(Path("nodes.csv"), Path("rels.csv"))
+```
+
+**Nodes and edges** (edge identified by `(from_id, to_id, edge_type)`; `edge_type` is string)
+
+```python
+node: CpgNode = graph.node("2")
+node.name
+node.set_property("name", "x")
+node.set_properties({"k": "v"})
+
+edge: CpgEdge = graph.edge("2", "3", "ENTRY")
+edge.from_nid, edge.to_nid, edge.type
+edge.set_property("weight", 0.5)
+```
+
+**Traversal**
+
+```python
+graph.succ(node)   # successors
+graph.prev(node)   # predecessors
+graph.children(node)
+graph.parent(node)
+graph.flow_to(node)
+graph.flow_from(node)
+graph.topfile_node("5")   # top-level file node for given node ID
+```
+
+**Filtered iteration** (optional predicate)
+
+```python
+graph.nodes(lambda n: n.type == "Function")
+graph.edges(lambda e: e.edge_type == "FLOWS_TO")
+graph.succ(node, who_satisifies=lambda e: e.edge_type == "PARENT_OF")
+graph.descendants(node, condition=...)
+graph.ancestors(node, condition=...)
+```
+
+**JSON persistence**
+
+```python
+graph.storage.save_json("graph.json")
+
+storage = Storage()
+storage.load_json("graph.json")
+graph2 = CpgGraph(storage)
+
+# or
+storage = storage_from_json(Path("graph.json"))
+```
+
+JSON schema: `{"nodes": { "<id>": { "<key>": <value>, ... }, ... }, "edges": [ {"from": str, "to": str, "type": str, "props": {...} }, ... ]}`. See [design.md](docs/design.md).
+
+---
+
+## Extending (ABCs)
+
+Implement `AbcGraphQuerier[MyNode, MyEdge]`, `AbcNodeQuerier`, `AbcEdgeQuerier`; inject `Storage`. Full interface and contracts: [docs/design.md](docs/design.md).
+
+Minimal custom graph:
+
+```python
+from cpg2py import AbcGraphQuerier, AbcNodeQuerier, AbcEdgeQuerier, Storage
+from typing import Optional
+
+class MyNode(AbcNodeQuerier): pass
+class MyEdge(AbcEdgeQuerier): pass
+
+class MyGraph(AbcGraphQuerier[MyNode, MyEdge]):
+    def node(self, whose_id_is: str) -> Optional[MyNode]:
+        return MyNode(self.storage, whose_id_is)
+    def edge(self, fid: str, tid: str, eid: str) -> Optional[MyEdge]:
+        return MyEdge(self.storage, fid, tid, eid)
+
+g = MyGraph(Storage())
+```
+
+---
+
+Interface specifications (classes, methods, signatures, validation): [docs/design.md](docs/design.md).
+
+---
+
+## License
+MIT.

cpg2py-1.2.0/README.md

@@ -0,0 +1,124 @@
+# cpg2py
+
+Python graph query engine for Code Property Graphs from Joern CSV exports. Directed multi-graph with generic ABCs for custom node/edge/graph types.
+
+**Features**: Load from `nodes.csv` + `rels.csv`; query/update nodes and edges (`get_property`, `set_property`, `set_properties`); traverse succ/prev/children/parent/flow_to/flow_from; JSON persistence (`save_json`, `load_json`, `storage_from_json`). Concrete types: `CpgGraph`, `CpgNode`, `CpgEdge`.
+
+---
+
+## Installation
+
+```bash
+pip install cpg2py
+```
+
+From source (e.g. with [uv](https://github.com/astral-sh/uv)):
+
+```bash
+git clone https://github.com/samhsu-dev/cpg2py.git && cd cpg2py
+uv sync --dev
+uv run pytest tests/
+```
+
+---
+
+## Input format
+
+- **nodes.csv**: tab-delimited; must include node id (e.g. `id:int` or `id`). Other columns become node properties.
+- **rels.csv**: tab-delimited; columns `start`, `end`, `type` (or `start:str`, `end:str`, `type:str`).
+
+---
+
+## Usage
+
+**Load from CSV**
+
+```python
+from pathlib import Path
+from cpg2py import cpg_graph, CpgGraph, CpgNode, CpgEdge
+
+graph: CpgGraph = cpg_graph(Path("nodes.csv"), Path("rels.csv"))
+```
+
+**Nodes and edges** (edge identified by `(from_id, to_id, edge_type)`; `edge_type` is string)
+
+```python
+node: CpgNode = graph.node("2")
+node.name
+node.set_property("name", "x")
+node.set_properties({"k": "v"})
+
+edge: CpgEdge = graph.edge("2", "3", "ENTRY")
+edge.from_nid, edge.to_nid, edge.type
+edge.set_property("weight", 0.5)
+```
+
+**Traversal**
+
+```python
+graph.succ(node)   # successors
+graph.prev(node)   # predecessors
+graph.children(node)
+graph.parent(node)
+graph.flow_to(node)
+graph.flow_from(node)
+graph.topfile_node("5")   # top-level file node for given node ID
+```
+
+**Filtered iteration** (optional predicate)
+
+```python
+graph.nodes(lambda n: n.type == "Function")
+graph.edges(lambda e: e.edge_type == "FLOWS_TO")
+graph.succ(node, who_satisifies=lambda e: e.edge_type == "PARENT_OF")
+graph.descendants(node, condition=...)
+graph.ancestors(node, condition=...)
+```
+
+**JSON persistence**
+
+```python
+graph.storage.save_json("graph.json")
+
+storage = Storage()
+storage.load_json("graph.json")
+graph2 = CpgGraph(storage)
+
+# or
+storage = storage_from_json(Path("graph.json"))
+```
+
+JSON schema: `{"nodes": { "<id>": { "<key>": <value>, ... }, ... }, "edges": [ {"from": str, "to": str, "type": str, "props": {...} }, ... ]}`. See [design.md](docs/design.md).
+
+---
+
+## Extending (ABCs)
+
+Implement `AbcGraphQuerier[MyNode, MyEdge]`, `AbcNodeQuerier`, `AbcEdgeQuerier`; inject `Storage`. Full interface and contracts: [docs/design.md](docs/design.md).
+
+Minimal custom graph:
+
+```python
+from cpg2py import AbcGraphQuerier, AbcNodeQuerier, AbcEdgeQuerier, Storage
+from typing import Optional
+
+class MyNode(AbcNodeQuerier): pass
+class MyEdge(AbcEdgeQuerier): pass
+
+class MyGraph(AbcGraphQuerier[MyNode, MyEdge]):
+    def node(self, whose_id_is: str) -> Optional[MyNode]:
+        return MyNode(self.storage, whose_id_is)
+    def edge(self, fid: str, tid: str, eid: str) -> Optional[MyEdge]:
+        return MyEdge(self.storage, fid, tid, eid)
+
+g = MyGraph(Storage())
+```
+
+---
+
+Interface specifications (classes, methods, signatures, validation): [docs/design.md](docs/design.md).
+
+---
+
+## License
+MIT.

{cpg2py-1.1.0 → cpg2py-1.2.0}/cpg2py/__init__.py

@@ -1,14 +1,36 @@
 from csv import DictReader
 from pathlib import Path
+from typing import Union
 
-from ._abc import *
-from ._cpg import CpgGraph, CpgNode, CpgEdge
+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.
@@ -66,6 +88,7 @@ def cpg_graph(node_csv: Path, edge_csv: Path, verbose: bool = False) -> CpgGraph
 
 __all__ = [
     "cpg_graph",
+    "storage_from_json",
     "CpgGraph",
     "CpgNode",
     "CpgEdge",

cpg2py-1.2.0/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-1.2.0/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)

{cpg2py-1.1.0 → cpg2py-1.2.0}/cpg2py/_abc/storage.py

@@ -1,4 +1,6 @@
-from typing import Any, Dict, Iterable, List, Optional, Tuple
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
 
 from .._logger import get_logger
 
@@ -188,3 +190,69 @@ class Storage:
         self.__struct[eid[1]].remove(eid)
         self.__edges.pop(eid)
         return True
+
+    def save_json(self, path: Union[Path, str]) -> None:
+        """
+        Serializes the graph (nodes and edges with properties) to a UTF-8 JSON file.
+
+        Args:
+            path: File path (Path or str).
+
+        Raises:
+            OSError: If the file cannot be written.
+            TypeError: If a property value is not JSON-serializable.
+        """
+        payload: Dict[str, Any] = {
+            "nodes": dict(self.__nodes),
+            "edges": [
+                {"from": eid[0], "to": eid[1], "type": eid[2], "props": props}
+                for eid, props in self.__edges.items()
+            ],
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+
+    def load_json(self, path: Union[Path, str]) -> None:
+        """
+        Replaces the current graph with the contents of the JSON file.
+
+        Clears existing nodes and edges, then loads nodes, edges, and their
+        properties. Expects top-level keys "nodes" and "edges".
+
+        Args:
+            path: File path (Path or str).
+
+        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".
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            data: Dict[str, Any] = json.load(f)
+        if "nodes" not in data or "edges" not in data:
+            raise ValueError("JSON must contain top-level 'nodes' and 'edges'")
+        self.__nodes = {}
+        self.__edges = {}
+        self.__struct = {}
+        nodes_data: Dict[str, Dict[str, Any]] = data["nodes"]
+        for nid, props in nodes_data.items():
+            nid_str = str(nid)
+            self.__nodes[nid_str] = dict(props) if props else {}
+            self.__struct[nid_str] = []
+        for edge_obj in data["edges"]:
+            from_nid = str(edge_obj["from"])
+            to_nid = str(edge_obj["to"])
+            etype = str(edge_obj["type"])
+            props = edge_obj.get("props")
+            if props is None:
+                props = {}
+            eid = (from_nid, to_nid, etype)
+            if from_nid not in self.__nodes:
+                self.__nodes[from_nid] = {}
+                self.__struct[from_nid] = []
+            if to_nid not in self.__nodes:
+                self.__nodes[to_nid] = {}
+                self.__struct[to_nid] = []
+            self.__edges[eid] = dict(props)
+            self.__struct[from_nid].append(eid)
+            self.__struct[to_nid].append(eid)

{cpg2py-1.1.0 → cpg2py-1.2.0}/cpg2py/_cpg/edge.py

@@ -2,12 +2,11 @@ from __future__ import annotations
 
 from typing import Optional, Tuple
 
-from .._abc import AbcEdgeQuerier, AbcGraphQuerier
+from .._abc import AbcEdgeQuerier
 
 
 class CpgEdge(AbcEdgeQuerier):
-    def __init__(self, graph: AbcGraphQuerier, f_nid: str, t_nid: str, e_type: str) -> None:
-        super().__init__(graph, f_nid, t_nid, e_type)
+    """Concrete edge implementation with CPG-specific property accessors."""
 
     @property
     def id(self) -> Tuple[str, str, str]:

{cpg2py-1.1.0 → cpg2py-1.2.0}/cpg2py/_cpg/node.py

@@ -2,12 +2,11 @@ from __future__ import annotations
 
 from typing import List, Optional
 
-from .._abc import AbcGraphQuerier, AbcNodeQuerier
+from .._abc import AbcNodeQuerier
 
 
 class CpgNode(AbcNodeQuerier):
-    def __init__(self, graph: AbcGraphQuerier, nid: str) -> None:
-        super().__init__(graph, nid)
+    """Concrete node implementation with CPG-specific property accessors."""
 
     @property
     def id(self) -> str:

{cpg2py-1.1.0 → cpg2py-1.2.0}/cpg2py/_exceptions.py

@@ -1,6 +1,6 @@
-"""
-Custom exceptions for cpg2py package.
-"""
+"""Custom exceptions for cpg2py package."""
+
+from typing import Optional
 
 
 class CPGError(Exception):
@@ -8,9 +8,9 @@ class CPGError(Exception):
 
 
 class NodeNotFoundError(CPGError):
-    """Raised when a node cannot be found in the graph."""
+    """Raised when node identifier does not exist in storage."""
 
-    def __init__(self, node_id: str, message: str = None):
+    def __init__(self, node_id: str, message: Optional[str] = None) -> None:
         self.node_id = node_id
         if message is None:
             message = f"Node with id '{node_id}' not found in graph"
@@ -18,9 +18,11 @@ class NodeNotFoundError(CPGError):
 
 
 class EdgeNotFoundError(CPGError):
-    """Raised when an edge cannot be found in the graph."""
+    """Raised when edge identifier tuple does not exist in storage."""
 
-    def __init__(self, from_id: str, to_id: str, edge_type: str, message: str = None):
+    def __init__(
+        self, from_id: str, to_id: str, edge_type: str, message: Optional[str] = None
+    ) -> None:
         self.from_id = from_id
         self.to_id = to_id
         self.edge_type = edge_type
@@ -32,9 +34,9 @@ class EdgeNotFoundError(CPGError):
 
 
 class TopFileNotFoundError(CPGError):
-    """Raised when top file node cannot be found."""
+    """Raised when top file node cannot be found during upward traversal."""
 
-    def __init__(self, node_id: str, message: str = None):
+    def __init__(self, node_id: str, message: Optional[str] = None) -> None:
         self.node_id = node_id
         if message is None:
             message = f"Cannot find top file node from node '{node_id}'"