flowquery 1.0.15 → 1.0.17

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

@@ -0,0 +1,118 @@
+"""Data class for graph record iteration and indexing."""
+
+from typing import Any, Dict, List, Optional
+
+
+class IndexEntry:
+    """Index entry for tracking positions of records with a specific key value."""
+
+    def __init__(self, positions: Optional[List[int]] = None):
+        self._positions: List[int] = positions if positions is not None else []
+        self._index: int = -1
+
+    def add(self, position: int) -> None:
+        """Add a position to the index entry."""
+        self._positions.append(position)
+
+    @property
+    def position(self) -> int:
+        """Get the current position."""
+        return self._positions[self._index]
+
+    def reset(self) -> None:
+        """Reset the index to the beginning."""
+        self._index = -1
+
+    def next(self) -> bool:
+        """Move to the next position. Returns True if successful."""
+        if self._index < len(self._positions) - 1:
+            self._index += 1
+            return True
+        return False
+
+    def clone(self) -> "IndexEntry":
+        """Create a copy of this index entry."""
+        return IndexEntry(list(self._positions))
+
+
+class Layer:
+    """Layer for managing index state at a specific level."""
+
+    def __init__(self, index: Dict[str, IndexEntry]):
+        self._index: Dict[str, IndexEntry] = index
+        self._current: int = -1
+
+    @property
+    def index(self) -> Dict[str, IndexEntry]:
+        """Get the index dictionary."""
+        return self._index
+
+    @property
+    def current(self) -> int:
+        """Get the current position."""
+        return self._current
+
+    @current.setter
+    def current(self, value: int) -> None:
+        """Set the current position."""
+        self._current = value
+
+
+class Data:
+    """Base class for graph data with record iteration and indexing."""
+
+    def __init__(self, records: Optional[List[Dict[str, Any]]] = None):
+        self._records: List[Dict[str, Any]] = records if records is not None else []
+        self._layers: Dict[int, Layer] = {0: Layer({})}
+
+    def _build_index(self, key: str, level: int = 0) -> None:
+        """Build an index for the given key at the specified level."""
+        self.layer(level).index.clear()
+        for idx, record in enumerate(self._records):
+            if key in record:
+                if record[key] not in self.layer(level).index:
+                    self.layer(level).index[record[key]] = IndexEntry()
+                self.layer(level).index[record[key]].add(idx)
+
+    def layer(self, level: int = 0) -> Layer:
+        """Get or create a layer at the specified level."""
+        if level not in self._layers:
+            first = self._layers[0]
+            cloned = {}
+            for key, entry in first.index.items():
+                cloned[key] = entry.clone()
+            self._layers[level] = Layer(cloned)
+        return self._layers[level]
+
+    def _find(self, key: str, level: int = 0) -> bool:
+        """Find the next record with the given key value."""
+        if key not in self.layer(level).index:
+            self.layer(level).current = len(self._records)  # Move to end
+            return False
+        else:
+            entry = self.layer(level).index[key]
+            more = entry.next()
+            if not more:
+                self.layer(level).current = len(self._records)  # Move to end
+                return False
+            self.layer(level).current = entry.position
+            return True
+
+    def reset(self) -> None:
+        """Reset iteration to the beginning."""
+        self.layer(0).current = -1
+        for entry in self.layer(0).index.values():
+            entry.reset()
+
+    def next(self, level: int = 0) -> bool:
+        """Move to the next record. Returns True if successful."""
+        if self.layer(level).current < len(self._records) - 1:
+            self.layer(level).current += 1
+            return True
+        return False
+
+    def current(self, level: int = 0) -> Optional[Dict[str, Any]]:
+        """Get the current record."""
+        if self.layer(level).current < len(self._records):
+            return self._records[self.layer(level).current]
+        return None

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

