coffy 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

coffy/__init__.py

@@ -1,2 +1,2 @@
 # coffy/__init__.py
-# author: nsarathy
+# author: nsarathy

coffy/graph/__init__.py

@@ -1,4 +1,6 @@
 # coffy/graph/__init__.py
 # author: nsarathy
 
-from .graphdb_nx import GraphDB
+from .graphdb_nx import GraphDB as GraphDB
+
+__all__ = ["GraphDB"]

coffy/graph/graphdb_nx.py

@@ -1,13 +1,28 @@
 # coffy/graph/graphdb_nx.py
 # author: nsarathy
 
-import networkx as nx
+"""
+A simple graph database using NetworkX.
+"""
+
 import json
+import networkx as nx
 import os
 
+
 class GraphDB:
+    """
+    A class to represent a graph database.
+    """
 
     def __init__(self, directed=False, path=None):
+        """
+        Initialize a GraphDB instance.
+        directed -- Whether the graph is directed or not.
+        path -- Path to the JSON file where the graph will be stored.
+            If path is ":memory:" or None, the graph will be in-memory only.
+            If path is provided, it must end with ".json".
+        """
         self.g = nx.DiGraph() if directed else nx.Graph()
         self.directed = directed
         self.in_memory = path == ":memory:"
@@ -24,89 +39,186 @@ class GraphDB:
             os.makedirs(os.path.dirname(self.path), exist_ok=True)
             self.save(self.path)
 
-
     # Node operations
+
     def add_node(self, node_id, labels=None, **attrs):
+        """
+        Add a node to the graph.
+        node_id -- Unique identifier for the node.
+        labels -- Optional list of labels for the node.
+        attrs -- Additional attributes for the node.
+        """
+        if self.has_node(node_id):
+            raise KeyError(
+                f"Node '{node_id}' already exists. Use update_node to modify it."
+            )
         if labels is not None:
             attrs["_labels"] = labels if isinstance(labels, list) else [labels]
         self.g.add_node(node_id, **attrs)
         self._persist()
 
     def add_nodes(self, nodes):
+        """
+        Add multiple nodes to the graph.
+        nodes -- List of dictionaries, each representing a node.
+        """
         for node in nodes:
             node_id = node["id"]
             labels = node.get("labels") or node.get("_labels")  # Accept either form
-            attrs = {k: v for k, v in node.items() if k not in ["id", "labels", "_labels"]}
+            attrs = {
+                k: v for k, v in node.items() if k not in ["id", "labels", "_labels"]
+            }
             self.add_node(node_id, labels=labels, **attrs)
 
     def get_node(self, node_id):
+        """
+        Get a node from the graph.
+        node_id -- Unique identifier for the node.
+        Returns the node's attributes as a dictionary.
+        """
         return self.g.nodes[node_id]
 
     def _get_neighbors(self, node_id, direction):
+        """
+        Get the neighbors of a node in the graph.
+        node_id -- Unique identifier for the node.
+        direction -- Direction of the neighbors to retrieve ('in', 'out', or 'any').
+        Returns a set of neighbor node IDs.
+        """
         if self.directed:
             if direction == "out":
                 return self.g.successors(node_id)
             elif direction == "in":
                 return self.g.predecessors(node_id)
             elif direction == "any":
-                return set(self.g.successors(node_id)).union(self.g.predecessors(node_id))
+                return set(self.g.successors(node_id)).union(
+                    self.g.predecessors(node_id)
+                )
             else:
                 raise ValueError("Direction must be 'in', 'out', or 'any'")
         else:
             return self.g.neighbors(node_id)
 
     def remove_node(self, node_id):
+        """
+        Remove a node from the graph.
+        node_id -- Unique identifier for the node.
+        """
         self.g.remove_node(node_id)
         self._persist()
 
     # Relationship (edge) operations
     def add_relationship(self, source, target, rel_type=None, **attrs):
+        """
+        Add a relationship (edge) to the graph.
+        source -- Unique identifier for the source node.
+        target -- Unique identifier for the target node.
+        rel_type -- Optional type of the relationship.
+        attrs -- Additional attributes for the relationship.
+        """
         if rel_type:
             attrs["_type"] = rel_type
         self.g.add_edge(source, target, **attrs)
         self._persist()
 
     def add_relationships(self, relationships):
+        """
+        Add multiple relationships to the graph.
+        relationships -- List of dictionaries, each representing a relationship.
+        """
         for rel in relationships:
             source = rel["source"]
             target = rel["target"]
             rel_type = rel.get("type") or rel.get("_type")
