flowquery 1.0.16 → 1.0.17

package/flowquery-py/src/parsing/expressions/expression_map.py

@@ -0,0 +1,26 @@
+"""Expression map for managing named expressions."""
+
+from typing import Optional, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .expression import Expression
+
+
+class ExpressionMap:
+    """Maps expression aliases to their corresponding Expression objects."""
+
+    def __init__(self):
+        self._map: dict[str, Expression] = {}
+
+    def get(self, alias: str) -> Optional['Expression']:
+        return self._map.get(alias)
+
+    def has(self, alias: str) -> bool:
+        return alias in self._map
+
+    def set_map(self, expressions: List['Expression']) -> None:
+        self._map.clear()
+        for expr in expressions:
+            if expr.alias is None:
+                continue
+            self._map[expr.alias] = expr

package/flowquery-py/src/parsing/expressions/f_string.py

@@ -0,0 +1,27 @@
+"""Represents a formatted string (f-string) in the AST."""
+
+from typing import TYPE_CHECKING
+
+from ..ast_node import ASTNode
+
+if TYPE_CHECKING:
+    from .expression import Expression
+
+
+class FString(ASTNode):
+    """Represents a formatted string (f-string) in the AST.
+    
+    F-strings allow embedding expressions within string literals.
+    Child nodes represent the parts of the f-string (literal strings and expressions).
+    
+    Example:
+        # For f"Hello {name}!"
+        fstr = FString()
+        fstr.add_child(String("Hello "))
+        fstr.add_child(name_expression)
+        fstr.add_child(String("!"))
+    """
+
+    def value(self) -> str:
+        parts = self.get_children()
+        return "".join(str(part.value()) for part in parts)

package/flowquery-py/src/parsing/expressions/identifier.py

@@ -0,0 +1,20 @@
+"""Represents an identifier in the AST."""
+
+from .string import String
+from typing import Any
+
+
+class Identifier(String):
+    """Represents an identifier in the AST.
+    
+    Identifiers are used for variable names, property names, and similar constructs.
+    
+    Example:
+        id = Identifier("myVariable")
+    """
+
+    def __str__(self) -> str:
+        return f"Identifier ({self._value})"
+
+    def value(self) -> Any:
+        return super().value()

package/flowquery-py/src/parsing/expressions/number.py

@@ -0,0 +1,32 @@
+"""Represents a numeric literal in the AST."""
+
+from ..ast_node import ASTNode
+
+
+class Number(ASTNode):
+    """Represents a numeric literal in the AST.
+    
+    Parses string representations of numbers into integer or float values.
+    
+    Example:
+        num = Number("42")
+        print(num.value())  # 42
+    """
+
+    def __init__(self, value: str):
+        """Creates a new Number node by parsing the string value.
+        
+        Args:
+            value: The string representation of the number
+        """
+        super().__init__()
+        if '.' in value:
+            self._value = float(value)
+        else:
+            self._value = int(value)
+
+    def value(self) -> float | int:
+        return self._value
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__} ({self._value})"

package/flowquery-py/src/parsing/expressions/operator.py

