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

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/_abc/edge.py

@@ -9,88 +9,88 @@ from .storage import Storage
 
 class AbcEdgeQuerier(abc.ABC):
     """
-    Abstract base class for edge query operations.
-
-    Provides interface for querying edge properties and accessing edge data.
+    Abstract base class for edge property access, queries, and updates.
     """
 
-    def __init__(self, graph: Storage, f_nid: str, t_nid: str, e_type: int = 0) -> None:
+    def __init__(self, graph: Storage, f_nid: str, t_nid: str, e_type: str) -> None:
         """
-        Initializes an edge querier.
+        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/ID
+            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
+            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, str(e_type))
+            raise EdgeNotFoundError(f_nid, t_nid, e_type)
 
     @property
-    def edge_id(self) -> Tuple[str, str, int]:
+    def edge_id(self) -> Tuple[str, str, str]:
         """
-        Returns the edge ID tuple.
-
-        Returns:
-            Edge ID tuple (from_node, to_node, edge_type)
+        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 ID.
-
-        Returns:
-            Source node ID string
-        """
+        """Returns the source node identifier."""
         return self.__edge_id[0]
 
     @property
     def to_nid(self) -> str:
-        """
-        Returns the target node ID.
-
-        Returns:
-            Target node ID string
-        """
+        """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 the edge type.
+        Returns first found property value trying multiple name alternatives.
+
+        Args:
+            prop_names: Property name alternatives to try.
 
         Returns:
-            Edge type string
+            First found value, or None if none found.
         """
-        return self.__edge_id[2]
+        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)
 
-    @property
-    def properties(self) -> Optional[Dict[str, Any]]:
+    def set_property(self, key: str, value: Any) -> bool:
         """
-        Returns all edge properties.
+        Sets single edge property value.
+
+        Args:
+            key: Property key.
+            value: Property value.
 
         Returns:
-            Dictionary of edge properties, or None if edge not found
+            True if property was set, False if edge does not exist.
         """
-        return self.__graph.get_edge_props(self.__edge_id)
+        return self.__graph.set_edge_prop(self.__edge_id, key, value)
 
-    def get_property(self, *prop_names: str) -> Optional[Any]:
+    def set_properties(self, props: Dict[str, Any]) -> bool:
         """
-        Gets an edge property by trying multiple possible property names.
+        Updates multiple edge properties at once.
 
         Args:
-            prop_names: Variable number of property name alternatives to try
+            props: Dictionary of property key-value pairs.
 
         Returns:
-            First found property value, or None if none found
+            True if properties were updated, False if edge does not exist.
         """
-        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)
+        return self.__graph.set_edge_props(self.__edge_id, props)

cpg2py/_abc/node.py

@@ -7,56 +7,69 @@ from .storage import Storage
 
 class AbcNodeQuerier(abc.ABC):
     """
-    Abstract base class for node query operations.
-
-    Provides interface for querying node properties and accessing node data.
+    Abstract base class for node property access, queries, and updates.
     """
 
     def __init__(self, graph: Storage, nid: str) -> None:
         """
-        Initializes a node querier.
+        Initializes node querier and validates node existence.
 
         Args:
-            graph: Storage instance containing the graph
-            nid: Node ID to query
+            graph: Storage instance containing the graph.
+            nid: Node identifier.
 
         Raises:
-            NodeNotFoundError: If node does not exist in the graph
+            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(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 the node ID.
+        Returns first found property value trying multiple name alternatives.
+
+        Args:
+            prop_names: Property name alternatives to try.
 
         Returns:
-            Node ID string
+            First found value, or None if none found.
         """
-        return self.__nid
+        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)
 
-    @property
-    def properties(self) -> Optional[Dict[str, Any]]:
+    def set_property(self, key: str, value: Any) -> bool:
         """
-        Returns all node properties.
+        Sets single node property value.
+
+        Args:
+            key: Property key.
+            value: Property value.
 
         Returns:
-            Dictionary of node properties, or None if node not found
+            True if property was set, False if node does not exist.
         """
-        return self.__graph.get_node_props(self.__nid)
+        return self.__graph.set_node_prop(self.__nid, key, value)
 
-    def get_property(self, *prop_names: str) -> Optional[Any]:
+    def set_properties(self, props: Dict[str, Any]) -> bool:
         """
-        Gets a node property by trying multiple possible property names.
+        Updates multiple node properties at once.
 
         Args:
-            prop_names: Variable number of property name alternatives to try
+            props: Dictionary of property key-value pairs.
 
         Returns:
-            First found property value, or None if none found
+            True if properties were updated, False if node does not exist.
         """
-        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)
+        return self.__graph.set_node_props(self.__nid, props)

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/_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/_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/_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}'"

cpg2py-1.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+cpg2py/__init__.py,sha256=j_4bRx0t-P10QnOXahQ89avNJne_1mVio0Gd62JIRLs,3548
+cpg2py/_exceptions.py,sha256=OlnptpATmuzRQS0HoC24MoDPcPrY01uGMhVPJdK7Zuo,1376
+cpg2py/_logger.py,sha256=HjJAhs4ZAB_IMoBMVRe3KPGS5GRygGy0eNncvIqu8ls,1309
+cpg2py/_abc/__init__.py,sha256=XN7RKxMpnZqvjDAUWxXXLGKY1jrPpKBAxUbq-pydwh4,208
+cpg2py/_abc/edge.py,sha256=Co3TXbfR2kd7G5oXFVEO0YjDND0zzFecf_R6yRHcyzw,2956
+cpg2py/_abc/graph.py,sha256=LDF2ylbJYQubUV2LboJlkiQaqWtLW3LsyKBkTJOl4Gs,7795
+cpg2py/_abc/node.py,sha256=ZnMf0TTi2Pv69AhzmomI8a8z8_05WgzVpK9p8VisTr8,2275
+cpg2py/_abc/storage.py,sha256=E8lB6uo4zMCvgFmg6LJ5x00AoAFT-gha8nY3FxcJAQE,9252
+cpg2py/_cpg/__init__.py,sha256=BYNrxYo0G3XoIaUN9llEYkZoCstYJgt88OrJZCkQW7E,126
+cpg2py/_cpg/edge.py,sha256=bqzv9dmAVMFSyDmyCLhE0SKIWZZ9gu9UWLC3j6dfhAQ,886
+cpg2py/_cpg/graph.py,sha256=Aks2VsDolKdT1NdEz9Vn5ABIWBTPDGvEq7PbrehLVuI,5674
+cpg2py/_cpg/node.py,sha256=wSBCTCvA8UWQZG9CJn0QyBlQPt9PiXlPd0B2Ddlr7BI,1945
+cpg2py-1.2.0.dist-info/licenses/LICENSE,sha256=ZAjdPt8K7uO5xDb4RyEuUTNZtFGx9_sfSQCy0OP64cU,1067
+cpg2py-1.2.0.dist-info/METADATA,sha256=a-sNUByG1k8a0xX_HFQKRmINP8LDcJ9FMuz5RcqjzNU,5915
+cpg2py-1.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cpg2py-1.2.0.dist-info/top_level.txt,sha256=xDY8faKh5Rczvsqb5Jt9Sq-Y7EOImh7jh-m1oVTnH5k,7
+cpg2py-1.2.0.dist-info/RECORD,,

{cpg2py-1.1.0.dist-info → cpg2py-1.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.3.3)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{cpg2py-1.1.0.dist-info → cpg2py-1.2.0.dist-info/licenses}/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.1.0.dist-info/METADATA

@@ -1,407 +0,0 @@
-Metadata-Version: 2.1
-Name: cpg2py
-Version: 1.1.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 Yichao Xu
-        
-        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/YichaoXu/cpg2py
-Project-URL: Repository, https://github.com/YichaoXu/cpg2py
-Project-URL: Documentation, https://github.com/YichaoXu/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: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Provides-Extra: test
-
-# **cpg2py: Graph-Based Query Engine for Joern CSV Files**
-
-`cpg2py` is a Python library that provides a lightweight **graph-based query engine** for analyzing **Code Property Graphs (CPG)** extracted from Joern CSV files. The library offers an **abstract base class (ABC) architecture**, allowing users to extend and implement their own custom graph queries.
-
----
-
-## **🚀 Features**
-
-- **MultiDiGraph Representation**: A directed multi-graph with support for multiple edges between nodes.
-- **CSV-Based Graph Construction**: Reads `nodes.csv` and `rels.csv` to construct a graph structure.
-- **Type-Safe Generic Types**: Uses Python generics for type-safe graph operations (similar to Java generics).
-- **Extensible Abstract Base Classes (ABC)**:
-  - `AbcGraphQuerier` for implementing **custom graph queries** with generic type support.
-  - `AbcNodeQuerier` for interacting with **nodes**.
-  - `AbcEdgeQuerier` for interacting with **edges**.
-- **Built-in Query Mechanisms**:
-  - **Retrieve all nodes and edges** with type-safe iteration.
-  - **Get incoming and outgoing edges** of a node.
-  - **Find successors and predecessors** with type preservation.
-  - **Traverse AST, Control Flow, and Data Flow Graphs**.
-- **Concrete Implementation**: `CpgGraph`, `CpgNode`, and `CpgEdge` provide ready-to-use implementations.
-
----
-
-## **📚 Installation**
-
-### Using pip
-
-To install the package, use:
-
-```bash
-pip install git+https://github.com/samhsu-dev/cpg2py.git
-```
-
-### Using uv (Recommended)
-
-This project uses [uv](https://github.com/astral-sh/uv) for fast and reliable package management.
-
-**Install uv:**
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-**Clone and install:**
-```bash
-git clone https://github.com/samhsu-dev/cpg2py.git
-cd cpg2py
-uv sync --dev  # Install with dev dependencies
-```
-
-**For development:**
-```bash
-uv sync --dev
-uv run pytest tests/  # Run tests
-```
-
-Or clone the pip repository:
-
-```bash
-pip install cpg2py
-```
-
----
-
-## **📂 File Structure**
-
-- **`nodes.csv`** (Example):
-```csv
-id:int	labels:label	type	flags:string_array	lineno:int	code	childnum:int	funcid:int	classname	namespace	endlineno:int	name	doccomment
-0	Filesystem	Directory									"input"	
-1	Filesystem	File									"example.php"	
-2	AST	AST_TOPLEVEL	TOPLEVEL_FILE	1					""	25	"/input/example.php"	
-
-````
-- **`rels.csv`** (Example):
-```csv
-start	end	type
-2	3	ENTRY
-2	4	EXIT
-6	7	ENTRY
-6	9	PARENT_OF
-````
-
----
-
-## **🎯 Type Safety with Generics**
-
-`cpg2py` uses Python's generic types (similar to Java generics) to provide type-safe operations:
-
-```python
-from typing import Iterable
-from cpg2py import cpg_graph, CpgGraph, CpgNode, CpgEdge
-
-# Type checker knows graph is CpgGraph[CpgNode, CpgEdge]
-graph: CpgGraph = cpg_graph("nodes.csv", "rels.csv")
-
-# Type checker knows node is CpgNode (not just AbcNodeQuerier)
-node: CpgNode = graph.node("5")
-
-# Type checker knows successors are Iterable[CpgNode]
-successors: Iterable[CpgNode] = graph.succ(node)
-for succ in successors:
-    succ.code  # Type-safe: IDE knows succ is CpgNode
-```
-
-This ensures that:
-- Return types are preserved throughout graph operations
-- IDE autocomplete works correctly
-- Type checkers (mypy, pyright) can verify type correctness
-
-For more details, see [Generics Documentation](docs/GENERICS.md).
-
----
-
-## **📚 Usage**
-
-### **1️⃣ Load Graph from Joern CSVs**
-
-```python
-from cpg2py import cpg_graph
-
-# Load graph from CSV files
-graph = cpg_graph("nodes.csv", "rels.csv")
-```
-
-The `cpg_graph` function returns a `CpgGraph` instance, which is the concrete implementation of the graph querier.
-
----
-
-### **2️⃣ Query Nodes & Edges**
-
-```python
-from cpg2py import CpgGraph, CpgNode, CpgEdge
-
-# Get a specific node (returns CpgNode)
-node: CpgNode = graph.node("2")
-print(node.name, node.type)  # Example output: "/tmp/example.php" AST_TOPLEVEL
-
-# Get a specific edge (returns CpgEdge)
-edge: CpgEdge = graph.edge("2", "3", "ENTRY")
-print(edge.type)  # Output: ENTRY
-```
-
----
-
-### **3️⃣ Get Node Connections**
-
-```python
-# Get all outgoing edges from a node
-outgoing_edges = graph.succ(node)
-for out_node in outgoing_edges:
-    print(out_node.id, out_node.name)  # out_node is CpgNode
-
-# Get all incoming edges to a node
-incoming_edges = graph.prev(node)
-for in_node in incoming_edges:
-    print(in_node.id, in_node.name)  # in_node is CpgNode
-```
-
----
-
-### **4️⃣ AST and Flow Queries**
-
-```python
-# Get top-level file node for a given node
-top_file: CpgNode = graph.topfile_node("5")
-print(top_file.name)  # Output: "example.php"
-
-# Get child nodes in the AST hierarchy
-children = graph.children(node)
-print([child.id for child in children])  # children are CpgNode instances
-
-# Get data flow successors
-flow_successors = graph.flow_to(node)
-print([succ.id for succ in flow_successors])  # successors are CpgNode instances
-```
-
----
-
-## **🛠 Abstract Base Classes (ABC)**
-
-The following abstract base classes (`ABC`) provide interfaces for extending **node**, **edge**, and **graph** querying behavior. All ABCs are imported directly from the main `cpg2py` package.
-
----
-
-### **🔹 AbcNodeQuerier (Abstract Node Interface)**
-
-This class defines how nodes interact with the graph storage.
-
-```python
-from cpg2py import AbcNodeQuerier, Storage
-
-class MyNodeQuerier(AbcNodeQuerier):
-    def __init__(self, graph: Storage, nid: str):
-        super().__init__(graph, nid)
-
-    @property
-    def name(self):
-        return self.get_property("name")
-```
-
----
-
-### **🔹 AbcEdgeQuerier (Abstract Edge Interface)**
-
-Defines the querying mechanisms for edges in the graph.
-
-```python
-from cpg2py import AbcEdgeQuerier, Storage
-
-class MyEdgeQuerier(AbcEdgeQuerier):
-    def __init__(self, graph: Storage, f_nid: str, t_nid: str, e_type: str):
-        super().__init__(graph, f_nid, t_nid, e_type)
-
-    @property
-    def type(self):
-        return self.get_property("type")
-```
-
----
-
-### **🔹 AbcGraphQuerier (Abstract Graph Interface)**
-
-This class provides an interface for implementing custom graph query mechanisms. It's a generic class that supports type-safe operations.
-
-```python
-from cpg2py import AbcGraphQuerier, Storage
-from typing import Optional
-
-class MyGraphQuerier(AbcGraphQuerier[MyNodeQuerier, MyEdgeQuerier]):
-    def node(self, nid: str) -> Optional[MyNodeQuerier]:
-        return MyNodeQuerier(self.storage, nid)
-
-    def edge(self, fid: str, tid: str, eid: str) -> Optional[MyEdgeQuerier]:
-        return MyEdgeQuerier(self.storage, fid, tid, eid)
-```
-
-**Note**: `AbcGraphQuerier` is a generic class parameterized by node and edge types, ensuring type safety throughout graph operations. The concrete implementation `CpgGraph` is defined as `AbcGraphQuerier[CpgNode, CpgEdge]`.
-
----
-
-## **🔍 Querying The Graph**
-
-After implementing the abstract classes, you can perform advanced queries:
-
-```python
-from cpg2py import Storage
-
-storage = Storage()
-graph = MyGraphQuerier(storage)
-
-# Query node properties
-node = graph.node("5")
-print(node.name)  # Example Output: "main"
-
-# Query edge properties
-edge = graph.edge("5", "6", "FLOWS_TO")
-print(edge.type)  # Output: "FLOWS_TO"
-```
-
-### **Using the Built-in CpgGraph**
-
-You can also use the built-in `CpgGraph` implementation directly:
-
-```python
-from typing import Iterable
-from cpg2py import cpg_graph, CpgGraph, CpgNode, CpgEdge
-
-# Load from CSV files
-graph: CpgGraph = cpg_graph("nodes.csv", "rels.csv")
-
-# Type-safe operations
-node: CpgNode = graph.node("5")
-edge: CpgEdge = graph.edge("5", "6", "FLOWS_TO")
-
-# Type-safe iteration
-successors: Iterable[CpgNode] = graph.succ(node)
-for succ in successors:
-    print(succ.code)  # Type checker knows succ is CpgNode
-```
-
----
-
-## **🐝 API Reference**
-
-For more detailed API documentation, please see our [APIs doc](docs/APIs.md).
-
-### **Main Package Exports**
-
-All public APIs are available directly from the `cpg2py` package:
-
-```python
-from cpg2py import (
-    # Factory function
-    cpg_graph,
-    
-    # Concrete implementations
-    CpgGraph,
-    CpgNode,
-    CpgEdge,
-    
-    # Abstract base classes
-    AbcGraphQuerier,
-    AbcNodeQuerier,
-    AbcEdgeQuerier,
-    Storage,
-    
-    # Exceptions
-    CPGError,
-    NodeNotFoundError,
-    EdgeNotFoundError,
-    TopFileNotFoundError,
-)
-```
-
-### **Graph Functions**
-
-- `cpg_graph(node_csv: Path, edge_csv: Path, verbose: bool = False) -> CpgGraph`: Loads graph from CSV files and returns a `CpgGraph` instance.
-- `graph.node(nid: str) -> Optional[CpgNode]`: Retrieves a node by ID (returns `CpgNode`).
-- `graph.edge(fid: str, tid: str, eid: str) -> Optional[CpgEdge]`: Retrieves an edge (returns `CpgEdge`).
-- `graph.succ(node: CpgNode) -> Iterable[CpgNode]`: Gets successor nodes.
-- `graph.prev(node: CpgNode) -> Iterable[CpgNode]`: Gets predecessor nodes.
-- `graph.children(node: CpgNode) -> Iterable[CpgNode]`: Gets child nodes via PARENT_OF edges.
-- `graph.parent(node: CpgNode) -> Iterable[CpgNode]`: Gets parent nodes via PARENT_OF edges.
-- `graph.flow_to(node: CpgNode) -> Iterable[CpgNode]`: Gets data flow successors.
-- `graph.flow_from(node: CpgNode) -> Iterable[CpgNode]`: Gets data flow predecessors.
-- `graph.topfile_node(nid: str) -> CpgNode`: Finds the top-level file node.
-
-### **Node Properties (CpgNode)**
-
-- `.id`: Node ID (string).
-- `.name`: Node name.
-- `.type`: Node type.
-- `.code`: Source code content.
-- `.label`: Node label.
-- `.line_num`: Source code line number.
-- `.flags`: List of node flags.
-- `.children_num`: Number of children.
-- `.func_id`: Function ID.
-- `.class_name`: Class name.
-- `.namespace`: Namespace.
-- `.end_num`: End line number.
-- `.comment`: Documentation comment.
-
-### **Edge Properties (CpgEdge)**
-
-- `.id`: Edge ID tuple `(from_node, to_node, edge_type)`.
-- `.start`: Edge start position.
-- `.end`: Edge end position.
-- `.type`: Edge type.
-- `.var`: Variable name (if applicable).
-
----
-
-## **🌟 License**
-
-This project is licensed under the **MIT License**.
-

cpg2py-1.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-cpg2py/__init__.py,sha256=T8Nt4ZLMtCSQjqRINYlYZH9iLiANj3onJqGZk08he4A,2888
-cpg2py/_exceptions.py,sha256=AR2zPeds9fNcCA9iFZGAGluMg3_lgsKHR_4WUmyuD_w,1240
-cpg2py/_logger.py,sha256=HjJAhs4ZAB_IMoBMVRe3KPGS5GRygGy0eNncvIqu8ls,1309
-cpg2py/_abc/__init__.py,sha256=XN7RKxMpnZqvjDAUWxXXLGKY1jrPpKBAxUbq-pydwh4,208
-cpg2py/_abc/edge.py,sha256=CqRz4xmDPplH3lyzRnoWjMj-JgFLFoL8YAJ6XLUsPjA,2571
-cpg2py/_abc/graph.py,sha256=LDF2ylbJYQubUV2LboJlkiQaqWtLW3LsyKBkTJOl4Gs,7795
-cpg2py/_abc/node.py,sha256=s-AQ2oOVtw9wXjBODYtaRKAp8tkPgddMLX2_6eJglcg,1724
-cpg2py/_abc/storage.py,sha256=vUng2nBlhBOJL6YrPTBZaAjkpLdcQLCAW9lOhz7hPxw,6623
-cpg2py/_cpg/__init__.py,sha256=BYNrxYo0G3XoIaUN9llEYkZoCstYJgt88OrJZCkQW7E,126
-cpg2py/_cpg/edge.py,sha256=GcGfwWzQJY0P1GkL8BsQ-vVcsHRlbUp-Le81lPLNt-w,973
-cpg2py/_cpg/graph.py,sha256=Aks2VsDolKdT1NdEz9Vn5ABIWBTPDGvEq7PbrehLVuI,5674
-cpg2py/_cpg/node.py,sha256=hP6jfw9miUyuqksnX9Sr5pz7NYaY4ESigZZ0cmobMcM,1988
-cpg2py-1.1.0.dist-info/LICENSE,sha256=vTjbt7iL1hUilI8E87FoQerEDa9nbpeip26iA6bguHI,1066
-cpg2py-1.1.0.dist-info/METADATA,sha256=VaniBLcK3R1Vp52Iyma3L0NonkN35bH7b41p0H5wJfw,12262
-cpg2py-1.1.0.dist-info/WHEEL,sha256=WnJ8fYhv8N4SYVK2lLYNI6N0kVATA7b0piVUNvqIIJE,91
-cpg2py-1.1.0.dist-info/top_level.txt,sha256=xDY8faKh5Rczvsqb5Jt9Sq-Y7EOImh7jh-m1oVTnH5k,7
-cpg2py-1.1.0.dist-info/RECORD,,