flowquery 1.0.16 → 1.0.17

package/flowquery-py/src/graph/physical_node.py

@@ -0,0 +1,40 @@
+"""Physical node representation for FlowQuery."""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..parsing.ast_node import ASTNode
+
+from .node import Node
+
+
+class PhysicalNode(Node):
+    """Represents a physical node in the graph database."""
+
+    def __init__(self, id_: Optional[str], label: str, properties: Optional[Dict[str, Any]] = None):
+        super().__init__(id_, label)
+        # Store additional physical properties in a separate dict
+        # (Node.properties is for Expression-based pattern properties)
+        self._physical_properties = properties or {}
+        self._statement: Optional["ASTNode"] = None
+
+    @property
+    def physical_properties(self) -> Dict[str, Any]:
+        """Get the physical properties (values, not expressions)."""
+        return self._physical_properties
+
+    @property
+    def statement(self) -> Optional["ASTNode"]:
+        return self._statement
+
+    @statement.setter
+    def statement(self, value: Optional["ASTNode"]) -> None:
+        self._statement = value
+
+    async def data(self) -> List[Dict[str, Any]]:
+        if self._statement is None:
+            raise ValueError("Statement is null")
+        from ..compute.runner import Runner
+        runner = Runner(ast=self._statement)
+        await runner.run()
+        return runner.results

package/flowquery-py/src/graph/physical_relationship.py

@@ -0,0 +1,36 @@
+"""Physical relationship representation for FlowQuery."""
+
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from .relationship import Relationship
+
+if TYPE_CHECKING:
+    from ..parsing.ast_node import ASTNode
+
+
+class PhysicalRelationship(Relationship):
+    """Represents a physical relationship in the graph database."""
+
+    def __init__(self):
+        super().__init__()
+        self._statement: Optional[ASTNode] = None
+
+    @property
+    def statement(self) -> Optional[ASTNode]:
+        """Get the statement for this relationship."""
+        return self._statement
+
+    @statement.setter
+    def statement(self, value: Optional[ASTNode]) -> None:
+        """Set the statement for this relationship."""
+        self._statement = value
+
+    async def data(self) -> List[Dict[str, Any]]:
+        """Execute the statement and return results."""
+        if self._statement is None:
+            raise ValueError("Statement is null")
+        from ..compute.runner import Runner
+        runner = Runner(None, self._statement)
+        await runner.run()
+        return runner.results

package/flowquery-py/src/graph/relationship.py

@@ -0,0 +1,135 @@
+"""Graph relationship representation for FlowQuery."""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union
+
+from ..parsing.ast_node import ASTNode
+from .hops import Hops
+from .relationship_match_collector import RelationshipMatchCollector, RelationshipMatchRecord
+
+if TYPE_CHECKING:
+    from .node import Node
+    from .relationship_data import RelationshipData, RelationshipRecord
+
+
+class Relationship(ASTNode):
+    """Represents a relationship in a graph pattern."""
+
+    def __init__(self):
+        super().__init__()
+        self._identifier: Optional[str] = None
+        self._type: Optional[str] = None
+        self._hops: Hops = Hops()
+        self._source: Optional['Node'] = None
+        self._target: Optional['Node'] = None
+        self._data: Optional['RelationshipData'] = None
+        self._value: Optional[Union[RelationshipMatchRecord, List[RelationshipMatchRecord]]] = None
+        self._matches: RelationshipMatchCollector = RelationshipMatchCollector()
+        self._properties: Dict[str, Any] = {}
+
+    @property
+    def identifier(self) -> Optional[str]:
+        return self._identifier
+
+    @identifier.setter
+    def identifier(self, value: str) -> None:
+        self._identifier = value
+
+    @property
+    def type(self) -> Optional[str]:
+        return self._type
+
+    @type.setter
+    def type(self, value: str) -> None:
+        self._type = value
+
+    @property
+    def hops(self) -> Hops:
+        return self._hops
+
+    @hops.setter
+    def hops(self, value: Hops) -> None:
+        self._hops = value
+
+    @property
+    def properties(self) -> Dict[str, Any]:
+        """Get properties from relationship data."""
+        if self._data:
+            return self._data.properties() or {}
+        return {}
+
+    @property
+    def source(self) -> Optional['Node']:
+        return self._source
+
+    @source.setter
+    def source(self, value: 'Node') -> None:
+        self._source = value
+
+    @property
+    def target(self) -> Optional['Node']:
+        return self._target
+
+    @target.setter
+    def target(self, value: 'Node') -> None:
+        self._target = value
+
+    # Keep start/end aliases for backward compatibility
+    @property
+    def start(self) -> Optional['Node']:
+        return self._source
+
+    @start.setter
+    def start(self, value: 'Node') -> None:
+        self._source = value
+
+    @property
+    def end(self) -> Optional['Node']:
+        return self._target
+
+    @end.setter
+    def end(self, value: 'Node') -> None:
+        self._target = value
+
+    def set_data(self, data: Optional['RelationshipData']) -> None:
+        self._data = data
+
+    def set_value(self, relationship: 'Relationship') -> None:
+        """Set value by pushing match to collector."""
+        self._matches.push(relationship)
+        self._value = self._matches.value()
+
+    def value(self) -> Optional[Union[RelationshipMatchRecord, List[RelationshipMatchRecord]]]:
+        return self._value
+
+    @property
+    def matches(self) -> List[RelationshipMatchRecord]:
+        return self._matches.matches
+
+    def set_end_node(self, node: 'Node') -> None:
+        """Set the end node for the current match."""
+        self._matches.end_node = node
+
+    async def find(self, left_id: str, hop: int = 0) -> None:
+        """Find relationships starting from the given node ID."""
+        # Save original source node
+        original = self._source
+        if hop > 0:
+            # For hops greater than 0, the source becomes the target of the previous hop
+            self._source = self._target
+        if hop == 0:
+            self._data.reset() if self._data else None
+        
+        while self._data and self._data.find(left_id, hop):
+            data = self._data.current(hop)
+            if data and self._hops and hop >= self._hops.min:
+                self.set_value(self)
+                if self._target and 'right_id' in data:
+                    await self._target.find(data['right_id'], hop)
+                if self._matches.is_circular():
+                    raise ValueError("Circular relationship detected")
+                if self._hops and hop + 1 < self._hops.max:
+                    await self.find(data['right_id'], hop + 1)
+                self._matches.pop()
+        
+        # Restore original source node
+        self._source = original