@@ -0,0 +1,82 @@
+"""Graph database for FlowQuery."""
+
+from typing import Any, Dict, Optional, Union, TYPE_CHECKING
+
+from ..parsing.ast_node import ASTNode
+
+if TYPE_CHECKING:
+    from .node import Node
+    from .relationship import Relationship
+    from .node_data import NodeData
+    from .relationship_data import RelationshipData
+
+
+class Database:
+    """Singleton database for storing graph data."""
+
+    _instance: Optional['Database'] = None
+    _nodes: Dict[str, 'PhysicalNode'] = {}
+    _relationships: Dict[str, 'PhysicalRelationship'] = {}
+
+    def __init__(self):
+        pass
+
+    @classmethod
+    def get_instance(cls) -> 'Database':
+        if cls._instance is None:
+            cls._instance = Database()
+        return cls._instance
+
+    def add_node(self, node: 'Node', statement: ASTNode) -> None:
+        """Adds a node to the database."""
+        from .physical_node import PhysicalNode
+        if node.label is None:
+            raise ValueError("Node label is null")
+        physical = PhysicalNode(None, node.label)
+        physical.statement = statement
+        Database._nodes[node.label] = physical
+
+    def get_node(self, node: 'Node') -> Optional['PhysicalNode']:
+        """Gets a node from the database."""
+        return Database._nodes.get(node.label) if node.label else None
+
+    def add_relationship(self, relationship: 'Relationship', statement: ASTNode) -> None:
+        """Adds a relationship to the database."""
+        from .physical_relationship import PhysicalRelationship
+        if relationship.type is None:
+            raise ValueError("Relationship type is null")
+        physical = PhysicalRelationship()
+        physical.type = relationship.type
+        physical.statement = statement
+        Database._relationships[relationship.type] = physical
+
+    def get_relationship(self, relationship: 'Relationship') -> Optional['PhysicalRelationship']:
+        """Gets a relationship from the database."""
+        return Database._relationships.get(relationship.type) if relationship.type else None
+
+    async def get_data(self, element: Union['Node', 'Relationship']) -> Union['NodeData', 'RelationshipData']:
+        """Gets data for a node or relationship."""
+        from .node import Node
+        from .relationship import Relationship
+        from .node_data import NodeData
+        from .relationship_data import RelationshipData
+        
+        if isinstance(element, Node):
+            node = self.get_node(element)
+            if node is None:
+                raise ValueError(f"Physical node not found for label {element.label}")
+            data = await node.data()
+            return NodeData(data)
+        elif isinstance(element, Relationship):
+            relationship = self.get_relationship(element)
+            if relationship is None:
+                raise ValueError(f"Physical relationship not found for type {element.type}")
+            data = await relationship.data()
+            return RelationshipData(data)
+        else:
+            raise ValueError("Element is neither Node nor Relationship")
+
+
+# Import for type hints
+from .physical_node import PhysicalNode
+from .physical_relationship import PhysicalRelationship

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

@@ -0,0 +1,43 @@
+"""Hops specification for variable-length relationships."""
+
+import sys
+from typing import Optional
+
+
+class Hops:
+    """Specifies the number of hops for a relationship pattern."""
+
+    def __init__(self, min_hops: Optional[int] = None, max_hops: Optional[int] = None):
+        # Default min=0, max=1 (matching TypeScript implementation)
+        if min_hops is None:
+            self._min: int = 0
+        else:
+            self._min = min_hops
+        if max_hops is None:
+            self._max: int = 1
+        else:
+            self._max = max_hops
+
+    @property
+    def min(self) -> int:
+        return self._min
+
+    @min.setter
+    def min(self, value: int) -> None:
+        self._min = value
+
+    @property
+    def max(self) -> int:
+        return self._max
+
+    @max.setter
+    def max(self, value: int) -> None:
+        self._max = value
+
+    def multi(self) -> bool:
+        """Returns True if this represents a variable-length relationship."""
+        return self._max > 1 or self._max == -1 or self._max == sys.maxsize
+
+    def unbounded(self) -> bool:
+        """Returns True if the max is unbounded."""
+        return self._max == sys.maxsize

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

@@ -0,0 +1,112 @@
+"""Graph node representation for FlowQuery."""
+
+from typing import Any, Callable, Dict, Optional, TYPE_CHECKING
+
+from ..parsing.ast_node import ASTNode
+from ..parsing.expressions.expression import Expression
+
+if TYPE_CHECKING:
+    from .relationship import Relationship
+    from .node_data import NodeData, NodeRecord
+
+
+class Node(ASTNode):
+    """Represents a node in a graph pattern."""
+
+    def __init__(
+        self,
+        identifier: Optional[str] = None,
+        label: Optional[str] = None
+    ):
+        super().__init__()
+        self._identifier = identifier
+        self._label = label
+        self._properties: Dict[str, Expression] = {}
+        self._value: Optional['NodeRecord'] = None
+        self._incoming: Optional['Relationship'] = None
+        self._outgoing: Optional['Relationship'] = None
+        self._data: Optional['NodeData'] = None
+        self._todo_next: Optional[Callable[[], None]] = None
+
+    @property
+    def identifier(self) -> Optional[str]:
+        return self._identifier
+
+    @identifier.setter
+    def identifier(self, value: str) -> None:
+        self._identifier = value
+
+    @property
+    def label(self) -> Optional[str]:
+        return self._label
+
+    @label.setter
+    def label(self, value: str) -> None:
+        self._label = value
+
+    @property
+    def properties(self) -> Dict[str, Expression]:
+        return self._properties
+
+    def set_property(self, key: str, value: Expression) -> None:
+        self._properties[key] = value
+
+    def get_property(self, key: str) -> Optional[Expression]:
+        return self._properties.get(key)
+
+    def set_value(self, value: 'NodeRecord') -> None:
+        self._value = value
+
+    def value(self) -> Optional['NodeRecord']:
+        return self._value
+
+    @property
+    def outgoing(self) -> Optional['Relationship']:
+        return self._outgoing
+
+    @outgoing.setter
+    def outgoing(self, relationship: Optional['Relationship']) -> None:
+        self._outgoing = relationship
+
+    @property
+    def incoming(self) -> Optional['Relationship']:
+        return self._incoming
+
+    @incoming.setter
+    def incoming(self, relationship: Optional['Relationship']) -> None:
+        self._incoming = relationship
+
+    def set_data(self, data: Optional['NodeData']) -> None:
+        self._data = data
+
+    async def next(self) -> None:
+        if self._data:
+            self._data.reset()
+            while self._data.next():
+                self.set_value(self._data.current())
+                if self._outgoing:
+                    await self._outgoing.find(self._value['id'])
+                await self.run_todo_next()
+
+    async def find(self, id_: str, hop: int = 0) -> None:
+        if self._data:
+            self._data.reset()
+            while self._data.find(id_, hop):
+                self.set_value(self._data.current(hop))
+                if self._incoming:
+                    self._incoming.set_end_node(self)
+                if self._outgoing:
+                    await self._outgoing.find(self._value['id'], hop)
+                await self.run_todo_next()
+
+    @property
+    def todo_next(self) -> Optional[Callable[[], None]]:
+        return self._todo_next
+
+    @todo_next.setter
+    def todo_next(self, func: Optional[Callable[[], None]]) -> None:
+        self._todo_next = func
+
+    async def run_todo_next(self) -> None:
+        if self._todo_next:
+            await self._todo_next()

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

@@ -0,0 +1,26 @@
+"""Node data class for FlowQuery."""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+from .data import Data
+
+
+class NodeRecord(TypedDict, total=False):
+    """Represents a node record from the database."""
+    id: str
+
+
+class NodeData(Data):
+    """Node data class extending Data with ID-based indexing."""
+
+    def __init__(self, records: Optional[List[Dict[str, Any]]] = None):
+        super().__init__(records)
+        self._build_index("id")
+
+    def find(self, id_: str, hop: int = 0) -> bool:
+        """Find a record by ID."""
+        return self._find(id_, hop)
+
+    def current(self, hop: int = 0) -> Optional[Dict[str, Any]]:
+        """Get the current record."""
+        return super().current(hop)

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

