added offset clause for select and objects queries

Author: dantownsend

docs/src/piccolo/query_clauses/index.rst

@@ -8,6 +8,7 @@ Query Clauses
 
     ./first
     ./limit
+    ./offset
     ./order_by
     ./where
     ./batch

docs/src/piccolo/query_clauses/offset.rst

@@ -0,0 +1,27 @@
+.. _offset:
+
+offset
+======
+
+You can use ``offset`` clauses with the following queries:
+
+* :ref:`Objects`
+* :ref:`Select`
+
+This will omit the first X rows from the response. It's useful for things like
+pagination.
+
+It's highly recommended to use it along with an :ref:`order_by` clause,
+otherwise the results returned could be different each time.
+
+.. code-block:: python
+
+    >>> Band.select(Band.name).offset(1).order_by(Band.name).run_sync()
+    [{'name': 'Pythonistas'}, {'name': 'Rustaceans'}]
+
+Likewise, with objects:
+
+.. code-block:: python
+
+    >>> Band.objects().offset(1).order_by(Band.name).run_sync()
+    [Band2, Band3]

docs/src/piccolo/query_types/objects.rst

@@ -84,6 +84,11 @@ limit
 
 See  :ref:`limit`.
 
+offset
+~~~~~~
+
+See  :ref:`offset`.
+
 first
 ~~~~~
 

docs/src/piccolo/query_types/select.rst

@@ -119,6 +119,11 @@ limit
 
 See  :ref:`limit`.
 
+offset
+~~~~~~
+
+See  :ref:`offset`.
+
 order_by
 ~~~~~~~~
 

piccolo/query/methods/objects.py

@@ -6,6 +6,7 @@
 from piccolo.query.base import Query
 from piccolo.query.mixins import (
     LimitDelegate,
+    OffsetDelegate,
     OrderByDelegate,
     WhereDelegate,
     OutputDelegate,
@@ -26,13 +27,15 @@ class Objects(Query):
 
     __slots__ = (
         "limit_delegate",
+        "offset_delegate",
         "order_by_delegate",
         "output_delegate",
         "where_delegate",
     )
 
     def _setup_delegates(self):
         self.limit_delegate = LimitDelegate()
+        self.offset_delegate = OffsetDelegate()
         self.order_by_delegate = OrderByDelegate()
         self.output_delegate = OutputDelegate()
         self.output_delegate._output.as_objects = True
@@ -46,6 +49,10 @@ def first(self) -> Objects:
         self.limit_delegate.first()
         return self
 
+    def offset(self, number: int) -> Objects:
+        self.offset_delegate.offset(number)
+        return self
+
     def order_by(self, *columns: Column, ascending=True) -> Objects:
         self.order_by_delegate.order_by(*columns, ascending=ascending)
         return self
@@ -77,6 +84,7 @@ def querystring(self) -> QueryString:
         for attr in (
             "limit_delegate",
             "where_delegate",
+            "offset_delegate",
             "output_delegate",
             "order_by_delegate",
         ):

piccolo/query/methods/select.py

@@ -10,6 +10,7 @@
     ColumnsDelegate,
     DistinctDelegate,
     LimitDelegate,
+    OffsetDelegate,
     OrderByDelegate,
     OutputDelegate,
     WhereDelegate,
@@ -27,6 +28,7 @@ class Select(Query):
         "columns_delegate",
         "distinct_delegate",
         "limit_delegate",
+        "offset_delegate",
         "order_by_delegate",
         "output_delegate",
         "where_delegate",
@@ -45,6 +47,7 @@ def _setup_delegates(self):
         self.columns_delegate = ColumnsDelegate()
         self.distinct_delegate = DistinctDelegate()
         self.limit_delegate = LimitDelegate()
+        self.offset_delegate = OffsetDelegate()
         self.order_by_delegate = OrderByDelegate()
         self.output_delegate = OutputDelegate()
         self.where_delegate = WhereDelegate()
@@ -66,6 +69,10 @@ def first(self) -> Select:
         self.limit_delegate.first()
         return self
 
+    def offset(self, number: int) -> Select:
+        self.offset_delegate.offset(number)
+        return self
+
     async def response_handler(self, response):
         if self.limit_delegate._first:
             if len(response) == 0:
@@ -210,6 +217,10 @@ def querystring(self) -> QueryString:
             query += " {}"
             args.append(self.limit_delegate._limit.querystring)
 
+        if self.offset_delegate._offset:
+            query += " {}"
+            args.append(self.offset_delegate._offset.querystring)
+
         querystring = QueryString(query, *args)
 
         return querystring

piccolo/query/mixins.py

@@ -28,6 +28,24 @@ def __str__(self) -> str:
         return self.querystring.__str__()
 
 
+@dataclass
+class Offset:
+    __slots__ = ("number",)
+
+    number: int
+
+    def __post_init__(self):
+        if type(self.number) != int:
+            raise TypeError("Limit must be an integer")
+
+    @property
+    def querystring(self) -> QueryString:
+        return QueryString(f" OFFSET {self.number}")
+
+    def __str__(self) -> str:
+        return self.querystring.__str__()
+
+
 @dataclass
 class OrderBy:
     __slots__ = ("columns", "ascending")
@@ -192,3 +210,21 @@ class ValuesDelegate:
 
     def values(self, values: t.Dict[Column, t.Any]):
         self._values.update(values)
+
+
+@dataclass
+class OffsetDelegate:
+    """
+    Used to offset the results - for example, to return row 100 and onward.
+
+    Typically used in conjunction with order_by and limit.
+
+    Example usage:
+
+    .offset(100)
+    """
+
+    _offset: t.Optional[Offset] = None
+
+    def offset(self, number: int = 0):
+        self._offset = Offset(number)

tests/table/test_objects.py

@@ -3,7 +3,6 @@
 
 
 class TestObjects(DBTestCase):
-
     def test_get_all(self):
         self.insert_row()
 
@@ -14,17 +13,25 @@ def test_get_all(self):
         instance = response[0]
 
         self.assertTrue(isinstance(instance, Band))
-        self.assertTrue(instance.name == 'Pythonistas')
+        self.assertTrue(instance.name == "Pythonistas")
 
         # Now try changing the value and saving it.
-        instance.name = 'Rustaceans'
+        instance.name = "Rustaceans"
         save_query = instance.save()
         save_query.run_sync()
 
         self.assertTrue(
-            Band.select().columns(
-                Band.name
-            ).output(
-                as_list=True
-            ).run_sync()[0] == 'Rustaceans'
+            Band.select().columns(Band.name).output(as_list=True).run_sync()[0]
+            == "Rustaceans"
+        )
+
+    def test_offset(self):
+        self.insert_rows()
+
+        response = Band.objects().order_by(Band.name).offset(1).run_sync()
+
+        print(f"response = {response}")
+
+        self.assertEqual(
+            [i.name for i in response], ["Pythonistas", "Rustaceans"]
         )

tests/table/test_select.py

@@ -218,6 +218,23 @@ def test_limit(self):
 
         self.assertEqual(response, [{"name": "CSharps"}])
 
+    def test_offset(self):
+        self.insert_rows()
+
+        response = (
+            Band.select()
+            .columns(Band.name)
+            .order_by(Band.name)
+            .offset(1)
+            .run_sync()
+        )
+
+        print(f"response = {response}")
+
+        self.assertEqual(
+            response, [{"name": "Pythonistas"}, {"name": "Rustaceans"}]
+        )
+
     def test_first(self):
         self.insert_rows()