-            attrs = {k: v for k, v in rel.items() if k not in ["source", "target", "type", "_type"]}
+            attrs = {
+                k: v
+                for k, v in rel.items()
+                if k not in ["source", "target", "type", "_type"]
+            }
             self.add_relationship(source, target, rel_type=rel_type, **attrs)
 
     def get_relationship(self, source, target):
+        """
+        Get a relationship (edge) from the graph.
+        source -- Unique identifier for the source node.
+        target -- Unique identifier for the target node.
+        Returns the relationship's attributes as a dictionary.
+        """
         return self.g.get_edge_data(source, target)
 
     def remove_relationship(self, source, target):
+        """
+        Remove a relationship (edge) from the graph.
+        source -- Unique identifier for the source node.
+        target -- Unique identifier for the target node.
+        """
         self.g.remove_edge(source, target)
         self._persist()
 
     # Basic queries
     def neighbors(self, node_id):
+        """
+        Get the neighbors of a node.
+        node_id -- Unique identifier for the node.
+        Returns a list of neighbor node IDs.
+        """
         return list(self.g.neighbors(node_id))
 
     def degree(self, node_id):
+        """
+        Get the degree of a node.
+        node_id -- Unique identifier for the node.
+        Returns the degree of the node (number of edges connected to it).
+        """
         return self.g.degree[node_id]
 
     def has_node(self, node_id):
+        """
+        Check if a node exists in the graph.
+        node_id -- Unique identifier for the node.
+        Returns True if the node exists, False otherwise.
+        """
         return self.g.has_node(node_id)
 
     def has_relationship(self, u, v):
+        """
+        Check if a relationship (edge) exists in the graph.
+        u -- Unique identifier for the source node.
+        v -- Unique identifier for the target node.
+        Returns True if the relationship exists, False otherwise.
+        """
         return self.g.has_edge(u, v)
-    
+
     def update_node(self, node_id, **attrs):
+        """
+        Update attributes of a node.
+        node_id -- Unique identifier for the node.
+        attrs -- Attributes to update.
+        """
         if not self.has_node(node_id):
             raise KeyError(f"Node '{node_id}' does not exist.")
         self.g.nodes[node_id].update(attrs)
         self._persist()
 
     def update_relationship(self, source, target, **attrs):
+        """
+        Update attributes of a relationship (edge).
+        source -- Unique identifier for the source node.
+        target -- Unique identifier for the target node.
+        attrs -- Attributes to update.
+        """
         if not self.has_relationship(source, target):
             raise KeyError(f"Relationship '{source}->{target}' does not exist.")
         self.g.edges[source, target].update(attrs)
         self._persist()
 
     def set_node(self, node_id, labels=None, **attrs):
+        """
+        Set or update a node in the graph.
+        node_id -- Unique identifier for the node.
+        labels -- Optional list of labels for the node.
+        attrs -- Attributes to set or update.
+        """
         if self.has_node(node_id):
             self.update_node(node_id, **attrs)
         else:
@@ -115,6 +227,13 @@ class GraphDB:
 
     # Advanced node search
     def project_node(self, node_id, fields=None):
+        """
+        Project a node's attributes.
+        node_id -- Unique identifier for the node.
+        fields -- Optional list of fields to include in the projection.
+        Returns the node's attributes as a dictionary.
+            If fields is None, all attributes are included.
+        """
         if not self.has_node(node_id):
             return None
         node = self.get_node(node_id).copy()
@@ -124,6 +243,14 @@ class GraphDB:
         return {k: node[k] for k in fields if k in node}
 
     def project_relationship(self, source, target, fields=None):
+        """
+        Project a relationship's attributes.
+        source -- Unique identifier for the source node.
+        target -- Unique identifier for the target node.
+        fields -- Optional list of fields to include in the projection.
+        Returns the relationship's attributes as a dictionary.
+            If fields is None, all attributes are included.
+        """
         if not self.has_relationship(source, target):
             return None
         rel = self.get_relationship(source, target).copy()
@@ -133,30 +260,72 @@ class GraphDB:
         return {k: rel[k] for k in fields if k in rel}
 
     def find_nodes(self, label=None, fields=None, **conditions):
+        """
+        Find nodes in the graph based on conditions.
+        label -- Optional label to filter nodes by.
+        fields -- Optional list of fields to include in the projection.
+        conditions -- Conditions to filter nodes by.
+        Returns a list of nodes that match the conditions.
+            Each node is projected using the specified fields.
+        """
         return [
-            self.project_node(n, fields) for n, a in self.g.nodes(data=True)
-            if (label is None or label in a.get("_labels", [])) and self._match_conditions(a, conditions)
+            self.project_node(n, fields)
+            for n, a in self.g.nodes(data=True)
+            if (label is None or label in a.get("_labels", []))
+            and self._match_conditions(a, conditions)
         ]
 
     def find_by_label(self, label, fields=None):
+        """
+        Find nodes by label.
+        label -- Label to filter nodes by.
+        fields -- Optional list of fields to include in the projection.
+        Returns a list of nodes that have the specified label.
+            Each node is projected using the specified fields.
+        """
         return [
-            self.project_node(n, fields) for n, a in self.g.nodes(data=True)
+            self.project_node(n, fields)
+            for n, a in self.g.nodes(data=True)
             if label in a.get("_labels", [])
         ]
 
     def find_relationships(self, rel_type=None, fields=None, **conditions):
+        """
+        Find relationships in the graph based on conditions.
+        rel_type -- Optional type of the relationship to filter by.
+        fields -- Optional list of fields to include in the projection.
+        conditions -- Conditions to filter relationships by.
+        Returns a list of relationships that match the conditions.
+            Each relationship is projected using the specified fields.
+        """
         return [
-            self.project_relationship(u, v, fields) for u, v, a in self.g.edges(data=True)
-            if (rel_type is None or a.get("_type") == rel_type) and self._match_conditions(a, conditions)
+            self.project_relationship(u, v, fields)
+            for u, v, a in self.g.edges(data=True)
+            if (rel_type is None or a.get("_type") == rel_type)
+            and self._match_conditions(a, conditions)
         ]
 
     def find_by_relationship_type(self, rel_type, fields=None):
+        """
+        Find relationships by type.
+        rel_type -- Type of the relationship to filter by.
+        fields -- Optional list of fields to include in the projection.
+        Returns a list of relationships that have the specified type.
+            Each relationship is projected using the specified fields.
+        """
         return [
-            self.project_relationship(u, v, fields) for u, v, a in self.g.edges(data=True)
+            self.project_relationship(u, v, fields)
+            for u, v, a in self.g.edges(data=True)
             if a.get("_type") == rel_type
         ]
 
     def _match_conditions(self, attrs, conditions):
+        """
+        Check if the attributes match the given conditions.
+        attrs -- Attributes of the node or relationship.
+        conditions -- Conditions to match against.
+        Returns True if all conditions are met, False otherwise.
+        """
         if not conditions:
             return True
         logic = conditions.get("_logic", "and")
@@ -167,13 +336,20 @@ class GraphDB:
             actual = attrs.get(key)
             if isinstance(expected, dict):
                 for op, val in expected.items():
-                    if op == "gt": results.append(actual > val)
-                    elif op == "lt": results.append(actual < val)
-                    elif op == "gte": results.append(actual >= val)
-                    elif op == "lte": results.append(actual <= val)
-                    elif op == "ne": results.append(actual != val)
-                    elif op == "eq": results.append(actual == val)
-                    else: results.append(False)
+                    if op == "gt":
+                        results.append(actual > val)
+                    elif op == "lt":
+                        results.append(actual < val)
+                    elif op == "gte":
+                        results.append(actual >= val)
+                    elif op == "lte":
+                        results.append(actual <= val)
+                    elif op == "ne":
+                        results.append(actual != val)
+                    elif op == "eq":
+                        results.append(actual == val)
+                    else:
+                        results.append(False)
             else:
                 results.append(actual == expected)
 
@@ -182,8 +358,19 @@ class GraphDB:
         elif logic == "not":
             return not all(results)
         return all(results)
-    
-    def match_node_path(self, start, pattern, return_nodes=True, node_fields=None, direction="out"):
+
+    def match_node_path(
+        self, start, pattern, return_nodes=True, node_fields=None, direction="out"
+    ):
+        """
+        Match a path in the graph starting from a node.
+        start -- Starting node conditions (e.g., {"name": "Alice"}).
+        pattern -- Pattern to match, a list of dictionaries with "rel_type" and "node" keys.
+        return_nodes -- Whether to return the nodes in the path.
+        node_fields -- Optional list of fields to include in the projected nodes.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        Returns a list of paths, where each path is a list of node IDs.
+        """
         start_nodes = self.find_nodes(**start)
         node_paths = []
 