package/flowquery-py/src/graph/relationship_data.py

@@ -0,0 +1,33 @@
+"""Relationship data class for FlowQuery."""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+from .data import Data
+
+
+class RelationshipRecord(TypedDict, total=False):
+    """Represents a relationship record from the database."""
+    left_id: str
+    right_id: str
+
+
+class RelationshipData(Data):
+    """Relationship data class extending Data with left_id-based indexing."""
+
+    def __init__(self, records: Optional[List[Dict[str, Any]]] = None):
+        super().__init__(records)
+        self._build_index("left_id")
+
+    def find(self, left_id: str, hop: int = 0) -> bool:
+        """Find a relationship by start node ID."""
+        return self._find(left_id, hop)
+
+    def properties(self) -> Optional[Dict[str, Any]]:
+        """Get properties of current relationship, excluding left_id and right_id."""
+        current = self.current()
+        if current:
+            props = dict(current)
+            props.pop("left_id", None)
+            props.pop("right_id", None)
+            return props
+        return None

package/flowquery-py/src/graph/relationship_match_collector.py

@@ -0,0 +1,77 @@
+"""Collector for relationship match records."""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, TypedDict, Union
+
+if TYPE_CHECKING:
+    from .relationship import Relationship
+    from .node import Node
+
+
+class RelationshipMatchRecord(TypedDict, total=False):
+    """Represents a matched relationship record."""
+    type: str
+    startNode: Dict[str, Any]
+    endNode: Optional[Dict[str, Any]]
+    properties: Dict[str, Any]
+
+
+class RelationshipMatchCollector:
+    """Collects relationship matches during graph traversal."""
+
+    def __init__(self):
+        self._matches: List[RelationshipMatchRecord] = []
+        self._node_ids: List[str] = []
+
+    def push(self, relationship: 'Relationship') -> RelationshipMatchRecord:
+        """Push a new match onto the collector."""
+        match: RelationshipMatchRecord = {
+            "type": relationship.type or "",
+            "startNode": relationship.source.value() if relationship.source else {},
+            "endNode": None,
+            "properties": relationship.properties,
+        }
+        self._matches.append(match)
+        start_node_value = match.get("startNode", {})
+        if isinstance(start_node_value, dict):
+            self._node_ids.append(start_node_value.get("id", ""))
+        return match
+
+    @property
+    def end_node(self) -> Optional[Dict[str, Any]]:
+        """Get the end node of the last match."""
+        if self._matches:
+            return self._matches[-1].get("endNode")
+        return None
+
+    @end_node.setter
+    def end_node(self, node: 'Node') -> None:
+        """Set the end node of the last match."""
+        if self._matches:
+            self._matches[-1]["endNode"] = node.value()
+
+    def pop(self) -> Optional[RelationshipMatchRecord]:
+        """Pop the last match from the collector."""
+        if self._node_ids:
+            self._node_ids.pop()
+        if self._matches:
+            return self._matches.pop()
+        return None
+
+    def value(self) -> Optional[Union[RelationshipMatchRecord, List[RelationshipMatchRecord]]]:
+        """Get the current value(s)."""
+        if len(self._matches) == 0:
+            return None
+        elif len(self._matches) == 1:
+            return self._matches[0]
+        else:
+            return self._matches
+
+    @property
+    def matches(self) -> List[RelationshipMatchRecord]:
+        """Get all matches."""
+        return self._matches
+
+    def is_circular(self) -> bool:
+        """Check if the collected relationships form a circular pattern."""
+        seen = set(self._node_ids)
+        return len(seen) < len(self._node_ids)

