falkordb 1.0.0a0__tar.gz

falkordb-1.0.0a0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.1
+Name: FalkorDB
+Version: 1.0.0a0
+Summary: Python client for interacting with FalkorDB database
+Home-page: http://falkordb-py.readthedocs.io
+Keywords: FalkorDB,GraphDB,Cypher
+Author: FalkorDB inc
+Author-email: info@falkordb.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: redis (>=5.0.1,<6.0.0)
+Project-URL: Repository, http://github.com/falkorDB/falkordb-py
+Description-Content-Type: text/markdown
+
+# FalkorDB
+
+FalkorDB python client
+
+see [docs](http://falkordb-py.readthedocs.io/)
+
+## Installation
+```sh
+pip install FalkorDB
+```
+
+## Usage
+
+### Run FalkorDB instance
+Docker:
+```sh
+docker run --rm -p 6379:6379 falkordb/falkordb
+```
+Or use our [sandbox](https://cloud.falkordb.com/sandbox)
+
+### Example 
+```python
+from falkordb import FalkorDB
+
+# Connect to FalkorDB
+db = FalkorDB(host='localhost', port=6379)
+
+# Select the social graph
+g = db.select_graph('social')
+
+# Create 100 nodes and return a handful
+nodes = g.query('UNWIND range(0, 100) AS i CREATE (n {v:1}) RETURN n LIMIT 10').result_set
+for n in nodes:
+    print(n)
+```
+

falkordb-1.0.0a0/README.md

@@ -0,0 +1,35 @@
+# FalkorDB
+
+FalkorDB python client
+
+see [docs](http://falkordb-py.readthedocs.io/)
+
+## Installation
+```sh
+pip install FalkorDB
+```
+
+## Usage
+
+### Run FalkorDB instance
+Docker:
+```sh
+docker run --rm -p 6379:6379 falkordb/falkordb
+```
+Or use our [sandbox](https://cloud.falkordb.com/sandbox)
+
+### Example 
+```python
+from falkordb import FalkorDB
+
+# Connect to FalkorDB
+db = FalkorDB(host='localhost', port=6379)
+
+# Select the social graph
+g = db.select_graph('social')
+
+# Create 100 nodes and return a handful
+nodes = g.query('UNWIND range(0, 100) AS i CREATE (n {v:1}) RETURN n LIMIT 10').result_set
+for n in nodes:
+    print(n)
+```

falkordb-1.0.0a0/falkordb/__init__.py

@@ -0,0 +1,6 @@
+from .falkordb       import FalkorDB
+from .node           import Node
+from .edge           import Edge
+from .path           import Path
+from .graph          import Graph
+from .execution_plan import ExecutionPlan, Operation

falkordb-1.0.0a0/falkordb/edge.py

@@ -0,0 +1,127 @@
+from typing import Optional
+from .node import Node
+from .helpers import quote_string
+
+class Edge:
+    """
+    An edge connecting two nodes.
+    """
+
+    def __init__(self, src_node: Node, relation: str, dest_node: Node,
+                 edge_id: Optional[int] = None, alias: Optional[str] = '',
+                 properties=None):
+        """
+        Create a new edge.
+
+        Args:
+            src_node: The source node of the edge.
+            relation: The relationship type of the edge.
+            dest_node: The destination node of the edge.
+            edge_id: The ID of the edge.
+            alias: An alias for the edge (default is empty string).
+            properties: The properties of the edge.
+
+        Raises:
+            AssertionError: If either src_node or dest_node is not provided.
+
+        Returns:
+            None
+        """
+        if src_node is None or dest_node is None:
+            raise AssertionError("Both src_node & dest_node must be provided")
+
+        self.id         = edge_id
+        self.alias      = alias
+        self.src_node   = src_node
+        self.dest_node  = dest_node
+        self.relation   = relation
+        self.properties = properties or {}
+
+    def to_string(self) -> str:
+        """
+        Get a string representation of the edge's properties.
+
+        Returns:
+            str: A string representation of the edge's properties.
+        """
+        res = ""
+        if self.properties:
+            props = ",".join(
+                key + ":" + str(quote_string(val))
+                for key, val in sorted(self.properties.items())
+            )
+            res += "{" + props + "}"
+
+        return res
+
+    def __str__(self) -> str:
+        """
+        Get a string representation of the edge.
+
+        Returns:
+            str: A string representation of the edge.
+        """
+        # Source node
+        if isinstance(self.src_node, Node):
+            res = f"({self.src_node.alias})"
+        else:
+            res = "()"
+
+        # Edge
+        res += f"-[{self.alias}"
+        if self.relation:
+            res += ":" + self.relation
+        if self.properties:
+            props = ",".join(
+                key + ":" + str(quote_string(val))
+                for key, val in sorted(self.properties.items())
+            )
+            res += f"{{{props}}}"
+        res += "]->"
+
+        # Dest node
+        if isinstance(self.dest_node, Node):
+            res += f"({self.dest_node.alias})"
+        else:
+            res += "()"
+
+        return res
+
+    def __eq__(self, rhs) -> bool:
+        """
+        Check if two edges are equal.
+
+        Args:
+            rhs: The edge to compare.
+
+        Returns:
+            bool: True if the edges are equal, False otherwise.
+        """
+        # Type checking
+        if not isinstance(rhs, Edge):
+            return False
+
+        # Quick positive check, if both IDs are set
+        if self.id is not None and rhs.id is not None and self.id == rhs.id:
+            return True
+
+        # Source and destination nodes should match
+        if self.src_node != rhs.src_node:
+            return False
+
+        if self.dest_node != rhs.dest_node:
+            return False
+
+        # Relation should match
+        if self.relation != rhs.relation:
+            return False
+
+        # Quick check for the number of properties
+        if len(self.properties) != len(rhs.properties):
+            return False
+
+        # Compare properties
+        if self.properties != rhs.properties:
+            return False
+
+        return True

falkordb-1.0.0a0/falkordb/exceptions.py

@@ -0,0 +1,15 @@
+class SchemaVersionMismatchException(Exception):
+    """
+    Exception raised when the schema version of the database does not match the
+    version of the schema that the application expects.
+    """
+    def __init__(self, version: int):
+        """
+        Create a new SchemaVersionMismatchException.
+
+        Args:
+            version: The version of the schema that the application expects.
+
+        """
+
+        self.version = version

falkordb-1.0.0a0/falkordb/execution_plan.py

@@ -0,0 +1,324 @@
+import re
+
+
+class ProfileStats:
+    """
+    ProfileStats Class for representing runtime execution statistics of an operation.
+
+    Attributes:
+        records_produced (int): The number of records produced.
+        execution_time (float): The execution time in milliseconds.
+    """
+
+    def __init__(self, records_produced: int, execution_time: float):
+        """
+        Initializes a new ProfileStats instance with the given records_produced and execution_time.
+
+        Args:
+            records_produced (int): The number of records produced.
+            execution_time (float): The execution time in milliseconds.
+        """
+        self.execution_time   = execution_time
+        self.records_produced = records_produced
+
+
+class Operation:
+    """
+    Operation Class for representing a single operation within an execution plan.
+
+    Attributes:
+        name (str): The name of the operation.
+        args (str): Operation arguments.
+        children (list): List of child operations.
+        profile_stats (ProfileStats): Profile statistics for the operation.
+    """
+
+    def __init__(self, name: str, args=None, profile_stats: bool = None):
+        """
+        Creates a new Operation instance.
+
+        Args:
+            name (str): The name of the operation.
+            args (str, optional): Operation arguments.
+            profile_stats (ProfileStats, optional): Profile statistics for the operation.
+        """
+        self.name          = name
+        self.args          = args
+        self.children      = []
+        self.profile_stats = profile_stats
+
+    @property
+    def execution_time(self) -> int:
+        """
+        returns operation's execution time in ms
+        """
+        return self.profile_stats.execution_time
+
+    @property
+    def records_produced(self) -> int:
+        """
+        returns number of records produced by operation.
+        """
+        return self.profile_stats.records_produced
+
+    def append_child(self, child):
+        """
+        Appends a child operation to the current operation.
+
+        Args:
+            child (Operation): The child operation to append.
+
+        Returns:
+            Operation: The updated operation instance.
+        """
+        if not isinstance(child, Operation):
+            raise Exception("child must be Operation")
+
+        self.children.append(child)
+        return self
+
+    def child_count(self) -> int:
+        """
+        Returns the number of child operations.
+
+        Returns:
+            int: Number of child operations.
+        """
+        return len(self.children)
+
+    def __eq__(self, o: object) -> bool:
+        """
+        Compares two Operation instances for equality based on their name and arguments.
+
+        Args:
+            o (object): Another Operation instance for comparison.
+
+        Returns:
+            bool: True if the operations are equal, False otherwise.
+        """
+        if not isinstance(o, Operation):
+            return False
+
+        return self.name == o.name and self.args == o.args
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the operation.
+
+        Returns:
+            str: String representation of the operation.
+        """
+        args_str = "" if self.args is None else " | " + self.args
+        return f"{self.name}{args_str}"
+
+
+class ExecutionPlan:
+    """
+    ExecutionPlan Class for representing a collection of operations.
+
+    Attributes:
+        plan (list): List of strings representing the collection of operations.
+        structured_plan (Operation): Root of the structured operation tree.
+    """
+
+    def __init__(self, plan):
+        """
+        Creates a new ExecutionPlan instance.
+
+        Args:
+            plan (list): List of strings representing the collection of operations.
+        """
+        if not isinstance(plan, list):
+            raise Exception("plan must be an array")
+
+        if isinstance(plan[0], bytes):
+            plan = [b.decode() for b in plan]
+
+        self.plan = plan
+        self.operations = {}
+        self.structured_plan = self._operation_tree()
+        for key in self.operations:
+            self.operations[key].reverse()
+
+    def collect_operations(self, op_name):
+        """
+        Collects all operations with specified name from plan
+
+        Args:
+            op_name (string): Name of operation to collect
+
+        Returns:
+            List[Operation]: All operations with the specified name
+        """
+        if op_name in self.operations:
+            return self.operations[op_name]
+        return []
+
+        ops = []
+
+        for op in self.operations:
+            if op.name == op_name:
+                ops.append(op)
+
+        return ops
+
+    def __compare_operations(self, root_a, root_b) -> bool:
+        """
+        Compares execution plan operation trees.
+
+        Returns:
+            bool: True if operation trees are equal, False otherwise.
+        """
+        # compare current root
+        if root_a != root_b:
+            return False
+
+        # make sure root have the same number of children
+        if root_a.child_count() != root_b.child_count():
+            return False
+
+        # recursively compare children
+        for i in range(root_a.child_count()):
+            if not self.__compare_operations(root_a.children[i], root_b.children[i]):
+                return False
+
+        return True
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the execution plan.
+
+        Returns:
+            str: String representation of the execution plan.
+        """
+        def aggregate_str(str_children):
+            return "\n".join(
+                [
+                    "    " + line
+                    for str_child in str_children
+                    for line in str_child.splitlines()
+                ]
+            )
+
+        def combine_str(x, y):
+            return f"{x}\n{y}"
+
+        return self._operation_traverse(
+            self.structured_plan, str, aggregate_str, combine_str
+        )
+
+    def __eq__(self, o: object) -> bool:
+        """
+        Compares two execution plans.
+
+        Returns:
+            bool: True if the two plans are equal, False otherwise.
+        """
+        # make sure 'o' is an execution-plan
+        if not isinstance(o, ExecutionPlan):
+            return False
+
+        # get root for both plans
+        root_a = self.structured_plan
+        root_b = o.structured_plan
+
+        # compare execution trees
+        return self.__compare_operations(root_a, root_b)
+
+    def __iter__(self):
+        return iter(self.operations)
+
+    def _operation_traverse(self, op, op_f, aggregate_f, combine_f):
+        """
+        Traverses the operation tree recursively applying functions.
+
+        Args:
+            op: Operation to traverse.
+            op_f: Function applied for each operation.
+            aggregate_f: Aggregation function applied for all children of a single operation.
+            combine_f: Combine function applied for the operation result and the children result.
+        """
+        # apply op_f for each operation
+        op_res = op_f(op)
+        if len(op.children) == 0:
+            return op_res  # no children return
+
+        # apply _operation_traverse recursively
+        children = [
+            self._operation_traverse(child, op_f, aggregate_f, combine_f)
+            for child in op.children
+        ]
+        # combine the operation result with the children aggregated result
+        return combine_f(op_res, aggregate_f(children))
+
+    def _operation_tree(self):
+        """
+        Builds the operation tree from the string representation.
+
+        Returns:
+            Operation: Root of the structured operation tree.
+        """
+        # initial state
+        i       = 0
+        level   = 0
+        stack   = []
+        current = None
+
+        def create_operation(args):
+            profile_stats = None
+            name = args[0].strip()
+            args.pop(0)
+            if len(args) > 0 and "Records produced" in args[-1]:
+                records_produced = int(
+                    re.search("Records produced: (\\d+)", args[-1]).group(1)
+                )
+                execution_time = float(
+                    re.search("Execution time: (\\d+.\\d+) ms", args[-1]).group(1)
+                )
+                profile_stats = ProfileStats(records_produced, execution_time)
+                args.pop(-1)
+            return Operation(
+                name, None if len(args) == 0 else args[0].strip(), profile_stats
+            )
+
+        # iterate plan operations
+        while i < len(self.plan):
+            current_op = self.plan[i]
+            op_level = current_op.count("    ")
+            if op_level == level:
+                # if the operation level equal to the current level
+                # set the current operation and move next
+                child = create_operation(current_op.split("|"))
+                if child.name not in self.operations:
+                    self.operations[child.name] = []
+                self.operations[child.name].append(child)
+
+                if current:
+                    current = stack.pop()
+                    current.append_child(child)
+                current = child
+                i += 1
+                stack.append(child)
+            elif op_level == level + 1:
+                # if the operation is child of the current operation
+                # add it as child and set as current operation
+                child = create_operation(current_op.split("|"))
+                if child.name not in self.operations:
+                    self.operations[child.name] = []
+                self.operations[child.name].append(child)
+
+                current.append_child(child)
+                stack.append(current)
+                current = child
+                level += 1
+                i += 1
+            elif op_level < level:
+                # if the operation is not child of current operation
+                # go back to it's parent operation
+                levels_back = level - op_level + 1
+                for _ in range(levels_back):
+                    current = stack.pop()
+                level -= levels_back
+            else:
+                raise Exception("corrupted plan")
+        return stack[0]