flowquery 1.0.20 → 1.0.21

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

@@ -1,18 +1,26 @@
 """Main parser for FlowQuery statements."""
 
-from typing import Dict, Iterator, List, Optional
+import sys
+from typing import Dict, Iterator, List, Optional, Tuple, cast
 
+from ..graph.hops import Hops
+from ..graph.node import Node
+from ..graph.node_reference import NodeReference
+from ..graph.pattern import Pattern
+from ..graph.pattern_expression import PatternExpression
+from ..graph.relationship import Relationship
+from ..graph.relationship_reference import RelationshipReference
 from ..tokenization.token import Token
 from ..utils.object_utils import ObjectUtils
 from .alias import Alias
 from .alias_option import AliasOption
 from .ast_node import ASTNode
 from .base_parser import BaseParser
-from .context import Context
 from .components.from_ import From
 from .components.headers import Headers
 from .components.null import Null
 from .components.post import Post
+from .context import Context
 from .data_structures.associative_array import AssociativeArray
 from .data_structures.json_array import JSONArray
 from .data_structures.key_value_pair import KeyValuePair
@@ -30,12 +38,14 @@ from .functions.function import Function
 from .functions.function_factory import FunctionFactory
 from .functions.predicate_function import PredicateFunction
 from .logic.case import Case
-from .logic.when import When
-from .logic.then import Then
 from .logic.else_ import Else
+from .logic.then import Then
+from .logic.when import When
 from .operations.aggregated_return import AggregatedReturn
 from .operations.aggregated_with import AggregatedWith
 from .operations.call import Call
+from .operations.create_node import CreateNode
+from .operations.create_relationship import CreateRelationship
 from .operations.limit import Limit
 from .operations.load import Load
 from .operations.match import Match
@@ -44,22 +54,15 @@ from .operations.return_op import Return
 from .operations.unwind import Unwind
 from .operations.where import Where
 from .operations.with_op import With
-from ..graph.node import Node
-from ..graph.node_reference import NodeReference
-from ..graph.pattern import Pattern
-from ..graph.pattern_expression import PatternExpression
-from ..graph.relationship import Relationship
-from .operations.create_node import CreateNode
-from .operations.create_relationship import CreateRelationship
 
 
 class Parser(BaseParser):
     """Main parser for FlowQuery statements.
-    
+
     Parses FlowQuery declarative query language statements into an Abstract Syntax Tree (AST).
     Supports operations like WITH, UNWIND, RETURN, LOAD, WHERE, and LIMIT, along with
     expressions, functions, data structures, and logical constructs.
-    
+
     Example:
         parser = Parser()
         ast = parser.parse("unwind [1, 2, 3, 4, 5] as num return num")
@@ -73,13 +76,13 @@ class Parser(BaseParser):
 
     def parse(self, statement: str) -> ASTNode:
         """Parses a FlowQuery statement into an Abstract Syntax Tree.
-        
+
         Args:
             statement: The FlowQuery statement to parse
-            
+
         Returns:
             The root AST node containing the parsed structure
-            
+
         Raises:
             ValueError: If the statement is malformed or contains syntax errors
         """
@@ -90,32 +93,32 @@ class Parser(BaseParser):
         root = ASTNode()
         previous: Optional[Operation] = None
         operation: Optional[Operation] = None
-        
+
         while not self.token.is_eof():
             if root.child_count() > 0:
                 self._expect_and_skip_whitespace_and_comments()
             else:
                 self._skip_whitespace_and_comments()
-            
+
             operation = self._parse_operation()
             if operation is None and not is_sub_query:
                 raise ValueError("Expected one of WITH, UNWIND, RETURN, LOAD, OR CALL")
             elif operation is None and is_sub_query:
                 return root
-            
+
             if self._returns > 1:
                 raise ValueError("Only one RETURN statement is allowed")
-            
+
             if isinstance(previous, Call) and not previous.has_yield:
                 raise ValueError(
                     "CALL operations must have a YIELD clause unless they are the last operation"
                 )
-            
+
             if previous is not None:
                 previous.add_sibling(operation)
             else:
                 root.add_child(operation)
-            
+
             where = self._parse_where()
             if where is not None:
                 if isinstance(operation, Return):
@@ -123,17 +126,17 @@ class Parser(BaseParser):
                 else:
                     operation.add_sibling(where)
                     operation = where
-            
+
             limit = self._parse_limit()
             if limit is not None:
                 operation.add_sibling(limit)
                 operation = limit
-            
+
             previous = operation
-        
+
         if not isinstance(operation, (Return, Call, CreateNode, CreateRelationship)):
             raise ValueError("Last statement must be a RETURN, WHERE, CALL, or CREATE statement")
-        
+
         return root
 
     def _parse_operation(self) -> Optional[Operation]:
@@ -156,7 +159,7 @@ class Parser(BaseParser):
         if len(expressions) == 0:
             raise ValueError("Expected expression")
         if any(expr.has_reducers() for expr in expressions):
-            return AggregatedWith(expressions)
+            return AggregatedWith(expressions)  # type: ignore[return-value]
         return With(expressions)
 
     def _parse_unwind(self) -> Optional[Unwind]:
@@ -228,7 +231,7 @@ class Parser(BaseParser):
         self._expect_and_skip_whitespace_and_comments()
         from_node = From()
         load.add_child(from_node)
-        
+
         # Check if source is async function
         async_func = self._parse_async_function()
         if async_func is not None:
@@ -238,7 +241,7 @@ class Parser(BaseParser):
             if expression is None:
                 raise ValueError("Expected expression or async function")
             from_node.add_child(expression)
-        
+
         self._expect_and_skip_whitespace_and_comments()
         if self.token.is_headers():
             headers = Headers()
@@ -250,7 +253,7 @@ class Parser(BaseParser):
             headers.add_child(header)
             load.add_child(headers)
             self._expect_and_skip_whitespace_and_comments()
-        
+
         if self.token.is_post():
             post = Post()
             self.set_next_token()
@@ -261,7 +264,7 @@ class Parser(BaseParser):
             post.add_child(payload)
             load.add_child(post)
             self._expect_and_skip_whitespace_and_comments()
-        
+
         alias = self._parse_alias()
         if alias is not None:
             load.add_child(alias)
@@ -288,7 +291,7 @@ class Parser(BaseParser):
             expressions = list(self._parse_expressions(AliasOption.OPTIONAL))
             if len(expressions) == 0:
                 raise ValueError("Expected at least one expression")
-            call.yielded = expressions
+            call.yielded = expressions  # type: ignore[assignment]
         return call
 
     def _parse_match(self) -> Optional[Match]:
@@ -311,11 +314,11 @@ class Parser(BaseParser):
             raise ValueError("Expected VIRTUAL")
         self.set_next_token()
         self._expect_and_skip_whitespace_and_comments()
-        
+
         node = self._parse_node()
         if node is None:
             raise ValueError("Expected node definition")
-        
+
         relationship: Optional[Relationship] = None
         if self.token.is_subtract() and self.peek() and self.peek().is_opening_bracket():
             self.set_next_token()  # skip -
@@ -341,17 +344,17 @@ class Parser(BaseParser):
                 raise ValueError("Expected target node definition")
             relationship = Relationship()
             relationship.type = rel_type
-        
+
         self._expect_and_skip_whitespace_and_comments()
         if not self.token.is_as():
             raise ValueError("Expected AS")
         self.set_next_token()
         self._expect_and_skip_whitespace_and_comments()
-        
+
         query = self._parse_sub_query()
         if query is None:
             raise ValueError("Expected sub-query")
-        
+
         if relationship is not None:
             return CreateRelationship(relationship, query)
         else:
@@ -416,7 +419,7 @@ class Parser(BaseParser):
 
     def _parse_pattern_expression(self) -> Optional[PatternExpression]:
         """Parse a pattern expression for WHERE clauses.
-        
+
         PatternExpression is used to test if a graph pattern exists.
         It must start with a NodeReference (referencing an existing variable).
         """
@@ -459,17 +462,17 @@ class Parser(BaseParser):
             raise ValueError("Expected node label identifier")
         if self.token.is_colon() and peek is not None and peek.is_identifier():
             self.set_next_token()
-            label = self.token.value
+            label = cast(str, self.token.value)  # Guaranteed by is_identifier check
             self.set_next_token()
         self._skip_whitespace_and_comments()
         node = Node()
         node.label = label
+        node.properties = dict(self._parse_properties())
         if label is not None and identifier is not None:
             node.identifier = identifier
             self._variables[identifier] = node
         elif identifier is not None:
             reference = self._variables.get(identifier)
-            from ..graph.node_reference import NodeReference
             if reference is None or not isinstance(reference, Node):
                 raise ValueError(f"Undefined node reference: {identifier}")
             node = NodeReference(node, reference)
@@ -479,7 +482,9 @@ class Parser(BaseParser):
         return node
 
     def _parse_relationship(self) -> Optional[Relationship]:
+        direction = "right"
         if self.token.is_less_than() and self.peek() is not None and self.peek().is_subtract():
+            direction = "left"
             self.set_next_token()
             self.set_next_token()
         elif self.token.is_subtract():
@@ -501,6 +506,7 @@ class Parser(BaseParser):
         rel_type: str = self.token.value or ""
         self.set_next_token()
         hops = self._parse_relationship_hops()
+        properties: Dict[str, Expression] = dict(self._parse_properties())
         if not self.token.is_closing_bracket():
             raise ValueError("Expected closing bracket for relationship definition")
         self.set_next_token()
@@ -510,12 +516,13 @@ class Parser(BaseParser):
         if self.token.is_greater_than():
             self.set_next_token()
         relationship = Relationship()
+        relationship.direction = direction
+        relationship.properties = properties
         if rel_type is not None and variable is not None:
             relationship.identifier = variable
             self._variables[variable] = relationship
         elif variable is not None:
             reference = self._variables.get(variable)
-            from ..graph.relationship_reference import RelationshipReference
             if reference is None or not isinstance(reference, Relationship):
                 raise ValueError(f"Undefined relationship reference: {variable}")
             relationship = RelationshipReference(relationship, reference)
@@ -524,9 +531,40 @@ class Parser(BaseParser):
         relationship.type = rel_type
         return relationship
 
-    def _parse_relationship_hops(self):
-        import sys
-        from ..graph.hops import Hops
+    def _parse_properties(self) -> Iterator[Tuple[str, Expression]]:
+        parts: int = 0
+        while True:
+            self._skip_whitespace_and_comments()
+            if not self.token.is_opening_brace() and parts == 0:
+                return
+            elif not self.token.is_opening_brace() and parts > 0:
+                raise ValueError("Expected opening brace")
+            self.set_next_token()
+            self._skip_whitespace_and_comments()
+            if not self.token.is_identifier():
+                raise ValueError("Expected identifier")
+            key: str = self.token.value or ""
+            self.set_next_token()
+            self._skip_whitespace_and_comments()
+            if not self.token.is_colon():
+                raise ValueError("Expected colon")
+            self.set_next_token()
+            self._skip_whitespace_and_comments()
+            expression = self._parse_expression()
+            if expression is None:
+                raise ValueError("Expected expression")
+            self._skip_whitespace_and_comments()
+            if not self.token.is_closing_brace():
+                raise ValueError("Expected closing brace")
+            self.set_next_token()
+            yield (key, expression)
+            self._skip_whitespace_and_comments()
+            if not self.token.is_comma():
+                break
+            self.set_next_token()
+            parts += 1
+
+    def _parse_relationship_hops(self) -> Optional[Hops]:
         if not self.token.is_multiply():
             return None
         hops = Hops()
@@ -572,10 +610,11 @@ class Parser(BaseParser):
                 alias = self._parse_alias()
                 if isinstance(expression.first_child(), Reference) and alias is None:
                     reference = expression.first_child()
+                    assert isinstance(reference, Reference)  # For type narrowing
                     expression.set_alias(reference.identifier)
                     self._variables[reference.identifier] = expression
-                elif (alias_option == AliasOption.REQUIRED and 
-                      alias is None and 
+                elif (alias_option == AliasOption.REQUIRED and
+                      alias is None and
                       not isinstance(expression.first_child(), Reference)):
                     raise ValueError("Alias required")
                 elif alias_option == AliasOption.NOT_ALLOWED and alias is not None:
@@ -607,7 +646,15 @@ class Parser(BaseParser):
                 lookup = self._parse_lookup(func)
                 expression.add_node(lookup)
                 return True
-        elif self.token.is_left_parenthesis() and self.peek() is not None and (self.peek().is_identifier() or self.peek().is_colon() or self.peek().is_right_parenthesis()):
+        elif (
+            self.token.is_left_parenthesis()
+            and self.peek() is not None
+            and (
+                self.peek().is_identifier()
+                or self.peek().is_colon()
+                or self.peek().is_right_parenthesis()
+            )
+        ):
             # Possible graph pattern expression
             pattern = self._parse_pattern_expression()
             if pattern is not None:
@@ -675,7 +722,7 @@ class Parser(BaseParser):
             else:
                 break
             self.set_next_token()
-        
+
         if expression.nodes_added():
             expression.finish()
             return expression
@@ -683,7 +730,7 @@ class Parser(BaseParser):
 
     def _parse_lookup(self, node: ASTNode) -> ASTNode:
         variable = node
-        lookup = None
+        lookup: Lookup | RangeLookup | None = None
         while True:
             if self.token.is_dot():
                 self.set_next_token()
@@ -870,30 +917,30 @@ class Parser(BaseParser):
         name = self.token.value or ""
         if not self.peek() or not self.peek().is_left_parenthesis():
             return None
-        
+
         try:
             func = FunctionFactory.create(name)
         except ValueError:
             raise ValueError(f"Unknown function: {name}")
-        
+
         # Check for nested aggregate functions
         if isinstance(func, AggregateFunction) and self._context.contains_type(AggregateFunction):
             raise ValueError("Aggregate functions cannot be nested")
-        
+
         self._context.push(func)
         self.set_next_token()  # skip function name
         self.set_next_token()  # skip left parenthesis
         self._skip_whitespace_and_comments()
-        
+
         # Check for DISTINCT keyword
         if self.token.is_distinct():
             func.distinct = True
             self.set_next_token()
             self._expect_and_skip_whitespace_and_comments()
-        
+
         params = list(self._parse_function_parameters())
         func.parameters = params
-        
+
         if not self.token.is_right_parenthesis():
             raise ValueError("Expected right parenthesis")
         self.set_next_token()
@@ -910,11 +957,11 @@ class Parser(BaseParser):
         if not self.token.is_left_parenthesis():
             raise ValueError("Expected left parenthesis")
         self.set_next_token()
-        
+
         func = FunctionFactory.create_async(name)
         params = list(self._parse_function_parameters())
         func.parameters = params
-        
+
         if not self.token.is_right_parenthesis():
             raise ValueError("Expected right parenthesis")
         self.set_next_token()

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

@@ -9,7 +9,6 @@ from .components.text import Text
 from .expressions.boolean import Boolean
 from .expressions.identifier import Identifier
 from .expressions.number import Number
-from .expressions.string import String
 from .expressions.operator import (
     Add,
     And,
@@ -28,6 +27,7 @@ from .expressions.operator import (
     Power,
     Subtract,
 )
+from .expressions.string import String
 from .logic.else_ import Else
 from .logic.end import End
 from .logic.then import Then
@@ -103,7 +103,7 @@ class TokenToNode:
             elif token.is_null():
                 return Null()
         elif token.is_boolean():
-            return Boolean(token.value)
+            return Boolean(token.value or "")
         else:
             raise ValueError("Unknown token")
         return ASTNode()

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

@@ -1,13 +1,13 @@
 """Tokenization module for FlowQuery."""
 
-from .tokenizer import Tokenizer
-from .token import Token
-from .token_type import TokenType
 from .keyword import Keyword
 from .operator import Operator
+from .string_walker import StringWalker
 from .symbol import Symbol
+from .token import Token
 from .token_mapper import TokenMapper
-from .string_walker import StringWalker
+from .token_type import TokenType
+from .tokenizer import Tokenizer
 from .trie import Trie
 
 __all__ = [

package/flowquery-py/src/tokenization/keyword.py

@@ -5,7 +5,7 @@ from enum import Enum
 
 class Keyword(Enum):
     """Enumeration of all keywords in FlowQuery."""
-    
+
     RETURN = "RETURN"
     MATCH = "MATCH"
     WHERE = "WHERE"

package/flowquery-py/src/tokenization/operator.py

@@ -5,7 +5,7 @@ from enum import Enum
 
 class Operator(Enum):
     """Enumeration of all operators in FlowQuery."""
-    
+
     # Arithmetic
     ADD = "+"
     SUBTRACT = "-"

package/flowquery-py/src/tokenization/string_walker.py

@@ -5,10 +5,10 @@ from ..utils.string_utils import StringUtils
 
 class StringWalker:
     """Utility class for walking through a string character by character during tokenization.