package/flowquery-py/src/graph/relationship_reference.py

@@ -0,0 +1,21 @@
+"""Relationship reference for FlowQuery."""
+
+from .relationship import Relationship
+from ..parsing.ast_node import ASTNode
+
+
+class RelationshipReference(Relationship):
+    """Represents a reference to an existing relationship variable."""
+
+    def __init__(self, relationship: Relationship, referred: ASTNode):
+        super().__init__()
+        self._referred = referred
+        if relationship.type:
+            self.type = relationship.type
+
+    @property
+    def referred(self) -> ASTNode:
+        return self._referred
+
+    def value(self):
+        return self._referred.value() if self._referred else None

package/flowquery-py/src/io/__init__.py

@@ -0,0 +1,5 @@
+"""IO module for FlowQuery."""
+
+from .command_line import CommandLine
+
+__all__ = ["CommandLine"]

package/flowquery-py/src/io/command_line.py

@@ -0,0 +1,67 @@
+"""Interactive command-line interface for FlowQuery."""
+
+import asyncio
+from typing import Optional
+
+from ..compute.runner import Runner
+
+
+class CommandLine:
+    """Interactive command-line interface for FlowQuery.
+    
+    Provides a REPL (Read-Eval-Print Loop) for executing FlowQuery statements
+    and displaying results.
+    
+    Example:
+        cli = CommandLine()
+        cli.loop()  # Starts interactive mode
+    """
+
+    def loop(self) -> None:
+        """Starts the interactive command loop.
+        
+        Prompts the user for FlowQuery statements, executes them, and displays results.
+        Type "exit" to quit the loop. End multi-line queries with ";".
+        """
+        print('Welcome to FlowQuery! Type "exit" to quit.')
+        print('End queries with ";" to execute. Multi-line input supported.')
+        
+        while True:
+            try:
+                lines = []
+                prompt = "> "
+                while True:
+                    line = input(prompt)
+                    if line.strip() == "exit":
+                        print("Exiting FlowQuery.")
+                        return
+                    lines.append(line)
+                    user_input = "\n".join(lines)
+                    if user_input.strip().endswith(";"):
+                        break
+                    prompt = "... "
+            except EOFError:
+                break
+            
+            if user_input.strip() == "":
+                continue
+            
+            # Remove the termination semicolon before sending to the engine
+            user_input = user_input.strip().rstrip(";")
+            
+            try:
+                runner = Runner(user_input)
+                asyncio.run(self._execute(runner))
+            except Exception as e:
+                print(f"Error: {e}")
+
+        print("Exiting FlowQuery.")
+
+    async def _execute(self, runner: Runner) -> None:
+        await runner.run()
+        print(runner.results)
+
+
+def main() -> None:
+    """Entry point for the flowquery CLI command."""
+    CommandLine().loop()

package/flowquery-py/src/parsing/__init__.py

@@ -0,0 +1,17 @@
+"""Parsing module for FlowQuery."""
+
+from .ast_node import ASTNode
+from .context import Context
+from .alias import Alias
+from .alias_option import AliasOption
+from .base_parser import BaseParser
+from .parser import Parser
+
+__all__ = [
+    "ASTNode",
+    "Context",
+    "Alias",
+    "AliasOption",
+    "BaseParser",
+    "Parser",
+]

package/flowquery-py/src/parsing/alias.py