@@ -0,0 +1,169 @@
+"""Operator classes for FlowQuery expressions."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..ast_node import ASTNode
+
+
+class Operator(ASTNode, ABC):
+    """Base class for all operators in FlowQuery."""
+
+    def __init__(self, precedence: int, left_associative: bool):
+        super().__init__()
+        self._precedence = precedence
+        self._left_associative = left_associative
+
+    def is_operator(self) -> bool:
+        return True
+
+    @property
+    def precedence(self) -> int:
+        return self._precedence
+
+    @property
+    def left_associative(self) -> bool:
+        return self._left_associative
+
+    @abstractmethod
+    def value(self) -> Any:
+        pass
+
+    @property
+    def lhs(self) -> ASTNode:
+        return self.get_children()[0]
+
+    @property
+    def rhs(self) -> ASTNode:
+        return self.get_children()[1]
+
+
+class Add(Operator):
+    def __init__(self):
+        super().__init__(1, True)
+
+    def value(self) -> Any:
+        return self.lhs.value() + self.rhs.value()
+
+
+class Subtract(Operator):
+    def __init__(self):
+        super().__init__(1, True)
+
+    def value(self) -> Any:
+        return self.lhs.value() - self.rhs.value()
+
+
+class Multiply(Operator):
+    def __init__(self):
+        super().__init__(2, True)
+
+    def value(self) -> Any:
+        return self.lhs.value() * self.rhs.value()
+
+
+class Divide(Operator):
+    def __init__(self):
+        super().__init__(2, True)
+
+    def value(self) -> Any:
+        return self.lhs.value() / self.rhs.value()
+
+
+class Modulo(Operator):
+    def __init__(self):
+        super().__init__(2, True)
+
+    def value(self) -> Any:
+        return self.lhs.value() % self.rhs.value()
+
+
+class Power(Operator):
+    def __init__(self):
+        super().__init__(3, False)
+
+    def value(self) -> Any:
+        return self.lhs.value() ** self.rhs.value()
+
+
+class Equals(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() == self.rhs.value() else 0
+
+
+class NotEquals(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() != self.rhs.value() else 0
+
+
+class GreaterThan(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() > self.rhs.value() else 0
+
+
+class LessThan(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() < self.rhs.value() else 0
+
+
+class GreaterThanOrEqual(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() >= self.rhs.value() else 0
+
+
+class LessThanOrEqual(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() <= self.rhs.value() else 0
+
+
+class And(Operator):
+    def __init__(self):
+        super().__init__(-1, True)
+
+    def value(self) -> int:
+        return 1 if (self.lhs.value() and self.rhs.value()) else 0
+
+
+class Or(Operator):
+    def __init__(self):
+        super().__init__(-1, True)
+
+    def value(self) -> int:
+        return 1 if (self.lhs.value() or self.rhs.value()) else 0
+
+
+class Not(Operator):
+    def __init__(self):
+        super().__init__(0, True)
+
+    def is_operator(self) -> bool:
+        return False
+
+    def value(self) -> int:
+        return 1 if not self.lhs.value() else 0
+
+
+class Is(Operator):
+    def __init__(self):
+        super().__init__(-1, True)
+
+    def value(self) -> int:
+        return 1 if self.lhs.value() == self.rhs.value() else 0

package/flowquery-py/src/parsing/expressions/reference.py

@@ -0,0 +1,47 @@
+"""Represents a reference to a previously defined variable or expression."""
+
+from typing import Any, Optional
+
+from ..ast_node import ASTNode
+from .identifier import Identifier
+
+
+class Reference(Identifier):
+    """Represents a reference to a previously defined variable or expression.
+    
+    References point to values defined earlier in the query (e.g., in WITH or LOAD statements).
+    
+    Example:
+        ref = Reference("myVar", previous_node)
+        print(ref.value())  # Gets value from referred node
+    """
+
+    def __init__(self, value: str, referred: Optional[ASTNode] = None):
+        """Creates a new Reference to a variable.
+        
+        Args:
+            value: The identifier name
+            referred: The node this reference points to (optional)
+        """
+        super().__init__(value)
+        self._referred = referred
+
+    @property
+    def referred(self) -> Optional[ASTNode]:
+        return self._referred
+
+    @referred.setter
+    def referred(self, node: ASTNode) -> None:
+        self._referred = node
+
+    def __str__(self) -> str:
+        return f"Reference ({self._value})"
+
+    def value(self) -> Any:
+        if self._referred is not None:
+            return self._referred.value()
+        return None
+
+    @property
+    def identifier(self) -> str:
+        return self._value

package/flowquery-py/src/parsing/expressions/string.py

@@ -0,0 +1,27 @@
+"""Represents a string literal in the AST."""
+
+from ..ast_node import ASTNode
+
+
+class String(ASTNode):
+    """Represents a string literal in the AST.
+    
+    Example:
+        s = String("hello")
+        print(s.value())  # "hello"
+    """
+
+    def __init__(self, value: str):
+        """Creates a new String node with the given value.
+        
+        Args:
+            value: The string value
+        """
+        super().__init__()
+        self._value = value
+
+    def value(self) -> str:
+        return self._value
+
+    def __str__(self) -> str:
+        return f"String ({self._value})"

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

@@ -0,0 +1,75 @@
+"""Functions module for FlowQuery parsing."""
+
+from .function import Function
+from .aggregate_function import AggregateFunction
+from .async_function import AsyncFunction
+from .predicate_function import PredicateFunction
+from .reducer_element import ReducerElement
+from .value_holder import ValueHolder
+from .function_metadata import (
+    FunctionCategory,
+    ParameterSchema,
+    OutputSchema,
+    FunctionMetadata,
+    FunctionDef,
+    FunctionDefOptions,
+    get_registered_function_metadata,
+    get_registered_function_factory,
+    get_function_metadata,
+)
+from .function_factory import FunctionFactory
+
+# Built-in functions
+from .sum import Sum
+from .avg import Avg
+from .collect import Collect
+from .join import Join
+from .keys import Keys
+from .rand import Rand
+from .range_ import Range
+from .replace import Replace
+from .round_ import Round
+from .size import Size
+from .split import Split
+from .stringify import Stringify
+from .to_json import ToJson
+from .type_ import Type
+from .functions import Functions
+from .predicate_sum import PredicateSum
+
+__all__ = [
+    # Base classes
+    "Function",
+    "AggregateFunction",
+    "AsyncFunction",
+    "PredicateFunction",
+    "ReducerElement",
+    "ValueHolder",
+    "FunctionCategory",
+    "ParameterSchema",
+    "OutputSchema",
+    "FunctionMetadata",
+    "FunctionDef",
+    "FunctionDefOptions",
+    "get_registered_function_metadata",
+    "get_registered_function_factory",
+    "get_function_metadata",
+    "FunctionFactory",
+    # Built-in functions
+    "Sum",
+    "Avg",
+    "Collect",
+    "Join",
+    "Keys",
+    "Rand",
+    "Range",
+    "Replace",
+    "Round",
+    "Size",
+    "Split",
+    "Stringify",
+    "ToJson",
+    "Type",
+    "Functions",
+    "PredicateSum",
+]

package/flowquery-py/src/parsing/functions/aggregate_function.py

@@ -0,0 +1,60 @@
+"""Base class for aggregate functions that reduce multiple values to a single value."""
+
+from typing import Any, Optional
+
+from .function import Function
+from .reducer_element import ReducerElement
+
+
+class AggregateFunction(Function):
+    """Base class for aggregate functions that reduce multiple values to a single value.
+    
+    Aggregate functions like SUM, AVG, and COLLECT process multiple input values
+    and produce a single output. They cannot be nested within other aggregate functions.
+    
+    Example:
+        sum_func = Sum()
+        # Used in: RETURN SUM(values)
+    """
+
+    def __init__(self, name: Optional[str] = None):
+        """Creates a new AggregateFunction with the given name.
+        
+        Args:
+            name: The function name
+        """
+        super().__init__(name)
+        self._overridden: Any = None
+
+    def reduce(self, value: ReducerElement) -> None:
+        """Processes a value during the aggregation phase.
+        
+        Args:
+            value: The element to aggregate
+            
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError("Method not implemented.")
+
+    def element(self) -> ReducerElement:
+        """Creates a reducer element for this aggregate function.
+        
+        Returns:
+            A ReducerElement instance
+            
+        Raises:
+            NotImplementedError: If not implemented by subclass
+        """
+        raise NotImplementedError("Method not implemented.")
+
+    @property
+    def overridden(self) -> Any:
+        return self._overridden
+
+    @overridden.setter
+    def overridden(self, value: Any) -> None:
+        self._overridden = value
+
+    def value(self) -> Any:
+        return self._overridden

package/flowquery-py/src/parsing/functions/async_function.py

@@ -0,0 +1,62 @@
+"""Represents an async data provider function call for use in LOAD operations."""
+
+from typing import Any, AsyncGenerator, List
+
+from ..ast_node import ASTNode
+from .function import Function
+
+
+class AsyncFunction(Function):
+    """Represents an async data provider function call for use in LOAD operations.
+    
+    This class holds the function name and arguments, and provides async iteration
+    over the results from a registered async data provider.
+    
+    Example:
+        # Used in: LOAD JSON FROM myDataSource('arg1', 'arg2') AS data
+        async_func = AsyncFunction("myDataSource")
+        async_func.parameters = [arg1_node, arg2_node]
+        async for item in async_func.execute():
+            print(item)
+    """
+
+    @property
+    def parameters(self) -> List[ASTNode]:
+        return self.children
+
+    @parameters.setter
+    def parameters(self, nodes: List[ASTNode]) -> None:
+        """Sets the function parameters.
+        
+        Args:
+            nodes: Array of AST nodes representing the function arguments
+        """
+        self.children = nodes
+
+    def get_arguments(self) -> List[Any]:
+        """Evaluates all parameters and returns their values.
+        Used by the framework to pass arguments to generate().
+        
+        Returns:
+            Array of parameter values
+        """
+        return [child.value() for child in self.children]
+
+    async def generate(self, *args: Any) -> AsyncGenerator[Any, None]:
+        """Generates the async data provider function results.
+        
+        Subclasses override this method with their own typed parameters.
+        The framework automatically evaluates the AST children and spreads
+        them as arguments when calling this method.
+        
+        Args:
+            args: Arguments passed from the query (e.g., myFunc(arg1, arg2))
+            
+        Yields:
+            Data items from the async provider
+            
+        Raises:
+            NotImplementedError: If the function is not registered as an async provider
+        """
+        raise NotImplementedError("generate method must be overridden in subclasses.")
+        yield  # Make this a generator

package/flowquery-py/src/parsing/functions/avg.py

@@ -0,0 +1,55 @@
+"""Avg aggregate function."""
+
+from typing import Optional
+
+from .aggregate_function import AggregateFunction
+from .reducer_element import ReducerElement
+from .function_metadata import FunctionDef
+
+
+class AvgReducerElement(ReducerElement):
+    """Reducer element for Avg aggregate function."""
+
+    def __init__(self):
+        self._count: int = 0
+        self._sum: Optional[float] = None
+
+    @property
+    def value(self) -> Optional[float]:
+        if self._sum is None:
+            return None
+        return self._sum / self._count
+
+    @value.setter
+    def value(self, val: float) -> None:
+        self._count += 1
+        if self._sum is not None:
+            self._sum += val
+        else:
+            self._sum = val
+
+
+@FunctionDef({
+    "description": "Calculates the average of numeric values across grouped rows",
+    "category": "aggregate",
+    "parameters": [
+        {"name": "value", "description": "Numeric value to average", "type": "number"}
+    ],
+    "output": {"description": "Average of all values", "type": "number", "example": 50},
+    "examples": ["WITH [10, 20, 30] AS nums UNWIND nums AS n RETURN avg(n)"]
+})
+class Avg(AggregateFunction):
+    """Avg aggregate function.
+    
+    Calculates the average of numeric values across grouped rows.
+    """
+
+    def __init__(self):
+        super().__init__("avg")
+        self._expected_parameter_count = 1
+
+    def reduce(self, element: AvgReducerElement) -> None:
+        element.value = self.first_child().value()
+
+    def element(self) -> AvgReducerElement:
+        return AvgReducerElement()

package/flowquery-py/src/parsing/functions/collect.py

@@ -0,0 +1,75 @@
+"""Collect aggregate function."""
+
+from typing import Any, Dict, List, Union
+import json
+
+from .aggregate_function import AggregateFunction
+from .reducer_element import ReducerElement
+from .function_metadata import FunctionDef
+
+
+class CollectReducerElement(ReducerElement):
+    """Reducer element for Collect aggregate function."""
+
+    def __init__(self):
+        self._value: List[Any] = []
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
+    @value.setter
+    def value(self, val: Any) -> None:
+        self._value.append(val)
+
+
+class DistinctCollectReducerElement(ReducerElement):
+    """Reducer element for Collect aggregate function with DISTINCT."""
+
+    def __init__(self):
+        self._value: Dict[str, Any] = {}
+
+    @property
+    def value(self) -> Any:
+        return list(self._value.values())
+
+    @value.setter
+    def value(self, val: Any) -> None:
+        key: str = json.dumps(val, sort_keys=True, default=str)
+        if key not in self._value:
+            self._value[key] = val
+
+
+@FunctionDef({
+    "description": "Collects values into an array across grouped rows",
+    "category": "aggregate",
+    "parameters": [
+        {"name": "value", "description": "Value to collect", "type": "any"}
+    ],
+    "output": {"description": "Array of collected values", "type": "array", "example": [1, 2, 3]},
+    "examples": ["WITH [1, 2, 3] AS nums UNWIND nums AS n RETURN collect(n)"]
+})
+class Collect(AggregateFunction):
+    """Collect aggregate function.
+    
+    Collects values into an array across grouped rows.
+    """
+
+    def __init__(self):
+        super().__init__("collect")
+        self._expected_parameter_count = 1
+        self._distinct: bool = False
+
+    def reduce(self, element: CollectReducerElement) -> None:
+        element.value = self.first_child().value()
+
+    def element(self) -> Union[CollectReducerElement, DistinctCollectReducerElement]:
+        return DistinctCollectReducerElement() if self._distinct else CollectReducerElement()
+
+    @property
+    def distinct(self) -> bool:
+        return self._distinct
+
+    @distinct.setter
+    def distinct(self, val: bool) -> None:
+        self._distinct = val