RDBC-1059 Add RavenDocumentQuery.now/today/cmp_xchg server-side helpers

Author: poissoncorp

ravendb/__init__.py

@@ -195,6 +195,7 @@
 from ravendb.documents.queries.highlighting import HighlightingOptions, QueryHighlightings
 from ravendb.documents.queries.index_query import IndexQuery
 from ravendb.documents.queries.misc import SearchOperator
+from ravendb.documents.queries.raven_document_query import RavenDocumentQuery
 from ravendb.documents.queries.more_like_this import (
     MoreLikeThisOperations,
     MoreLikeThisBase,

ravendb/documents/queries/raven_document_query.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ravendb.documents.session.misc import MethodCall, CmpXchg
+from ravendb.documents.session.tokens.query_tokens.definitions import WhereToken
+
+
+class RavenDocumentQuery:
+    """Server-side RQL functions for DocumentQuery: now(), today(), cmpxchg()."""
+
+    @staticmethod
+    def now(offset: Optional[str] = None) -> "RavenDocumentQuery.Time":
+        if offset is None:
+            return RavenDocumentQuery.Time(WhereToken.MethodsType.NOW)
+        return RavenDocumentQuery.Time(WhereToken.MethodsType.NOW, [offset])
+
+    @staticmethod
+    def today() -> "RavenDocumentQuery.Time":
+        return RavenDocumentQuery.Time(WhereToken.MethodsType.TODAY)
+
+    @staticmethod
+    def cmp_xchg(key: str) -> CmpXchg:
+        # Build directly — CmpXchg.value() is deprecated and emits a warning.
+        cmp_xchg = CmpXchg()
+        cmp_xchg.args = [key]
+        return cmp_xchg
+
+    class Time(MethodCall):
+        def __init__(self, method_type: WhereToken.MethodsType, args=None):
+            super().__init__(args=args or [])
+            self.method_type = method_type

ravendb/documents/session/misc.py

@@ -303,9 +303,16 @@ def __init__(self, args: List[object] = None, access_path: str = None):
 class CmpXchg(MethodCall):
     @classmethod
     def value(cls, key: str) -> CmpXchg:
+        # Kept for back-compat; prefer RavenDocumentQuery.cmp_xchg().
+        import warnings
+
+        warnings.warn(
+            "CmpXchg.value is deprecated; use RavenDocumentQuery.cmp_xchg() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         cmp_xchg = cls()
         cmp_xchg.args = [key]
-
         return cmp_xchg
 
 

ravendb/documents/session/query.py

@@ -463,7 +463,7 @@ def _where_equals(
         tokens = self.__get_current_where_tokens()
         self.__append_operator_if_needed(tokens)
 
-        if self.__if_value_is_method(WhereOperator.EQUALS, params, tokens):
+        if self._if_value_is_method(WhereOperator.EQUALS, params, tokens):
             return
 
         transform_to_equal_value = self.__transform_value(params)
@@ -476,17 +476,21 @@ def _where_equals(
         )
         tokens.append(where_token)
 
-    def __if_value_is_method(self, op: WhereOperator, where_params: WhereParams, tokens: List[QueryToken]) -> bool:
+    def _if_value_is_method(self, op: WhereOperator, where_params: WhereParams, tokens: List[QueryToken]) -> bool:
+        # MethodCall values (RavenDocumentQuery.now/today, CmpXchg) emit a
+        # method-flavored WhereToken instead of binding as a parameter.
+        # Returns True if a token was appended (caller should short-circuit).
         if isinstance(where_params.value, MethodCall):
+            from ravendb.documents.queries.raven_document_query import RavenDocumentQuery
+
             mc = where_params.value
 
             args = []
             for arg in mc.args:
                 args.append(self.__add_query_parameter(arg))
 
             token: Optional[WhereToken] = None
-            object_type = type(mc)
-            if object_type == CmpXchg:
+            if isinstance(mc, CmpXchg):
                 token = WhereToken.create(
                     op,
                     where_params.field_name,
@@ -500,8 +504,22 @@ def __if_value_is_method(self, op: WhereOperator, where_params: WhereParams, tok
                         )
                     ),
                 )
+            elif isinstance(mc, RavenDocumentQuery.Time):
+                token = WhereToken.create(
+                    op,
+                    where_params.field_name,
+                    None,
+                    WhereToken.WhereOptions(
+                        method_type__parameters__property__exact=(
+                            mc.method_type,
+                            args,
+                            mc.access_path,
+                            where_params.exact,
+                        )
+                    ),
+                )
             else:
-                raise TypeError(f"Unknown method {object_type}")
+                raise TypeError(f"Unknown method {type(mc)}")
 
             tokens.append(token)
             return True
@@ -537,7 +555,7 @@ def _where_not_equals(
 
         where_params.field_name = self._ensure_valid_field_name(where_params.field_name, where_params.nested_path)
 
-        if self.__if_value_is_method(WhereOperator.NOT_EQUALS, where_params, tokens):
+        if self._if_value_is_method(WhereOperator.NOT_EQUALS, where_params, tokens):
             return
 
         where_token = WhereToken.create(
@@ -639,82 +657,46 @@ def _where_between(self, field_name: str, start: object, end: object, exact: Opt
         )
         tokens.append(where_token)
 
-    def _where_greater_than(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
+    def _where_compare(
+        self,
+        op: WhereOperator,
+        field_name: str,
+        value: object,
+        exact: Optional[bool],
+        null_sentinel: str,
+    ) -> None:
+        # Shared body for >/>=/</<=. Routes through _if_value_is_method first
+        # so MethodCall values (now/today/cmpxchg) are emitted as RQL calls.
         field_name = self._ensure_valid_field_name(field_name, False)
-
         tokens = self.__get_current_where_tokens()
         self.__append_operator_if_needed(tokens)
         self.__negate_if_needed(tokens, field_name)
         where_params = WhereParams()
         where_params.value = value
         where_params.field_name = field_name
+        where_params.exact = exact
 
-        parameter = self.__add_query_parameter("*" if value is None else self.__transform_value(where_params, True))
-        where_token = WhereToken.create(
-            WhereOperator.GREATER_THAN,
-            field_name,
-            parameter,
-            WhereToken.WhereOptions(exact__from__to=(exact, None, None)),
-        )
-        tokens.append(where_token)
-
-    def _where_greater_than_or_equal(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
-        field_name = self._ensure_valid_field_name(field_name, False)
-
-        tokens = self.__get_current_where_tokens()
-        self.__append_operator_if_needed(tokens)
-        self.__negate_if_needed(tokens, field_name)
-        where_params = WhereParams()
-        where_params.value = value
-        where_params.field_name = field_name
+        if self._if_value_is_method(op, where_params, tokens):
+            return
 
-        parameter = self.__add_query_parameter("*" if value is None else self.__transform_value(where_params, True))
-        where_token = WhereToken.create(
-            WhereOperator.GREATER_THAN_OR_EQUAL,
-            field_name,
-            parameter,
-            WhereToken.WhereOptions(exact__from__to=(exact, None, None)),
+        parameter = self.__add_query_parameter(
+            null_sentinel if value is None else self.__transform_value(where_params, True)
         )
-        tokens.append(where_token)
-
-    def _where_less_than(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
-        field_name = self._ensure_valid_field_name(field_name, False)
-
-        tokens = self.__get_current_where_tokens()
-        self.__append_operator_if_needed(tokens)
-        self.__negate_if_needed(tokens, field_name)
-        where_params = WhereParams()
-        where_params.value = value
-        where_params.field_name = field_name
-
-        parameter = self.__add_query_parameter("*" if value is None else self.__transform_value(where_params, True))
-        where_token = WhereToken.create(
-            WhereOperator.LESS_THAN,
-            field_name,
-            parameter,
-            WhereToken.WhereOptions(exact__from__to=(exact, None, None)),
+        tokens.append(
+            WhereToken.create(op, field_name, parameter, WhereToken.WhereOptions(exact__from__to=(exact, None, None)))
         )
-        tokens.append(where_token)
 
-    def _where_less_than_or_equal(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
-        field_name = self._ensure_valid_field_name(field_name, False)
+    def _where_greater_than(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
+        self._where_compare(WhereOperator.GREATER_THAN, field_name, value, exact, "*")
 
-        tokens = self.__get_current_where_tokens()
-        self.__append_operator_if_needed(tokens)
-        self.__negate_if_needed(tokens, field_name)
+    def _where_greater_than_or_equal(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
+        self._where_compare(WhereOperator.GREATER_THAN_OR_EQUAL, field_name, value, exact, "*")
 
-        where_params = WhereParams()
-        where_params.value = value
-        where_params.field_name = field_name
+    def _where_less_than(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
+        self._where_compare(WhereOperator.LESS_THAN, field_name, value, exact, "NULL")
 
-        parameter = self.__add_query_parameter("NULL" if value is None else self.__transform_value(where_params, True))
-        where_token = WhereToken.create(
-            WhereOperator.LESS_THAN_OR_EQUAL,
-            field_name,
-            parameter,
-            WhereToken.WhereOptions(exact__from__to=(exact, None, None)),
-        )
-        tokens.append(where_token)
+    def _where_less_than_or_equal(self, field_name: str, value: object, exact: Optional[bool] = False) -> None:
+        self._where_compare(WhereOperator.LESS_THAN_OR_EQUAL, field_name, value, exact, "NULL")
 
     def _where_regex(self, field_name: str, pattern: str) -> None:
         field_name = self._ensure_valid_field_name(field_name, False)

ravendb/documents/session/tokens/query_tokens/definitions.py

@@ -576,6 +576,8 @@ def write_to(self, writer: List[str]):
 class WhereToken(QueryToken):
     class MethodsType(enum.Enum):
         CMP_X_CHG = "CmpXChg"
+        NOW = "Now"
+        TODAY = "Today"
 
     class WhereMethodCall:
         def __init__(
@@ -674,10 +676,21 @@ def add_alias(self, alias: str) -> WhereToken:
 
     def __write_method(self, writer: List[str]) -> bool:
         if self.options.method is not None:
-            if self.options.method.method_type == WhereToken.MethodsType.CMP_X_CHG:
+            method_type = self.options.method.method_type
+            if method_type == WhereToken.MethodsType.NOW:
+                writer.append("now(")
+                if self.options.method.parameters:
+                    writer.append("$")
+                    writer.append(self.options.method.parameters[0])
+                writer.append(")")
+                return True
+            if method_type == WhereToken.MethodsType.TODAY:
+                writer.append("today()")
+                return True
+            if method_type == WhereToken.MethodsType.CMP_X_CHG:
                 writer.append("cmpxchg(")
             else:
-                raise ValueError(f"Unsupported method: {self.options.method.method_type}")
+                raise ValueError(f"Unsupported method: {method_type}")
 
             first = True
             for parameter in self.options.method.parameters:

ravendb/tests/session_tests/test_raven_document_query.py

@@ -0,0 +1,71 @@
+"""
+Unit tests for RavenDocumentQuery.Now / Today / CmpXchg plus the
+WhereToken NOW/TODAY MethodsType output.
+"""
+
+import unittest
+import warnings
+
+from ravendb.documents.queries.raven_document_query import RavenDocumentQuery
+from ravendb.documents.session.misc import CmpXchg, MethodCall
+from ravendb.documents.session.tokens.misc import WhereOperator
+from ravendb.documents.session.tokens.query_tokens.definitions import WhereToken
+
+
+class TestRavenDocumentQueryFactories(unittest.TestCase):
+    def test_now_no_args(self):
+        t = RavenDocumentQuery.now()
+        self.assertEqual(WhereToken.MethodsType.NOW, t.method_type)
+        self.assertEqual([], t.args)
+        self.assertIsInstance(t, MethodCall)
+
+    def test_now_with_offset(self):
+        t = RavenDocumentQuery.now("+1d")
+        self.assertEqual(WhereToken.MethodsType.NOW, t.method_type)
+        self.assertEqual(["+1d"], t.args)
+
+    def test_today(self):
+        t = RavenDocumentQuery.today()
+        self.assertEqual(WhereToken.MethodsType.TODAY, t.method_type)
+        self.assertEqual([], t.args)
+
+    def test_cmp_xchg_does_not_warn(self):
+        with warnings.catch_warnings(record=True) as captured:
+            warnings.simplefilter("always")
+            x = RavenDocumentQuery.cmp_xchg("foo")
+            self.assertFalse(any(issubclass(w.category, DeprecationWarning) for w in captured))
+        self.assertIsInstance(x, CmpXchg)
+        self.assertEqual(["foo"], x.args)
+
+    def test_legacy_cmp_xchg_value_emits_deprecation(self):
+        with warnings.catch_warnings(record=True) as captured:
+            warnings.simplefilter("always")
+            CmpXchg.value("foo")
+            self.assertTrue(any(issubclass(w.category, DeprecationWarning) for w in captured))
+
+
+class TestWhereTokenNowTodayOutput(unittest.TestCase):
+    @staticmethod
+    def _render(method_type: WhereToken.MethodsType, parameters):
+        token = WhereToken.create(
+            WhereOperator.GREATER_THAN,
+            "CreatedAt",
+            None,
+            WhereToken.WhereOptions(method_type__parameters__property__exact=(method_type, parameters, None, None)),
+        )
+        out = []
+        token.write_to(out)
+        return "".join(out)
+
+    def test_now_no_param(self):
+        self.assertEqual("CreatedAt > now()", self._render(WhereToken.MethodsType.NOW, []))
+
+    def test_now_with_param(self):
+        self.assertEqual("CreatedAt > now($p0)", self._render(WhereToken.MethodsType.NOW, ["p0"]))
+
+    def test_today(self):
+        self.assertEqual("CreatedAt > today()", self._render(WhereToken.MethodsType.TODAY, []))
+
+
+if __name__ == "__main__":
+    unittest.main()