-    
+
     Provides methods to check for specific character patterns, move through the string,
     and extract substrings. Used by the Tokenizer to process input text.
-    
+
     Example:
         walker = StringWalker("WITH x as variable")
         while not walker.is_at_end:
@@ -17,7 +17,7 @@ class StringWalker:
 
     def __init__(self, text: str):
         """Creates a new StringWalker for the given text.
-        
+
         Args:
             text: The input text to walk through
         """
@@ -89,7 +89,7 @@ class StringWalker:
         return self.current_char == '\\' and self.next_char == char
 
     def escaped_brace(self) -> bool:
-        return ((self.current_char == '{' and self.next_char == '{') or 
+        return ((self.current_char == '{' and self.next_char == '{') or
                 (self.current_char == '}' and self.next_char == '}'))
 
     def opening_brace(self) -> bool:

package/flowquery-py/src/tokenization/symbol.py

@@ -5,7 +5,7 @@ from enum import Enum
 
 class Symbol(Enum):
     """Enumeration of all symbols in FlowQuery."""
-    
+
     LEFT_PARENTHESIS = "("
     RIGHT_PARENTHESIS = ")"
     COMMA = ","

package/flowquery-py/src/tokenization/token.py

@@ -1,25 +1,24 @@
 """Represents a single token in the FlowQuery language."""
 
 from __future__ import annotations
-from typing import TYPE_CHECKING, Optional, Any
 
-from .token_type import TokenType
+from typing import Optional
+
+from ..parsing.ast_node import ASTNode
+from ..utils.string_utils import StringUtils
 from .keyword import Keyword
 from .operator import Operator
 from .symbol import Symbol
-from ..utils.string_utils import StringUtils
-
-if TYPE_CHECKING:
-    from ..parsing.ast_node import ASTNode
+from .token_type import TokenType
 
 
 class Token:
     """Represents a single token in the FlowQuery language.
-    
+
     Tokens are the atomic units of lexical analysis, produced by the tokenizer
     and consumed by the parser. Each token has a type (keyword, operator, identifier, etc.)
     and an optional value.
-    
+
     Example:
         with_token = Token.WITH()
         ident_token = Token.IDENTIFIER("myVar")
@@ -28,7 +27,7 @@ class Token:
 
     def __init__(self, type_: TokenType, value: Optional[str] = None):
         """Creates a new Token instance.
-        
+
         Args:
             type_: The type of the token
             value: The optional value associated with the token
@@ -41,10 +40,10 @@ class Token:
 
     def equals(self, other: Token) -> bool:
         """Checks if this token equals another token.
-        
+
         Args:
             other: The token to compare against
-            
+
         Returns:
             True if tokens are equal, False otherwise
         """
@@ -82,6 +81,7 @@ class Token:
 
     @property
     def node(self) -> ASTNode:
+        # Import at runtime to avoid circular dependency
         from ..parsing.token_to_node import TokenToNode
         return TokenToNode.convert(self)
 

package/flowquery-py/src/tokenization/token_mapper.py

@@ -1,6 +1,7 @@
 """Maps string values to tokens using a Trie for efficient lookup."""
 
-from typing import Optional
+from enum import Enum
+from typing import Optional, Type
 
 from .token import Token
 from .trie import Trie
@@ -8,24 +9,24 @@ from .trie import Trie
 
 class TokenMapper:
     """Maps string values to tokens using a Trie for efficient lookup.
-    
+
     Takes an enum of keywords, operators, or symbols and builds a trie
     for fast token matching during tokenization.
-    
+
     Example:
         mapper = TokenMapper(Keyword)
         token = mapper.map("WITH")
     """
 
-    def __init__(self, enum_class):
+    def __init__(self, enum_class: Type[Enum]) -> None:
         """Creates a TokenMapper from an enum of token values.
-        
+
         Args:
             enum_class: An enum class containing token values
         """
         self._trie = Trie()
         self._enum = enum_class
-        
+
         for member in enum_class:
             token = Token.method(member.name)
             if token is not None and token.value is not None:
@@ -33,10 +34,10 @@ class TokenMapper:
 
     def map(self, value: str) -> Optional[Token]:
         """Maps a string value to its corresponding token.
-        
+
         Args:
             value: The string value to map
-            
+
         Returns:
             The matched token, or None if no match found
         """
@@ -45,7 +46,7 @@ class TokenMapper:
     @property
     def last_found(self) -> Optional[str]:
         """Gets the last matched string from the most recent map operation.
-        
+
         Returns:
             The last found string, or None if no match
         """

package/flowquery-py/src/tokenization/token_type.py

@@ -5,7 +5,7 @@ from enum import Enum
 
 class TokenType(Enum):
     """Enumeration of all token types in FlowQuery."""
-    
+
     KEYWORD = "KEYWORD"
     BOOLEAN = "BOOLEAN"
     OPERATOR = "OPERATOR"