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

cpg2py/abc/storage.py

@@ -1,153 +0,0 @@
-from typing import Optional, Iterable, Dict, Tuple
-
-
-class Storage:
-    """ A directed multi-graph implementation supporting multiple edges between nodes. """
-
-    __NodeID = str
-    __EdgeID = Tuple[str, str, str]
-    __Property = Dict[str, any]
-
-    def __init__(self):
-        """ Initializes an empty directed graph. """
-        self.__nodes = dict()
-        self.__edges = dict() 
-        self.__struct = dict()
-
-    ################################ GRAPH STRUCTURE APIs ################################
-
-    def add_node(self, nid: __NodeID) -> bool:
-        """ Adds a node to the graph. """
-        nid = str(nid)
-        if nid in self.__nodes: return False
-        self.__nodes[nid] = {}
-        self.__struct[nid] = []
-        return True
-    
-    def contains_node(self, nid: __NodeID) -> bool:
-        """ Checks if a node exists in the graph. """
-        nid = str(nid)
-        return nid in self.__nodes
-
-    def add_edge(self, eid: __EdgeID) -> bool:
-        """ Adds a directed edge from `start` to `end` with an optional edge type. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        if eid in self.__edges: return False
-        if eid[0] not in self.__nodes: return False
-        if eid[1] not in self.__nodes: return False
-        self.__edges[eid] = {}
-        self.__struct[eid[0]].append(eid)
-        self.__struct[eid[1]].append(eid)
-        return True
-    
-    def contains_edge(self, eid: __EdgeID) -> bool:
-        """ Checks if an edge exists in the graph. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        return eid in self.__edges
-    
-    def out_edges(self, nid: __NodeID) -> Iterable[__EdgeID]:
-        """ Returns a list of outgoing edges from a given node. """
-        nid = str(nid)
-        return (eid for eid in self.__struct.get(nid) if eid[0] == nid)
-
-    def in_edges(self, nid: __NodeID) -> Iterable[__EdgeID]:
-        """ Returns a list of incoming edges to a given node. """
-        nid = str(nid)
-        return (eid for eid in self.__struct.get(nid) if eid[1] == nid)
-
-    def successors(self, nid: __NodeID) -> Iterable[__NodeID]:
-        """ Returns all successor nodes of a given node. """
-        nid = str(nid)
-        return (eid[1] for eid in self.__struct.get(nid) if eid[0] == nid)
-
-    def predecessors(self, nid: __NodeID) -> Iterable[__NodeID]:
-        """ Returns all predecessor nodes of a given node. """
-        nid = str(nid)
-        return (eid[0] for eid in self.__struct.get(nid) if eid[1] == nid)
-    
-    ################################ GRAPH PROPERTIES APIs ################################
-
-    def set_node_props(self, node: __NodeID, props: __Property) -> bool:
-        """ Sets the properties of a node. """
-        node = str(node)
-        if node not in self.__nodes: return False
-        prev_data: dict = self.__nodes[node]
-        prev_data.update({str(k) : v for k, v in props.items()})
-        return True
-    
-    def get_node_props(self, node: __NodeID) -> Optional[__Property]:
-        """ Returns the properties of a node. """
-        node = str(node)
-        print(self.__nodes)
-        return self.__nodes.get(node, None)
-    
-    def set_node_prop(self, node: __NodeID, key: str, value: any) -> bool:
-        """ Sets the properties of a node. """
-        node, key = str(node), str(key)
-        if node not in self.__nodes: return False
-        self.__nodes[node][key] = value
-        return True
-    
-    def get_node_prop(self, node: __NodeID, key: str) -> Optional[any]:
-        """ Returns the properties of a node. """
-        node, key = str(node), str(key)
-        return self.__nodes.get(node, {}).get(key, None)
-    
-    def set_edge_props(self, eid: __EdgeID, props: __Property) -> bool:
-        """ Sets the properties of an edge. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        if eid not in self.__edges: return False
-        prev_data: dict = self.__edges[eid]
-        prev_data.update({str(k) : v for k, v in props.items()})
-        return True
-    
-    def get_edge_props(self, eid: __EdgeID) -> Optional[__Property]:
-        """ Returns the properties of an edge. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        return self.__edges.get(eid)
-      
-    def set_edge_prop(self, eid: __EdgeID, key: str, value: any) -> bool:
-        """ Sets the properties of an edge. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        key = str(key)
-        if eid not in self.__edges: return False
-        self.__edges[eid][key] = value
-        return
-    
-    def get_edge_prop(self, eid: __EdgeID, key: str) -> Optional[__Property]:
-        """ Returns the properties of an edge. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        key = str(key)
-        return self.__edges.get(eid, {}).get(key, None)
-
-    def __repr__(self):
-        """ Returns a string representation of the graph. """
-        return f"MultiDiGraph(nodes={len(self.nodes)}, edges={len(self.get_edges())})"
-    
-    ################################ GRAPH COMMON APIs ################################
-
-    def get_nodes(self) -> Iterable[__NodeID]:
-        """ Returns a list of all nodes in the graph. """
-        return self.__nodes.keys()
-
-    def get_edges(self) -> Iterable[__EdgeID]:
-        """ Returns a list of all edges in the graph. """
-        return self.__edges.keys()
-    
-    def remove_node(self, nid: __NodeID) -> bool:
-        """ Removes a node from the graph. """
-        nid = str(nid)
-        if nid not in self.__nodes: return False
-        self.__nodes.pop(nid)
-        for eid in self.__struct[nid]:
-            self.__edges.pop(eid)
-        return True
-    
-    def remove_edge(self, eid: __EdgeID) -> bool:
-        """ Removes an edge from the graph. """
-        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
-        if eid not in self.__edges: return False
-        self.__struct[eid[0]].remove(eid)
-        self.__struct[eid[1]].remove(eid)
-        self.__edges.pop(eid)
-        return True

