flowquery 1.0.34 → 1.0.36

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

@@ -0,0 +1,186 @@
+"""Shared utility functions for temporal (date/time) operations.
+
+These helpers are used by the datetime_, date_, time_, localdatetime,
+localtime, and timestamp functions.
+"""
+
+from datetime import date, datetime, timezone
+from typing import Any, Dict
+
+
+def iso_day_of_week(d: date) -> int:
+    """Computes the ISO day of the week (1 = Monday, 7 = Sunday) matching Neo4j convention."""
+    return d.isoweekday()
+
+
+def day_of_year(d: date) -> int:
+    """Computes the day of the year (1-based)."""
+    return d.timetuple().tm_yday
+
+
+def quarter(month: int) -> int:
+    """Computes the quarter (1-4) from a month (1-12)."""
+    return (month - 1) // 3 + 1
+
+
+def parse_temporal_arg(arg: Any, fn_name: str) -> datetime:
+    """Parses a temporal argument (string, number, or map) into a datetime object.
+
+    Args:
+        arg: The argument to parse (string, number, or dict with components)
+        fn_name: The calling function name for error messages
+
+    Returns:
+        A datetime object
+    """
+    if isinstance(arg, str):
+        try:
+            return datetime.fromisoformat(arg.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError(f"{fn_name}(): Invalid temporal string: '{arg}'")
+
+    if isinstance(arg, (int, float)):
+        # Treat as epoch milliseconds
+        return datetime.fromtimestamp(arg / 1000, tz=timezone.utc)
+
+    if isinstance(arg, dict):
+        # Map-style construction: {year, month, day, hour, minute, second, millisecond}
+        now = datetime.now()
+        year = arg.get("year", now.year)
+        month = arg.get("month", 1)
+        day = arg.get("day", 1)
+        hour = arg.get("hour", 0)
+        minute = arg.get("minute", 0)
+        second = arg.get("second", 0)
+        millisecond = arg.get("millisecond", 0)
+        return datetime(year, month, day, hour, minute, second, millisecond * 1000)
+
+    raise ValueError(
+        f"{fn_name}(): Expected a string, number (epoch millis), or map argument, "
+        f"got {type(arg).__name__}"
+    )
+
+
+def build_datetime_object(d: datetime, utc: bool) -> Dict[str, Any]:
+    """Builds a datetime result object with full temporal properties.
+
+    Args:
+        d: The datetime object
+        utc: If True, use UTC values; if False, use local values
+
+    Returns:
+        A dict with year, month, day, hour, minute, second, millisecond,
+        epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted
+    """
+    if utc:
+        if d.tzinfo is None:
+            d = d.replace(tzinfo=timezone.utc)
+        d_utc = d.astimezone(timezone.utc)
+        year = d_utc.year
+        month = d_utc.month
+        day = d_utc.day
+        hour = d_utc.hour
+        minute = d_utc.minute
+        second = d_utc.second
+        millisecond = d_utc.microsecond // 1000
+        formatted = d_utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{millisecond:03d}Z"
+    else:
+        if d.tzinfo is not None:
+            d = d.astimezone(tz=None).replace(tzinfo=None)
+        year = d.year
+        month = d.month
+        day = d.day
+        hour = d.hour
+        minute = d.minute
+        second = d.second
+        millisecond = d.microsecond // 1000
+        formatted = d.strftime("%Y-%m-%dT%H:%M:%S.") + f"{millisecond:03d}"
+
+    date_part = date(year, month, day)
+    epoch_millis = int(d.timestamp() * 1000) if d.tzinfo else int(
+        datetime(year, month, day, hour, minute, second, millisecond * 1000).timestamp() * 1000
+    )
+
+    return {
+        "year": year,
+        "month": month,
+        "day": day,
+        "hour": hour,
+        "minute": minute,
+        "second": second,
+        "millisecond": millisecond,
+        "epochMillis": epoch_millis,
+        "epochSeconds": epoch_millis // 1000,
+        "dayOfWeek": iso_day_of_week(date_part),
+        "dayOfYear": day_of_year(date_part),
+        "quarter": quarter(month),
+        "formatted": formatted,
+    }
+
+
+def build_date_object(d: datetime) -> Dict[str, Any]:
+    """Builds a date result object (no time component).
+
+    Args:
+        d: The datetime object
+
+    Returns:
+        A dict with year, month, day, epochMillis, dayOfWeek, dayOfYear, quarter, formatted
+    """
+    year = d.year
+    month = d.month
+    day_val = d.day
+
+    date_only = datetime(year, month, day_val)
+    epoch_millis = int(date_only.timestamp() * 1000)
+
+    date_part = date(year, month, day_val)
+
+    return {
+        "year": year,
+        "month": month,
+        "day": day_val,
+        "epochMillis": epoch_millis,
+        "dayOfWeek": iso_day_of_week(date_part),
+        "dayOfYear": day_of_year(date_part),
+        "quarter": quarter(month),
+        "formatted": f"{year}-{month:02d}-{day_val:02d}",
+    }
+
+
+def build_time_object(d: datetime, utc: bool) -> Dict[str, Any]:
+    """Builds a time result object (no date component).
+
+    Args:
+        d: The datetime object
+        utc: If True, use UTC values; if False, use local values
+
+    Returns:
+        A dict with hour, minute, second, millisecond, formatted
+    """
+    if utc:
+        if d.tzinfo is None:
+            d = d.replace(tzinfo=timezone.utc)
+        d_utc = d.astimezone(timezone.utc)
+        hour = d_utc.hour
+        minute = d_utc.minute
+        second = d_utc.second
+        millisecond = d_utc.microsecond // 1000
+    else:
+        if d.tzinfo is not None:
+            d = d.astimezone(tz=None).replace(tzinfo=None)
+        hour = d.hour
+        minute = d.minute
+        second = d.second
+        millisecond = d.microsecond // 1000
+
+    time_part = f"{hour:02d}:{minute:02d}:{second:02d}.{millisecond:03d}"
+    formatted = f"{time_part}Z" if utc else time_part
+
+    return {
+        "hour": hour,
+        "minute": minute,
+        "second": second,
+        "millisecond": millisecond,
+        "formatted": formatted,
+    }

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

@@ -0,0 +1,59 @@
+"""Time function."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+from .temporal_utils import build_time_object, parse_temporal_arg
+
+
+@FunctionDef({
+    "description": (
+        "Returns a time value. With no arguments returns the current UTC time. "
+        "Accepts an ISO 8601 time string or a map of components (hour, minute, second, millisecond)."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": "Optional. An ISO 8601 time string (HH:MM:SS) or a map of components.",
+            "type": "string",
+            "required": False,
+        },
+    ],
+    "output": {
+        "description": "A time object with properties: hour, minute, second, millisecond, formatted",
+        "type": "object",
+    },
+    "examples": [
+        "RETURN time() AS now",
+        "RETURN time('12:30:00') AS t",
+        "WITH time() AS t RETURN t.hour, t.minute",
+    ],
+})
+class Time(Function):
+    """Time function.
+
+    Returns a time value (with timezone offset awareness).
+    When called with no arguments, returns the current UTC time.
+    When called with a string argument, parses it.
+
+    Equivalent to Neo4j's time() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("time")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("time() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "time")
+        else:
+            d = datetime.now(timezone.utc)
+
+        return build_time_object(d, utc=True)

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

@@ -0,0 +1,39 @@
+"""Timestamp function."""
+
+import time
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": (
+        "Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z). "
+        "Equivalent to Neo4j's timestamp() function."
+    ),
+    "category": "scalar",
+    "parameters": [],
+    "output": {
+        "description": "Milliseconds since Unix epoch",
+        "type": "number",
+        "example": 1718450000000,
+    },
+    "examples": [
+        "RETURN timestamp() AS ts",
+        "WITH timestamp() AS before, timestamp() AS after RETURN after - before",
+    ],
+})
+class Timestamp(Function):
+    """Timestamp function.
+
+    Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).
+    Equivalent to Neo4j's timestamp() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("timestamp")
+        self._expected_parameter_count = 0
+
+    def value(self) -> Any:
+        return int(time.time() * 1000)

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

@@ -0,0 +1,46 @@
+"""ToFloat function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Converts a value to a floating point number",
+    "category": "scalar",
+    "parameters": [
+        {"name": "value", "description": "The value to convert to a float", "type": "any"}
+    ],
+    "output": {"description": "The floating point representation of the value", "type": "number", "example": 3.14},
+    "examples": [
+        'RETURN toFloat("3.14")',
+        "RETURN toFloat(42)",
+        "RETURN toFloat(true)"
+    ]
+})
+class ToFloat(Function):
+    """ToFloat function.
+
+    Converts a value to a floating point number.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("tofloat")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        val = self.get_children()[0].value()
+        if val is None:
+            return None
+        if isinstance(val, bool):
+            return 1.0 if val else 0.0
+        if isinstance(val, (int, float)):
+            return float(val)
+        if isinstance(val, str):
+            trimmed = val.strip()
+            try:
+                return float(trimmed)
+            except (ValueError, OverflowError):
+                raise ValueError(f'Cannot convert string "{val}" to float')
+        raise ValueError("toFloat() expects a number, string, or boolean")

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

@@ -0,0 +1,46 @@
+"""ToInteger function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Converts a value to an integer",
+    "category": "scalar",
+    "parameters": [
+        {"name": "value", "description": "The value to convert to an integer", "type": "any"}
+    ],
+    "output": {"description": "The integer representation of the value", "type": "number", "example": 42},
+    "examples": [
+        'RETURN toInteger("42")',
+        "RETURN toInteger(3.14)",
+        "RETURN toInteger(true)"
+    ]
+})
+class ToInteger(Function):
+    """ToInteger function.
+
+    Converts a value to an integer.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("tointeger")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        val = self.get_children()[0].value()
+        if val is None:
+            return None
+        if isinstance(val, bool):
+            return 1 if val else 0
+        if isinstance(val, (int, float)):
+            return int(val)
+        if isinstance(val, str):
+            trimmed = val.strip()
+            try:
+                return int(float(trimmed))
+            except (ValueError, OverflowError):
+                raise ValueError(f'Cannot convert string "{val}" to integer')
+        raise ValueError("toInteger() expects a number, string, or boolean")

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

@@ -0,0 +1,35 @@
+"""Trim function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Removes leading and trailing whitespace from a string",
+    "category": "scalar",
+    "parameters": [
+        {"name": "text", "description": "String to trim", "type": "string"}
+    ],
+    "output": {"description": "Trimmed string", "type": "string", "example": "hello"},
+    "examples": [
+        "WITH '  hello  ' AS s RETURN trim(s)",
+        "WITH '\\tfoo\\n' AS s RETURN trim(s)"
+    ]
+})
+class Trim(Function):
+    """Trim function.
+
+    Removes leading and trailing whitespace from a string.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("trim")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        val = self.get_children()[0].value()
+        if not isinstance(val, str):
+            raise ValueError("Invalid argument for trim function: expected a string")
+        return val.strip()

package/flowquery-py/src/parsing/operations/group_by.py

@@ -122,6 +122,8 @@ class GroupBy(Projection):
                 self.mappers[mapper_index].overridden = child.value
                 yield from self.generate_results(mapper_index + 1, child)
         else:
+            if node.elements is None:
+                node.elements = [reducer.element() for reducer in self.reducers]
             if node.elements:
                 for i, element in enumerate(node.elements):
                     self.reducers[i].overridden = element.value

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

@@ -398,6 +398,8 @@ class Parser(BaseParser):
                 raise ValueError("Expected target node definition")
             relationship = Relationship()
             relationship.type = rel_type
+            relationship.source = node
+            relationship.target = target
 
         self._expect_and_skip_whitespace_and_comments()
         if not self.token.is_as():
@@ -576,8 +578,16 @@ class Parser(BaseParser):
         self.set_next_token()
         if not self.token.is_identifier_or_keyword():
             raise ValueError("Expected relationship type identifier")
-        rel_type: str = self.token.value or ""
+        rel_types: List[str] = [self.token.value or ""]
         self.set_next_token()
+        while self.token.is_pipe():
+            self.set_next_token()
+            if self.token.is_colon():
+                self.set_next_token()
+            if not self.token.is_identifier_or_keyword():
+                raise ValueError("Expected relationship type identifier after '|'")
+            rel_types.append(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():
@@ -607,7 +617,7 @@ class Parser(BaseParser):
             self._state.variables[variable] = relationship
         if hops is not None:
             relationship.hops = hops
-        relationship.type = rel_type
+        relationship.types = rel_types
         return relationship
 
     def _parse_properties(self) -> Iterator[Tuple[str, Expression]]: