add support for slicing as a translation into limit and offset with ordering switch (#765)

Co-authored-by: collerek <collerek@gmail.com>

Author: SepehrBazyar

docs/queries/pagination-and-rows-number.md

@@ -5,14 +5,22 @@ Following methods allow you to paginate and limit number of rows in queries.
 * `paginate(page: int) -> QuerySet`
 * `limit(limit_count: int) -> QuerySet`
 * `offset(offset: int) -> QuerySet`
+* `__getitem__(key: int | slice) -> QuerySet`
 * `get() -> Model`
 * `first() -> Model`
+* `first_or_none() -> Optional[Model]`
+* `last() -> Model`
+* `last_or_none() -> Optional[Model]`
 
 
 * `QuerysetProxy`
     * `QuerysetProxy.paginate(page: int)` method
     * `QuerysetProxy.limit(limit_count: int)` method
     * `QuerysetProxy.offset(offset: int)` method
+    * `QuerysetProxy.__getitem__(key: int | slice)` method
+    * `QuerysetProxy.first_or_none()` method
+    * `QuerysetProxy.last()` method
+    * `QuerysetProxy.last_or_none()` method
 
 ## paginate
 
@@ -113,6 +121,41 @@ tracks = await Track.objects.offset(1).limit(1).all()
     Something like `Track.object.select_related("album").filter(album__name="Malibu").offset(1).limit(1).all()`
 
 
+## slicing with `__getitem__`
+
+A `QuerySet` can also be sliced with Python integer or slice syntax. Each
+call returns a new `QuerySet` with LIMIT/OFFSET set accordingly — you still
+need to `await` it with `.all()` to actually run the query.
+
+```python
+# positive bounds map directly to LIMIT/OFFSET
+first_ten = await Track.objects[:10].all()
+page_two = await Track.objects[10:20].all()
+single = await Track.objects[5].all()  # returns a one-element list
+```
+
+Negative indices and negative slice bounds are supported too. Internally
+they are translated into a reversed-order query plus an in-memory list
+reversal, so the caller still sees results in the original ordering:
+
+```python
+last_five = await Track.objects[-5:].all()
+last_one = await Track.objects[-1].all()      # one-element list
+tail_slice = await Track.objects[-10:-5].all()
+```
+
+!!!note
+    Slice shapes that would require a `COUNT(*)` round-trip to resolve — a
+    bare `[:-N]`, or mixed positive/negative bounds like `[3:-2]` — raise
+    `QueryDefinitionError`. If you need "all except the last N", fetch
+    `.count()` explicitly and combine it with `.offset()`/`.limit()`.
+
+    A `step` other than `1` is not supported, and a non-integer / non-slice
+    key (e.g. `objects["foo"]`) also raises `QueryDefinitionError`.
+
+    Each slice replaces any previous pagination state rather than composing
+    with it — avoid chaining multiple slices on the same queryset.
+
 
 ## get
 
@@ -129,14 +172,53 @@ If no criteria is set it will return the last row in db sorted by pk.
 
 ## first
 
-`first() -> Model` 
+`first() -> Model`
 
 Gets the first row from the db ordered by primary key column ascending.
 
 !!!tip
     To read more about `first` visit [read/first](./read/#first)
 
 
+## first_or_none
+
+`first_or_none() -> Optional[Model]`
+
+Same as `first()` but returns `None` instead of raising `NoMatch` when no
+row matches.
+
+!!!tip
+    To read more about `first_or_none` visit [read/first_or_none](./read/#first_or_none)
+
+
+## last
+
+`last() -> Model`
+
+Gets the last row from the db ordered by primary key column descending.
+Complementary to `first()` — the default pk ordering is flipped and the top
+row is returned.
+
+```python
+newest = await Track.objects.last()
+newest_by_name = await Track.objects.order_by("name").last()
+```
+
+!!!tip
+    To read more about `last` visit [read/last](./read/#last)
+
+
+## last_or_none
+
+`last_or_none() -> Optional[Model]`
+
+Same as `last()` but returns `None` instead of raising `NoMatch` when no
+row matches.
+
+!!!tip
+    To read more about `last_or_none` visit [read/last_or_none](./read/#last_or_none)
+
+
 ## QuerysetProxy methods
 
 When access directly the related `ManyToMany` field as well as `ReverseForeignKey`
@@ -169,4 +251,16 @@ objects from other side of the relation.
 !!!tip 
     To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
 
+### slicing with `__getitem__`
+
+Works exactly the same as [slicing](./#slicing-with-__getitem__) above but on the relation
+side:
+
+```python
+recent_cars = await user.cars[-3:].all()
+```
+
+!!!tip
+    To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
+
 [querysetproxy]: ../relations/queryset-proxy.md

docs/queries/read.md

@@ -3,8 +3,12 @@
 Following methods allow you to load data from the database.
 
 * `get(*args, **kwargs) -> Model`
+* `get_or_none(*args, **kwargs) -> Optional[Model]`
 * `get_or_create(_defaults: Optional[dict[str, Any]] = None, *args, **kwargs) -> tuple[Model, bool]`
 * `first(*args, **kwargs) -> Model`
+* `first_or_none(*args, **kwargs) -> Optional[Model]`
+* `last(*args, **kwargs) -> Model`
+* `last_or_none(*args, **kwargs) -> Optional[Model]`
 * `all(*args, **kwargs) -> list[Optional[Model]]`
 * `iterate(*args, **kwargs) -> AsyncGenerator[Model]`
 
@@ -15,8 +19,12 @@ Following methods allow you to load data from the database.
 
 * `QuerysetProxy`
     * `QuerysetProxy.get(*args, **kwargs)` method
+    * `QuerysetProxy.get_or_none(*args, **kwargs)` method
     * `QuerysetProxy.get_or_create(_defaults: Optional[dict[str, Any]] = None, *args, **kwargs)` method
     * `QuerysetProxy.first(*args, **kwargs)` method
+    * `QuerysetProxy.first_or_none(*args, **kwargs)` method
+    * `QuerysetProxy.last(*args, **kwargs)` method
+    * `QuerysetProxy.last_or_none(*args, **kwargs)` method
     * `QuerysetProxy.all(*args, **kwargs)` method
 
 ## get
@@ -126,6 +134,58 @@ album = await Album.objects.first()
 assert album.name == 'The Cat'
 ```
 
+## first_or_none
+
+`first_or_none(*args, **kwargs) -> Optional[Model]`
+
+Exact equivalent of `first` described above but instead of raising `NoMatch`
+returns `None` if no db record matching the criteria is found.
+
+```python
+empty = await Album.objects.first_or_none()
+# None — no rows in the table
+missing = await Album.objects.first_or_none(name='The Missing')
+# None — no row matches the filter
+```
+
+## last
+
+`last(*args, **kwargs) -> Model`
+
+Gets the last row from the db ordered by primary key column descending.
+Complementary to `first()` — the default pk ordering is flipped and the top
+row is returned. When you combine `last()` with `order_by(...)`, the user's
+ordering is flipped too, so `order_by("name").last()` returns the row that
+would sort last by name.
+
+```python
+await Album.objects.create(name='The Cat')
+await Album.objects.create(name='The Dog')
+album = await Album.objects.last()
+# last row by primary_key column desc
+assert album.name == 'The Dog'
+
+album = await Album.objects.order_by("name").last()
+# last row by name (alphabetical)
+assert album.name == 'The Dog'
+```
+
+!!!warning
+    Same as `first()` — raises `NoMatch` if no rows and `MultipleMatches` if
+    somehow more than one row matches.
+
+## last_or_none
+
+`last_or_none(*args, **kwargs) -> Optional[Model]`
+
+Exact equivalent of `last` described above but instead of raising `NoMatch`
+returns `None` if no db record matching the criteria is found.
+
+```python
+empty = await Album.objects.last_or_none()
+# None — no rows in the table
+```
+
 ## all
 
 `all(*args, **kwargs) -> list[Optional["Model"]]`
@@ -252,6 +312,30 @@ related objects from other side of the relation.
 !!!tip 
     To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
 
+### first_or_none
+
+Works exactly the same as [first_or_none](./#first_or_none) function above but
+returns `None` instead of raising `NoMatch`, and works on the relation side.
+
+!!!tip
+    To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
+
+### last
+
+Works exactly the same as [last](./#last) function above but allows you to query
+related objects from other side of the relation.
+
+!!!tip
+    To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
+
+### last_or_none
+
+Works exactly the same as [last_or_none](./#last_or_none) function above but
+returns `None` instead of raising `NoMatch`, and works on the relation side.
+
+!!!tip
+    To read more about `QuerysetProxy` visit [querysetproxy][querysetproxy] section
+
 ### all
 
 Works exactly the same as [all](./#all) function above but allows you to query related

ormar/queryset/actions/order_action.py

@@ -1,3 +1,4 @@
+import copy
 from typing import TYPE_CHECKING, Optional
 
 import sqlalchemy
@@ -128,6 +129,44 @@ def _split_value_into_parts(self, order_str: str) -> None:
         self.field_name = parts[-1]
         self.related_parts = parts[:-1]
 
+    @classmethod
+    def from_model_defaults(cls, model_cls: type["Model"]) -> list["OrderAction"]:
+        """
+        Builds the default list of ``OrderAction`` instances from a model's
+        ``OrmarConfig.orders_by`` (which always contains at least the primary
+        key, populated by the metaclass).
+
+        :param model_cls: model class whose defaults should be used
+        :type model_cls: type["Model"]
+        :return: list of default OrderAction instances for the model
+        :rtype: list[OrderAction]
+        """
+        return [
+            cls(order_str=str(name), model_cls=model_cls)
+            for name in model_cls.ormar_config.orders_by
+        ]
+
+    def flipped(self) -> "OrderAction":
+        """
+        Returns a shallow copy of this order action with the sort direction
+        and any `NULLS FIRST`/`NULLS LAST` annotation inverted.
+
+        Used by reverse slicing to turn an ASC/DESC ordering into its mirror
+        image so that ``LIMIT N`` fetches rows from the tail of the original
+        ordering. Callers are responsible for reversing the result list in
+        memory afterwards so the caller-visible ordering is preserved.
+
+        :return: new OrderAction with flipped direction and nulls ordering
+        :rtype: OrderAction
+        """
+        flipped = copy.copy(self)
+        flipped.direction = "" if self.direction == "desc" else "desc"
+        if self.nulls_ordering == "first":
+            flipped.nulls_ordering = "last"
+        elif self.nulls_ordering == "last":
+            flipped.nulls_ordering = "first"
+        return flipped
+
     def check_if_filter_apply(self, target_model: type["Model"], alias: str) -> bool:
         """
         Checks filter conditions to find if they apply to current join.

ormar/queryset/queries/query.py

@@ -79,8 +79,7 @@ def _apply_default_model_sorting(self) -> None:
         Applies orders_by from model OrmarConfig (if provided), if it was not provided
         it was filled by metaclass, so it's always there and falls back to pk column
         """
-        for order_by in self.model_cls.ormar_config.orders_by:
-            clause = ormar.OrderAction(order_str=order_by, model_cls=self.model_cls)
+        for clause in ormar.OrderAction.from_model_defaults(self.model_cls):
             self.sorted_orders[clause] = clause.get_text_clause()
 
     def _pagination_query_required(self) -> bool: