add TimeAxisShift; bump version

Author: mosheduminer

docs/conf.py

@@ -26,7 +26,7 @@
 master_doc = 'index'
 
 # The full version, including alpha/beta/rc tags
-release = '0.5.0'
+release = '0.5.1'
 
 
 # -- General configuration ---------------------------------------------------

pysirix/__init__.py

@@ -4,7 +4,7 @@
 from pysirix.database import Database
 from pysirix.resource import Resource
 from pysirix.json_store import JsonStoreSync, JsonStoreAsync
-from pysirix.constants import Insert, DBType
+from pysirix.constants import Insert, DBType, TimeAxisShift
 from pysirix.errors import SirixServerError
 from pysirix.types import (
     QueryResult,
@@ -65,4 +65,5 @@ async def sirix_async(
     "DeleteDiff",
     "Metadata",
     "MetaNode",
+    "TimeAxisShift",
 ]

pysirix/constants.py

@@ -23,6 +23,12 @@ class DBType(Enum):
     JSON = "application/json"
 
 
+class TimeAxisShift(Enum):
+    oldest = -1
+    none = 0
+    latest = 1
+
+
 class MetadataType(Enum):
     """
     This class defines the scope of the metadata to return using the

pysirix/json_store.py

@@ -1,11 +1,12 @@
 from datetime import datetime
 from typing import Union, Dict, List, Awaitable, Optional
+
 from pysirix.types import Commit, Revision as RevisionType, SubtreeRevision
 from json import dumps, loads
 
 from abc import ABC
 
-from pysirix.constants import DBType, Revision
+from pysirix.constants import DBType, Revision, TimeAxisShift
 from pysirix.async_client import AsyncClient
 from pysirix.auth import Auth
 from pysirix.sync_client import SyncClient
@@ -39,7 +40,7 @@ def stringify(v: Union[None, int, str, Dict, List]):
 query_function_include = (
     "declare function local:q($i, $q) {"
     "let $m := for $k in jn:keys($q) return if (not(empty($i=>$k))) then deep-equal($i=>$k, $q=>$k) else false()"
-    "return empty(index-of($m, false()))"
+    " return empty(index-of($m, false()))"
     "};"
 )
 
@@ -178,8 +179,9 @@ def _prepare_find_all(
         query_dict: Dict,
         projection: List[str] = None,
         revision: Revision = None,
-        node_key=True,
-        hash=False,
+        node_key: bool = True,
+        hash: bool = False,
+        time_axis_shift: TimeAxisShift = TimeAxisShift.none,
         start_result_index: Optional[int] = None,
         end_result_index: Optional[int] = None,
     ):
@@ -200,6 +202,10 @@ def _prepare_find_all(
                 f"for $i in bit:array-values(jn:doc('{self.db_name}','{self.name}',{revision})){self.root}",
             ]
         query_list.append(f"where local:q($i, {stringify(query_dict)})")
+        if time_axis_shift == TimeAxisShift.oldest:
+            query_list.append("let $i := jn:first-existing($i)")
+        elif time_axis_shift == TimeAxisShift.latest:
+            query_list.append("let $i := jn:last-existing($i)")
         return_obj = (
             "return {$i,'nodeKey': sdb:nodekey($i),'hash': sdb:hash($i)}"
             if node_key and hash
@@ -230,8 +236,9 @@ def find_all(
         query_dict: Dict,
         projection: List[str] = None,
         revision: Revision = None,
-        node_key=True,
-        hash=False,
+        node_key: bool = True,
+        hash: bool = False,
+        time_axis_shift: TimeAxisShift = TimeAxisShift.none,
         start_result_index: Optional[int] = None,
         end_result_index: Optional[int] = None,
     ) -> List[QueryResult]:
@@ -251,6 +258,7 @@ def find_all(
                         the nodeKey of the record.
         :param hash: a ``bool`` determining whether or not to return a ``hash`` field containing the hash of the record.
         :param revision: the revision to search, defaults to latest. May be an integer or a ``datetime`` instance
+        :param time_axis_shift: specify fetching the most or least recent existing revision of the record
         :param start_result_index: index of first result to return.
         :param end_result_index: index of last result to return.
         :return: a ``list`` of :py:class:`QueryResult` records matching the query.
@@ -366,8 +374,9 @@ def find_one(
         query_dict: Dict,
         projection: List[str] = None,
         revision: Revision = None,
-        node_key=True,
-        hash=False,
+        node_key: bool = True,
+        hash: bool = False,
+        time_axis_shift: TimeAxisShift = TimeAxisShift.none,
     ) -> List[QueryResult]:
         """
         This method is the same as :py:meth:`find_many`, except that this method will only return the first result,
@@ -378,6 +387,7 @@ def find_one(
         :param revision:
         :param node_key:
         :param hash:
+        :param time_axis_shift:
         :return:
         """
         return self.find_all(
@@ -386,6 +396,7 @@ def find_one(
             revision,
             node_key,
             hash,
+            time_axis_shift,
             start_result_index=0,
             end_result_index=0,
         )
@@ -406,8 +417,9 @@ def find_all(
         query_dict: Dict,
         projection: List[str] = None,
         revision: Revision = None,
-        node_key=True,
-        hash=False,
+        node_key: bool = True,
+        hash: bool = False,
+        time_axis_shift: TimeAxisShift = TimeAxisShift.none,
         start_result_index: Optional[int] = None,
         end_result_index: Optional[int] = None,
     ) -> List[QueryResult]:
@@ -417,6 +429,7 @@ def find_all(
             revision,
             node_key,
             hash,
+            time_axis_shift,
             start_result_index,
             end_result_index,
         )
@@ -459,8 +472,9 @@ async def find_all(
         query_dict: Dict,
         projection: List[str] = None,
         revision: Revision = None,
-        node_key=True,
-        hash=False,
+        node_key: bool = True,
+        hash: bool = False,
+        time_axis_shift: TimeAxisShift = TimeAxisShift.none,
         start_result_index: Optional[int] = None,
         end_result_index: Optional[int] = None,
     ) -> List[QueryResult]:
@@ -470,6 +484,7 @@ async def find_all(
             revision,
             node_key,
             hash,
+            time_axis_shift,
             start_result_index,
             end_result_index,
         )

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="pysirix",
-    version="0.5.0",
+    version="0.5.1",
     author="Moshe Uminer",
     author_email="[email protected]",
     description="The SirixDB Python SDK",

tests/test_json_store.py

@@ -1,8 +1,9 @@
+import time
 from datetime import datetime
 
 import httpx
 import pysirix
-from pysirix import DBType
+from pysirix import DBType, TimeAxisShift
 
 base_url = "http://localhost:9443"
 
@@ -148,6 +149,30 @@ def test_upsert_non_existent_field():
     assert store.find_one({"key": "value"}, node_key=False) == [{"key": "value"}]
 
 
+def test_shift_time_axis():
+    store.create()
+    store.insert_one({"id": 0})
+    store.update_by_key(2, {"key": "value"})
+    assert (
+        store.find_one(
+            {"id": 0},
+            node_key=False,
+            revision=2,
+            time_axis_shift=TimeAxisShift.latest,
+        )
+        == [{"key": "value", "id": 0}]
+    )
+    assert (
+        store.find_one(
+            {"id": 0},
+            node_key=False,
+            revision=3,
+            time_axis_shift=TimeAxisShift.oldest,
+        )
+        == [{"id": 0}]
+    )
+
+
 def test_update_many():
     store.create()
     store.insert_many(