cpg2py/cpg/__init__.py

@@ -1,3 +0,0 @@
-from .graph import _Graph
-
-__all__ = ['_Graph']

cpg2py/cpg/edge.py

@@ -1,31 +0,0 @@
-from __future__ import annotations
-from typing import Optional, Tuple
-from ..abc import AbcGraphQuerier, AbcEdgeQuerier
-
-class _Edge(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)
-        return None
-    
-    @property
-    def id(self) -> Tuple[str, str, str]: 
-        return self.edge_id
-
-    @property
-    def start(self) -> Optional[int]:
-        start_str = str(self.get_property('start', 'start:START_ID'))
-        return int(start_str) if start_str.isnumeric() else int(self.__from_id)
-
-    @property
-    def end(self) -> Optional[int]: 
-        end_str = str(self.get_property('end', 'end:END_ID'))
-        return int(end_str) if end_str.isnumeric() else int(self.__to_id) 
-
-    @property
-    def type(self) -> Optional[str]: 
-        return self.get_property('type', 'type:TYPE')
-    
-    @property
-    def var(self) -> Optional[str]: 
-        return self.get_property('var')

cpg2py/cpg/graph.py

@@ -1,97 +0,0 @@
-
-from __future__ import annotations
-
-from .edge import _Edge
-from .node import _Node
-from ..abc import AbcGraphQuerier, Storage 
-
-from typing import Callable, Iterable, Optional
-import json, functools
-
-class _Graph(AbcGraphQuerier): 
-    '''
-    OPG is Object Property Diagram used by ODgen and FAST
-    '''
-    __EdgeCondition = Callable[[_Edge], bool]
-    __always_true = lambda _: True
-
-    def __init__(self, target: Storage) -> None:
-        super().__init__(target)
-        return None
-
-    def node(self, whose_id_is: str) -> Optional[_Node]:
-        try: 
-            return _Node(self.storage, whose_id_is)
-        except Exception as e: print(
-            f'✘ {_Graph} ERROR:'
-            f'Cannot find node with id {whose_id_is}.'
-            f'(exception is {e})'
-        )
-        return None
-    
-    def edge(self, fid: str, tid: str, eid:str) -> Optional[_Edge]: 
-        try: 
-            return _Edge(self.storage, fid, tid, eid)
-        except Exception as e: print(
-            f'✘ {_Graph} ERROR:'
-            f'Cannot find edge from {fid} to {tid}, and eid is {str(eid)}.'
-            f'(exception is {e})'
-        )
-        return None
-    
-    @functools.lru_cache()
-    def topfile_node(self, of_nid: str) -> _Node: 
-        '''
-        find the top file node from the input node.
-        '''
-        of_node = self.node(of_nid)
-        if of_node.type == "File": return of_node
-        if 'TOPLEVEL_FILE' in of_node.flags: return of_node
-        parents = self.prev(of_node, lambda e: e.type in ["PARENT_OF", "ENTRY", "EXIT"])
-        for pre in parents: 
-            top_file = self.topfile_node(pre.id)
-            if top_file is not None: return top_file
-        raise Exception(f'❌ INNER ERROR(500): CANNOT FIND THE TOPFILE.')
-    
-    def succ(self, of: _Node, who_satisifies: __EdgeCondition = __always_true) -> Iterable[_Node]: 
-        '''
-        return the next nodes connected with the input one.
-        '''
-        return super().succ(of.id, who_satisifies)
-    
-    def prev(self, of, who_satisifies = __always_true) -> Iterable[_Node]:
-        '''
-        return the previous nodes connected with the input one.
-        '''
-        return super().prev(of, who_satisifies)
-
-
-    def children(self, of: _Node, extra: __EdgeCondition = __always_true) -> Iterable[_Node]: 
-        '''
-        return the next nodes connected with the input one.
-        The edge type between them is PARENT_OF 
-        '''
-        return self.succ(of, lambda e: extra(e) and (e.type == "PARENT_OF"))
-
-    def parent(self, of: _Node, extra:__EdgeCondition = __always_true) -> Iterable[_Node]: 
-        '''
-        return the prev nodes connected with the input one.
-        The edge type between them is PARENT_OF 
-        '''
-        return self.prev(of, lambda e: extra(e) and (e.type == "PARENT_OF"))
-
-    def flow_to(self, of: _Node, extra: __EdgeCondition = __always_true) -> Iterable[_Node]: 
-        '''
-        return the next nodes connected with the input one.
-        The edge type between them is FLOW_TO 
-        '''
-        return self.succ(of, lambda e: extra(e) and (e.type == "FLOWS_TO"))
-
-    def flow_from(self, of: _Node, extra: __EdgeCondition = __always_true) -> Iterable[_Node]:
-        '''
-        return the previous nodes connected with the input one.
-        The edge type between them is FLOW_TO 
-        '''
-        return self.prev(of, lambda e: extra(e) and (e.type == "FLOWS_TO"))
-    
-pass

cpg2py/cpg/node.py

@@ -1,65 +0,0 @@
-from __future__ import annotations
-from typing import List, Optional
-
-from ..abc import AbcNodeQuerier, AbcGraphQuerier
-
-class _Node(AbcNodeQuerier):  
-    
-    def __init__(self, graph: AbcGraphQuerier, nid: str) -> None:
-        super().__init__(graph, nid)
-        return None
-    
-    @property
-    def id(self) -> str: return self.node_id
-
-    @property
-    def code(self) -> Optional[str]: 
-        return self.get_property('code')
-    
-    @property
-    def label(self) -> Optional[str]: 
-        return self.get_property('labels:label', 'labels')
-    
-    @property
-    def flags(self) -> List[str]: 
-        flags_str = self.get_property('flags:string_array', 'flags:string[]', 'flags')
-        return str(flags_str).split(' ') if flags_str is not None else []
-    
-    @property
-    def line_num(self) -> Optional[int]: 
-        linenum_str = str(self.get_property('lineno:int', 'lineno'))
-        return int(linenum_str) if linenum_str.isnumeric() else None
-    
-    @property
-    def children_num(self) -> Optional[int]: 
-        num_str = str(self.get_property('childnum:int', 'childnum'))
-        return int(num_str) if num_str.isnumeric() else None
-
-    @property
-    def func_id(self) -> Optional[int]: 
-        fid_str = str(self.get_property('funcid:int', 'funcid'))
-        return int(fid_str) if fid_str.isnumeric() else None
-    
-    @property
-    def class_name(self) -> Optional[str]: 
-        return self.get_property('classname')
-
-    @property
-    def namespace(self) -> Optional[str]: 
-        return self.get_property('namespace')
-        
-    @property
-    def name(self) -> Optional[str]: return self.get_property('name')
-
-    @property
-    def end_num(self) -> Optional[int]:
-        end_str = str(self.get_property('endlineno:int', 'endlineno'))
-        return int(end_str) if end_str.isnumeric() else None
-
-    @property
-    def comment(self) -> Optional[str]: 
-        return self.get_property('doccomment')
-
-    @property 
-    def type(self) -> Optional[str]: 
-        return self.get_property('type')

cpg2py-1.0.4.dist-info/METADATA

@@ -1,261 +0,0 @@
-Metadata-Version: 2.2
-Name: cpg2py
-Version: 1.0.4
-Summary: A graph-based data structure designed for querying CSV files in Joern format in Python
-Home-page: https://github.com/YichaoXu/cpg2py
-Author: Yichao Xu
-Author-email: Yichao Xu <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
-Keywords: Joern,CPG,Graph,CSV
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: author
-Dynamic: home-page
-Dynamic: requires-python
-
-# **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.
-- **Extensible Abstract Base Classes (ABC)**:
-  - `AbcGraphQuerier` for implementing **custom graph queries**.
-  - `AbcNodeQuerier` for interacting with **nodes**.
-  - `AbcEdgeQuerier` for interacting with **edges**.
-- **Built-in Query Mechanisms**:
-  - **Retrieve all edges**.
-  - **Get incoming (**``**) and outgoing (**``**) edges of a node**.
-  - **Find successors (**``**) and predecessors (**``**)**.
-  - **Traverse AST, Control Flow, and Data Flow Graphs**.
-
----
-
-## **📚 Installation**
-
-To install the package, use:
-
-```bash
-pip install git+https://github.com/YichaoXu/cpg2py.git
-```
-
-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
-````
-
----
-
-## **📚 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")
-```
-
----
-
-### **2️⃣ Query Nodes & Edges**
-
-```python
-# Get a specific node
-node = graph.node("2")
-print(node.name, node.type)  # Example output: "/tmp/example.php" AST_TOPLEVEL
-
-# Get a specific edge
-edge = 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)
-
-# 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)
-```
-
----
-
-### **4️⃣ AST and Flow Queries**
-
-```python
-# Get top-level file node for a given node
-top_file = 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])
-
-# Get data flow successors
-flow_successors = graph.flow_to(node)
-print([succ.id for succ in flow_successors])
-```
-
----
-
-## **🛠 Abstract Base Classes (ABC)**
-
-The following abstract base classes (`ABC`) provide interfaces for extending **node**, **edge**, and **graph** querying behavior.
-
----
-
-### **🔹 AbcNodeQuerier (Abstract Node Interface)**
-
-This class defines how nodes interact with the graph storage.
-
-```python
-from cpg2py.abc import AbcNodeQuerier
-
-class MyNodeQuerier(AbcNodeQuerier):
-    def __init__(self, graph, nid):
-        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.abc import AbcEdgeQuerier
-
-class MyEdgeQuerier(AbcEdgeQuerier):
-    def __init__(self, graph, f_nid, t_nid, e_type):
-        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.
-
-```python
-from cpg2py.abc import AbcGraphQuerier
-
-class MyGraphQuerier(AbcGraphQuerier):
-    def node(self, nid: str):
-        return MyNodeQuerier(self.storage, nid)
-
-    def edge(self, fid, tid, eid):
-        return MyEdgeQuerier(self.storage, fid, tid, eid)
-```
-
----
-
-## **🔍 Querying The Graph**
-
-After implementing the abstract classes, you can perform advanced queries:
-
-```python
-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"
-```
-
----
-
-## **🐝 API Reference**
-
-For a more detail APIs document please see our [APIs doc](docs/APIs.md) 
-
-- **Graph Functions**:
-  - `cpg_graph(node_csv, edge_csv)`: Loads graph from CSV files.
-  - `graph.node(nid)`: Retrieves a node by ID.
-  - `graph.edge(fid, tid, eid)`: Retrieves an edge.
-  - `graph.succ(node)`: Gets successor nodes.
-  - `graph.prev(node)`: Gets predecessor nodes.
-- **Node Properties**:
-  - `.name`: Node name.
-  - `.type`: Node type.
-  - `.line_num`: Source code line number.
-- **Edge Properties**:
-  - `.start`: Edge start node.
-  - `.end`: Edge end node.
-  - `.type`: Edge type.
-
----
-
-## **🌟 License**
-
-This project is licensed under the **MIT License**.
-