@@ -193,7 +380,7 @@ class GraphDB:
                 pattern=pattern,
                 node_path=[s["id"]],
                 node_paths=node_paths,
-                direction=direction
+                direction=direction,
             )
 
         unique_paths = list({tuple(p) for p in node_paths})
@@ -205,8 +392,15 @@ class GraphDB:
             ]
         return unique_paths
 
-
     def _match_node_path(self, current_id, pattern, node_path, node_paths, direction):
+        """
+        Recursive helper function to match a node path.
+        current_id -- Current node ID.
+        pattern -- Pattern to match.
+        node_path -- Current path of node IDs.
+        node_paths -- List to collect all matching node paths.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        """
         if not pattern:
             node_paths.append(node_path)
             return
@@ -224,9 +418,21 @@ class GraphDB:
                 continue
             if neighbor in node_path:  # avoid cycles
                 continue
-            self._match_node_path(neighbor, pattern[1:], node_path + [neighbor], node_paths, direction)
-    
-    def match_full_path(self, start, pattern, node_fields=None, rel_fields=None, direction="out"):
+            self._match_node_path(
+                neighbor, pattern[1:], node_path + [neighbor], node_paths, direction
+            )
+
+    def match_full_path(
+        self, start, pattern, node_fields=None, rel_fields=None, direction="out"
+    ):
+        """
+        Match a full path in the graph starting from a node.
+        start -- Starting node conditions (e.g., {"name": "Alice"}).
+        pattern -- Pattern to match, a list of dictionaries with "rel_type" and "node" keys.
+        node_fields -- Optional list of fields to include in the projected nodes.
+        rel_fields -- Optional list of fields to include in the projected relationships.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        """
         start_nodes = self.find_nodes(**start)
         matched_paths = []
 
@@ -237,18 +443,37 @@ class GraphDB:
                 relationship_path=[],
                 node_path=[s["id"]],
                 matched_paths=matched_paths,
-                direction=direction
+                direction=direction,
             )
 
         return [
             {
                 "nodes": [self.project_node(n, node_fields) for n in nodes],
-                "relationships": [self.project_relationship(u, v, rel_fields) for u, v in path]
+                "relationships": [
+                    self.project_relationship(u, v, rel_fields) for u, v in path
+                ],
             }
             for path, nodes in matched_paths
         ]
 
-    def _match_full_path(self, current_id, pattern, relationship_path, node_path, matched_paths, direction):
+    def _match_full_path(
+        self,
+        current_id,
+        pattern,
+        relationship_path,
+        node_path,
+        matched_paths,
+        direction,
+    ):
+        """
+        Recursive helper function to match a full path.
+        current_id -- Current node ID.
+        pattern -- Pattern to match.
+        relationship_path -- Current path of relationships.
+        node_path -- Current path of node IDs.
+        matched_paths -- List to collect all matching paths.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        """
         if not pattern:
             matched_paths.append((relationship_path, node_path))
             return
@@ -272,10 +497,20 @@ class GraphDB:
                 relationship_path + [(current_id, neighbor)],
                 node_path + [neighbor],
                 matched_paths,
-                direction
+                direction,
             )
-            
-    def match_path_structured(self, start, pattern, node_fields=None, rel_fields=None, direction="out"):
+
+    def match_path_structured(
+        self, start, pattern, node_fields=None, rel_fields=None, direction="out"
+    ):
+        """
+        Match a structured path in the graph starting from a node.
+        start -- Starting node conditions (e.g., {"name": "Alice"}).
+        pattern -- Pattern to match, a list of dictionaries with "rel_type" and "node" keys.
+        node_fields -- Optional list of fields to include in the projected nodes.
+        rel_fields -- Optional list of fields to include in the projected relationships.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        """
         start_nodes = self.find_nodes(**start)
         structured_paths = []
 
@@ -285,12 +520,22 @@ class GraphDB:
                 pattern=pattern,
                 path=[{"node": self.project_node(s["id"], node_fields)}],
                 structured_paths=structured_paths,
-                direction=direction
+                direction=direction,
             )
 
         return structured_paths