@@ -0,0 +1,20 @@
+"""Alias node for FlowQuery AST."""
+
+from .ast_node import ASTNode
+
+
+class Alias(ASTNode):
+    """Represents an alias in the FlowQuery AST."""
+
+    def __init__(self, alias: str):
+        super().__init__()
+        self._alias = alias
+
+    def __str__(self) -> str:
+        return f"Alias ({self._alias})"
+
+    def get_alias(self) -> str:
+        return self._alias
+
+    def value(self) -> str:
+        return self._alias

package/flowquery-py/src/parsing/alias_option.py

@@ -0,0 +1,11 @@
+"""Alias option enumeration for FlowQuery parsing."""
+
+from enum import Enum
+
+
+class AliasOption(Enum):
+    """Enumeration of alias options for parsing."""
+    
+    NOT_ALLOWED = 0
+    OPTIONAL = 1
+    REQUIRED = 2

package/flowquery-py/src/parsing/ast_node.py

@@ -0,0 +1,146 @@
+"""Represents a node in the Abstract Syntax Tree (AST)."""
+
+from __future__ import annotations
+from typing import List, Any, Generator, Optional
+
+
+class ASTNode:
+    """Represents a node in the Abstract Syntax Tree (AST).
+    
+    The AST is a tree representation of the parsed FlowQuery statement structure.
+    Each node can have children and maintains a reference to its parent.
+    
+    Example:
+        root = ASTNode()
+        child = ASTNode()
+        root.add_child(child)
+    """
+
+    def __init__(self):
+        self._parent: Optional[ASTNode] = None
+        self.children: List[ASTNode] = []
+
+    def add_child(self, child: ASTNode) -> None:
+        """Adds a child node to this node and sets the child's parent reference.
+        
+        Args:
+            child: The child node to add
+        """
+        child._parent = self
+        self.children.append(child)
+
+    def first_child(self) -> ASTNode:
+        """Returns the first child node.
+        
+        Returns:
+            The first child node
+            
+        Raises:
+            ValueError: If the node has no children
+        """
+        if len(self.children) == 0:
+            raise ValueError('Expected child')
+        return self.children[0]
+
+    def last_child(self) -> ASTNode:
+        """Returns the last child node.
+        
+        Returns:
+            The last child node
+            
+        Raises:
+            ValueError: If the node has no children
+        """
+        if len(self.children) == 0:
+            raise ValueError('Expected child')
+        return self.children[-1]
+
+    def get_children(self) -> List[ASTNode]:
+        """Returns all child nodes.
+        
+        Returns:
+            Array of child nodes
+        """
+        return self.children
+
+    def child_count(self) -> int:
+        """Returns the number of child nodes.
+        
+        Returns:
+            The count of children
+        """
+        return len(self.children)
+
+    def value(self) -> Any:
+        """Returns the value of this node. Override in subclasses to provide specific values.
+        
+        Returns:
+            The node's value, or None if not applicable
+        """
+        return None
+
+    def is_operator(self) -> bool:
+        """Checks if this node represents an operator.
+        
+        Returns:
+            True if this is an operator node, False otherwise
+        """
+        return False
+
+    def is_operand(self) -> bool:
+        """Checks if this node represents an operand (the opposite of an operator).
+        
+        Returns:
+            True if this is an operand node, False otherwise
+        """
+        return not self.is_operator()
+
+    @property
+    def precedence(self) -> int:
+        """Gets the operator precedence for this node. Higher values indicate higher precedence.
+        
+        Returns:
+            The precedence value (0 for non-operators)
+        """
+        return 0
+
+    @property
+    def left_associative(self) -> bool:
+        """Indicates whether this operator is left-associative.
+        
+        Returns:
+            True if left-associative, False otherwise
+        """
+        return False
+
+    def print(self) -> str:
+        """Prints a string representation of the AST tree starting from this node.
+        
+        Returns:
+            A formatted string showing the tree structure
+        """
+        return '\n'.join(self._print(0))
+
+    def _print(self, indent: int) -> Generator[str, None, None]:
+        """Generator function for recursively printing the tree structure.
+        
+        Args:
+            indent: The current indentation level
+            
+        Yields:
+            Lines representing each node in the tree
+        """
+        if indent == 0:
+            yield self.__class__.__name__
+        elif indent > 0:
+            yield '-' * indent + f' {self}'
+        for child in self.children:
+            yield from child._print(indent + 1)
+
+    def __str__(self) -> str:
+        """Returns a string representation of this node. Override in subclasses for custom formatting.
+        
+        Returns:
+            The string representation
+        """
+        return self.__class__.__name__