cpg2py-1.0.4.dist-info/RECORD

@@ -1,15 +0,0 @@
-cpg2py/__init__.py,sha256=4GXaMrMxlqWKpjrwAZlSwBCG-9_osMeChuFS-WRqtKg,1918
-cpg2py/abc/__init__.py,sha256=HgDXsJkGcPQvr6ac3hMrUU9TuQibMaP7-oXbXLs_iLI,207
-cpg2py/abc/edge.py,sha256=zLlRebDKT2qK5XOJq23_UUCESgGsvgalbXdx_uUcKks,1240
-cpg2py/abc/graph.py,sha256=DbeHN6qsNaqcqL9cUquJWC16BihDxy1MEhyuL-qVMBI,3902
-cpg2py/abc/node.py,sha256=E2EQv_KisEPuslFaglZZvSBm-VY5LYCFBOFY1yiPzDY,844
-cpg2py/abc/storage.py,sha256=BF82Vs_7FxGYSPiM_6JwQVzmaqMzGy2r-WSk8pQQclY,5976
-cpg2py/cpg/__init__.py,sha256=fO59Yd7OISyxdjdZDJ5zFM41r4cYKawOsvpqV4gWrGM,48
-cpg2py/cpg/edge.py,sha256=brG7cQl7tjihbUCBYyjNUnMLsKIif-XQc_TFdGz8ZYo,1007
-cpg2py/cpg/graph.py,sha256=n4EjAhhjzl0XRJBwlAmK5AcSrECiqhjA6dXt2Ucf7IM,3448
-cpg2py/cpg/node.py,sha256=-2xl8c-eSbe4Kv4xPAEf6POlCYOV4j0voxJAKDZj3Cc,2037
-cpg2py-1.0.4.dist-info/LICENSE,sha256=vTjbt7iL1hUilI8E87FoQerEDa9nbpeip26iA6bguHI,1066
-cpg2py-1.0.4.dist-info/METADATA,sha256=Xhx-JFz1RECxW-aLxPhfy4elJgFoaTjxxiXR28YD-c8,7077
-cpg2py-1.0.4.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-cpg2py-1.0.4.dist-info/top_level.txt,sha256=xDY8faKh5Rczvsqb5Jt9Sq-Y7EOImh7jh-m1oVTnH5k,7
-cpg2py-1.0.4.dist-info/RECORD,,