-    
-    def _match_structured_path(self, current_id, pattern, path, structured_paths, direction):
+
+    def _match_structured_path(
+        self, current_id, pattern, path, structured_paths, direction
+    ):
+        """
+        Recursive helper function to match a structured path.
+        current_id -- Current node ID.
+        pattern -- Pattern to match.
+        path -- Current structured path.
+        structured_paths -- List to collect all matching structured paths.
+        direction -- Direction of the search ('in', 'out', or 'any').
+        """
         if not pattern:
             structured_paths.append({"path": path})
             return
@@ -311,39 +556,58 @@ class GraphDB:
 
             extended_path = path + [
                 {"relationship": self.project_relationship(current_id, neighbor)},
-                {"node": self.project_node(neighbor)}
+                {"node": self.project_node(neighbor)},
             ]
 
             self._match_structured_path(
-                neighbor,
-                pattern[1:],
-                extended_path,
-                structured_paths,
-                direction
+                neighbor, pattern[1:], extended_path, structured_paths, direction
             )
 
     # Export
     def nodes(self):
-        return [{"id": n, "labels": a.get("_labels", []), **{k: v for k, v in a.items() if k != "_labels"}} for n, a in self.g.nodes(data=True)]
+        """
+        Get all nodes in the graph.
+        Returns a list of dictionaries with node IDs, labels, and attributes.
+        """
+        return [
+            {
+                "id": n,
+                "labels": a.get("_labels", []),
+                **{k: v for k, v in a.items() if k != "_labels"},
+            }
+            for n, a in self.g.nodes(data=True)
+        ]
 
     def relationships(self):
+        """
+        Get all relationships in the graph.
+        Returns a list of dictionaries with source, target, type, and attributes.
+        """
         return [
             {
                 "source": u,
                 "target": v,
                 "type": a.get("_type"),
-                **{k: v for k, v in a.items() if k != "_type"}
+                **{k: v for k, v in a.items() if k != "_type"},
             }
             for u, v, a in self.g.edges(data=True)
         ]
 
     def to_dict(self):
-        return {
-            "nodes": self.nodes(),
-            "relationships": self.relationships()
-        }
+        """
+        Convert the graph to a dictionary representation.
+        Returns a dictionary with "nodes" and "relationships" keys.
+            Each key contains a list of nodes or relationships, respectively.
+        """
+        return {"nodes": self.nodes(), "relationships": self.relationships()}
 
     def save(self, path=None):
+        """
+        Save the graph to a file.
+        path -- Path to the file where the graph will be saved.
+            If path is None, it will use the instance's path.
+            If path is not specified, it will raise a ValueError.
+        """
         path = path or self.path
         if not path:
             raise ValueError("No path specified to save the graph.")
@@ -351,6 +615,12 @@ class GraphDB:
             json.dump(self.to_dict(), f, indent=4)
 
     def load(self, path=None):
+        """
+        Load the graph from a file.
+        path -- Path to the file from which the graph will be loaded.
+            If path is None, it will use the instance's path.
+            If path is not specified, it will raise a ValueError.
+        """
         path = path or self.path
         if not path:
             raise ValueError("No path specified to load the graph.")
@@ -363,17 +633,31 @@ class GraphDB:
             self.add_node(node["id"], **{k: v for k, v in node.items() if k != "id"})
         for rel in data.get("relationships", []):
             self.add_relationship(
-                rel["source"], rel["target"],
+                rel["source"],
+                rel["target"],
                 rel_type=rel.get("type") or rel.get("_type"),
-                **{k: v for k, v in rel.items() if k not in ["source", "target", "type", "_type"]}
+                **{
+                    k: v
+                    for k, v in rel.items()
+                    if k not in ["source", "target", "type", "_type"]
+                },
             )
-    
+
     def save_query_result(self, result, path=None):
+        """
+        Save the result of a query to a file.
+        result -- Result of the query, typically a list of nodes or relationships.
+        path -- Path to the file where the result will be saved.
+            If path is None, it will raise a ValueError.
+        """
         if path is None:
             raise ValueError("No path specified to save the query result.")
         with open(path, "w", encoding="utf-8") as f:
             json.dump(result, f, indent=4)
-            
+
     def _persist(self):
+        """
+        Persist changes to the graph to the file if not in memory.
+        """
         if not self.in_memory:
             self.save(self.path)

coffy/nosql/__init__.py

@@ -3,5 +3,9 @@
 
 from .engine import CollectionManager
 
+
 def db(collection_name: str, path: str = None):
     return CollectionManager(collection_name, path=path)
+
+
+__all__ = ["db", "CollectionManager"]