@@ -0,0 +1,49 @@
+"""Node reference for FlowQuery."""
+
+from typing import Optional, TYPE_CHECKING
+
+from .node import Node
+
+if TYPE_CHECKING:
+    from ..parsing.ast_node import ASTNode
+
+
+class NodeReference(Node):
+    """Represents a reference to an existing node variable."""
+
+    def __init__(self, base: Node, reference: Node):
+        super().__init__(base.identifier, base.label)
+        self._reference: Node = reference
+        # Copy properties from base
+        self._properties = base._properties
+        self._outgoing = base.outgoing
+        self._incoming = base.incoming
+
+    @property
+    def reference(self) -> Node:
+        return self._reference
+
+    # Keep referred as alias for backward compatibility
+    @property
+    def referred(self) -> Node:
+        return self._reference
+
+    def value(self):
+        return self._reference.value() if self._reference else None
+
+    async def next(self) -> None:
+        """Process next using the referenced node's value."""
+        self.set_value(self._reference.value())
+        if self._outgoing and self._value:
+            await self._outgoing.find(self._value['id'])
+        await self.run_todo_next()
+
+    async def find(self, id_: str, hop: int = 0) -> None:
+        """Find by ID, only matching if it equals the referenced node's ID."""
+        referenced = self._reference.value()
+        if referenced is None or id_ != referenced.get('id'):
+            return
+        self.set_value(referenced)
+        if self._outgoing and self._value:
+            await self._outgoing.find(self._value['id'], hop)
+        await self.run_todo_next()

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

@@ -0,0 +1,125 @@
+"""Graph pattern representation for FlowQuery."""
+
+from typing import Any, Generator, List, Optional, TYPE_CHECKING, Union
+
+from ..parsing.ast_node import ASTNode
+
+if TYPE_CHECKING:
+    from .node import Node
+    from .relationship import Relationship
+
+
+class Pattern(ASTNode):
+    """Represents a graph pattern for matching."""
+
+    def __init__(self):
+        super().__init__()
+        self._identifier: Optional[str] = None
+        self._chain: List[Union['Node', 'Relationship']] = []
+
+    @property
+    def identifier(self) -> Optional[str]:
+        return self._identifier
+
+    @identifier.setter
+    def identifier(self, value: str) -> None:
+        self._identifier = value
+
+    @property
+    def chain(self) -> List[Union['Node', 'Relationship']]:
+        return self._chain
+
+    @property
+    def elements(self) -> List[ASTNode]:
+        return self._chain
+
+    def add_element(self, element: Union['Node', 'Relationship']) -> None:
+        from .node import Node
+        from .relationship import Relationship
+        
+        if (len(self._chain) > 0 and 
+            type(self._chain[-1]) == type(element)):
+            raise ValueError("Cannot add two consecutive elements of the same type to the graph pattern")
+        
+        if len(self._chain) > 0:
+            last = self._chain[-1]
+            if isinstance(last, Node) and isinstance(element, Relationship):
+                last.outgoing = element
+                element.source = last
+            if isinstance(last, Relationship) and isinstance(element, Node):
+                last.target = element
+                element.incoming = last
+        
+        self._chain.append(element)
+        self.add_child(element)
+
+    @property
+    def start_node(self) -> 'Node':
+        from .node import Node
+        if len(self._chain) == 0:
+            raise ValueError("Pattern is empty")
+        first = self._chain[0]
+        if isinstance(first, Node):
+            return first
+        raise ValueError("Pattern does not start with a node")
+
+    @property
+    def end_node(self) -> 'Node':
+        from .node import Node
+        if len(self._chain) == 0:
+            raise ValueError("Pattern is empty")
+        last = self._chain[-1]
+        if isinstance(last, Node):
+            return last
+        raise ValueError("Pattern does not end with a node")
+
+    def first_node(self) -> Optional['Node']:
+        if len(self._chain) > 0:
+            return self._chain[0]
+        return None
+
+    def value(self) -> List[Any]:
+        return list(self.values())
+
+    def values(self) -> Generator[Any, None, None]:
+        from .node import Node
+        from .relationship import Relationship
+        
+        for element in self._chain:
+            if isinstance(element, Node):
+                yield element.value()
+            elif isinstance(element, Relationship):
+                i = 0
+                for match in element.matches:
+                    yield match
+                    if i < len(element.matches) - 1:
+                        yield match["endNode"]
+                    i += 1
+
+    async def fetch_data(self) -> None:
+        """Loads data from the database for all elements."""
+        from .database import Database
+        from .node import Node
+        from .relationship import Relationship
+        from .node_reference import NodeReference
+        from .relationship_reference import RelationshipReference
+        from .node_data import NodeData
+        from .relationship_data import RelationshipData
+        
+        db = Database.get_instance()
+        for element in self._chain:
+            if isinstance(element, (NodeReference, RelationshipReference)):
+                continue
+            data = await db.get_data(element)
+            if isinstance(element, Node):
+                element.set_data(data)
+            elif isinstance(element, Relationship):
+                element.set_data(data)
+
+    async def initialize(self) -> None:
+        await self.fetch_data()
+
+    async def traverse(self) -> None:
+        first = self.first_node()
+        if first:
+            await first.next()

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

@@ -0,0 +1,62 @@
+"""Pattern expression for FlowQuery."""
+
+from typing import Any
+
+from ..parsing.ast_node import ASTNode
+from .node_reference import NodeReference
+from .pattern import Pattern
+
+
+class PatternExpression(Pattern):
+    """Represents a pattern expression that can be evaluated.
+    
+    PatternExpression is used in WHERE clauses to test whether a graph pattern
+    exists. It evaluates to True if the pattern is matched, False otherwise.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._fetched: bool = False
+        self._evaluation: bool = False
+
+    def add_element(self, element) -> None:
+        """Add an element to the pattern, ensuring it starts with a NodeReference."""
+        if len(self._chain) == 0 and not isinstance(element, NodeReference):
+            raise ValueError("PatternExpression must start with a NodeReference")
+        super().add_element(element)
+
+    @property
+    def identifier(self):
+        return None
+
+    @identifier.setter
+    def identifier(self, value):
+        raise ValueError("Cannot set identifier on PatternExpression")
+
+    async def fetch_data(self) -> None:
+        """Fetches data for the pattern expression with caching."""
+        if self._fetched:
+            return
+        await super().fetch_data()
+        self._fetched = True
+
+    async def evaluate(self) -> None:
+        """Evaluates the pattern expression by traversing the graph.
+        
+        Sets _evaluation to True if the pattern is matched, False otherwise.
+        """
+        self._evaluation = False
+        
+        async def set_evaluation_true():
+            self._evaluation = True
+        
+        self.end_node.todo_next = set_evaluation_true
+        await self.start_node.next()
+
+    def value(self) -> bool:
+        """Returns the result of the pattern evaluation."""
+        return self._evaluation
+
+    def is_operand(self) -> bool:
+        """PatternExpression is an operand in expressions."""
+        return True

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

@@ -0,0 +1,42 @@
+"""Collection of graph patterns for FlowQuery."""
+
+from typing import Awaitable, Callable, List, Optional
+
+from .pattern import Pattern
+
+
+class Patterns:
+    """Manages a collection of graph patterns."""
+
+    def __init__(self, patterns: Optional[List[Pattern]] = None):
+        self._patterns = patterns or []
+        self._to_do_next: Optional[Callable[[], Awaitable[None]]] = None
+
+    @property
+    def patterns(self) -> List[Pattern]:
+        return self._patterns
+
+    @property
+    def to_do_next(self) -> Optional[Callable[[], Awaitable[None]]]:
+        return self._to_do_next
+
+    @to_do_next.setter
+    def to_do_next(self, func: Optional[Callable[[], Awaitable[None]]]) -> None:
+        self._to_do_next = func
+        if self._patterns:
+            self._patterns[-1].end_node.todo_next = func
+
+    async def initialize(self) -> None:
+        previous: Optional[Pattern] = None
+        for pattern in self._patterns:
+            await pattern.fetch_data()  # Ensure data is loaded
+            if previous is not None:
+                # Chain the patterns together
+                async def next_pattern_start(p=pattern):
+                    await p.start_node.next()
+                previous.end_node.todo_next = next_pattern_start
+            previous = pattern
+
+    async def traverse(self) -> None:
+        if self._patterns:
+            await self._patterns[0].start_node.next()