Adds docs for CursorPaginator

Author: janrito

docs/docs/guides/response/pagination.md

@@ -2,7 +2,6 @@
 
 **Django Ninja** comes with a pagination support. This allows you to split large result sets into individual pages.
 
-
 To apply pagination to a function - just apply `paginate` decorator:
 
 ```python hl_lines="1 4"
@@ -14,7 +13,6 @@ def list_users(request):
     return User.objects.all()
 ```
 
-
 That's it!
 
 Now you can query users with `limit` and `offset` GET parameters
@@ -25,7 +23,6 @@ Now you can query users with `limit` and `offset` GET parameters
 
 by default limit is set to `100` (you can change it in your settings.py using `NINJA_PAGINATION_PER_PAGE`)
 
-
 ## Built in Pagination Classes
 
 ### LimitOffsetPagination (default)
@@ -42,17 +39,18 @@ def list_users(request):
 ```
 
 Example query:
+
 ```
 /api/users?limit=10&offset=0
 ```
 
 this class has two input parameters:
 
- - `limit` - defines a number of queryset on the page (default = 100, change in NINJA_PAGINATION_PER_PAGE)
- - `offset` - set's the page window offset (default: 0, indexing starts with 0)
-
+- `limit` - defines a number of queryset on the page (default = 100, change in NINJA_PAGINATION_PER_PAGE)
+- `offset` - set's the page window offset (default: 0, indexing starts with 0)
 
 ### PageNumberPagination
+
 ```python hl_lines="1 4"
 from ninja.pagination import paginate, PageNumberPagination
 
@@ -63,11 +61,12 @@ def list_users(request):
 ```
 
 Example query:
+
 ```
 /api/users?page=2
 ```
 
-this class has one parameter `page` and outputs 100 queryset per page by default  (can be changed with settings.py)
+this class has one parameter `page` and outputs 100 queryset per page by default (can be changed with settings.py)
 
 Page numbering start with 1
 
@@ -82,12 +81,74 @@ def list_users(...
 In addition to the `page` parameter, you can also use the `page_size` parameter to dynamically adjust the number of records displayed per page:
 
 Example query:
+
 ```
 /api/users?page=2&page_size=20
 ```
 
 This allows you to temporarily override the page size setting in your request. The request will use the specified `page_size` value if provided. Otherwise, it will use either the value specified in the decorator or the value from `PAGINATION_MAX_PER_PAGE_SIZE` in settings.py if no decorator value is set.
 
+### CursorPagination
+
+Cursor-based pagination provides stable pagination for datasets that may change frequently. Cursor pagination uses base64 encoded tokens to mark positions in the dataset, ensuring consistent results even when items are added or removed.
+
+```python hl_lines="1 4"
+from ninja.pagination import paginate, CursorPagination
+
+@api.get('/events', response=List[EventSchema])
+@paginate(CursorPagination)
+def list_events(request):
+    return Event.objects.all()
+```
+
+Example query:
+
+```
+/api/events?cursor=eyJwIjoiMjAyNC0wMS0wMSIsInIiOmZhbHNlLCJvIjowfQ==
+```
+
+this class has two input parameters:
+
+- `cursor` - base64 token representing the current position (optional, starts from beginning if not provided)
+- `page_size` - number of items per page (optional)
+
+You can specify the `page_size` value to temporarily override in the request:
+
+```
+/api/events?cursor=eyJwIjoiMjAyNC0wMS0wMSIsInIiOmZhbHNlLCJvIjowfQ==&page_size=5
+```
+
+This class has a few parameters, which determine how the cursor position is ascertained and the parameter encoded:
+
+- `ordering` - tuple of field names to order the queryset. Use `-` prefix for descending order. The first one of which will be used to encode the position. The ordering field should be unique if possible. A string representation of this field will be used to point to the current position of the cursor. Timestamps work well if each item in the collection is created independently. The paginator can handle some non-uniqueness by adding an offset. Defaults to `("-created",)`, change in `NINJA_PAGINATION_DEFAULT_ORDERING`
+
+- `page_size` - default page size for endpoint. Defaults to `100`, change in `NINJA_PAGINATION_PER_PAGE`
+- `max_page_size` - maximum allowed page size for endpoint. Defaults to `100`, change in `NINJA_PAGINATION_MAX_PER_PAGE_SIZE`
+
+Finally, there is a `NINJA_PAGINATION_MAX_OFFSET` setting to limit malicious cursor requests. It defaults to `100`.
+
+The class parameters can be set globally via settings as well as per view:
+
+```python hl_lines="2"
+@api.get("/events")
+@paginate(CursorPagination, ordering=("start_date", "end_date"), page_size=20, max_page_size=100)
+def list_events(request):
+    return Event.objects.all()
+```
+
+The response includes navigation links and results:
+
+```json
+{
+  "next": "http://api.example.com/events?cursor=eyJwIjoiMjAyNC0wMS0wMiIsInIiOmZhbHNlLCJvIjowfQ==",
+  "previous": "http://api.example.com/events?cursor=eyJwIjoiMjAyNC0wMS0wMSIsInIiOnRydWUsIm8iOjB9",
+  "results": [
+    { "id": 1, "title": "Event 1", "start_date": "2024-01-01" },
+    { "id": 2, "title": "Event 2", "start_date": "2024-01-02" }
+  ]
+}
+```
+
 ## Accessing paginator parameters in view function
 
 If you need access to `Input` parameters used for pagination in your view function - use `pass_parameter` argument
@@ -102,18 +163,16 @@ def someview(request, **kwargs):
     return ...
 ```
 
-
 ## Creating Custom Pagination Class
 
 To create a custom pagination class you should subclass `ninja.pagination.PaginationBase` and override the `Input` and `Output` schema classes and `paginate_queryset(self, queryset, request, **params)` method:
 
- - The `Input` schema is a Schema class that describes parameters that should be passed to your paginator (f.e. page-number or limit/offset values).
- - The `Output` schema describes schema for page output (f.e. count/next-page/items/etc).
- - The `paginate_queryset` method is passed the initial queryset and should return an iterable object that contains only the data in the requested page. This method accepts the following arguments:
-    - `queryset`: a queryset (or iterable) returned by the api function
-    - `pagination` - the paginator.Input parameters (parsed and validated)
-    - `**params`: kwargs that will contain all the arguments that decorated function received 
-
+- The `Input` schema is a Schema class that describes parameters that should be passed to your paginator (f.e. page-number or limit/offset values).
+- The `Output` schema describes schema for page output (f.e. count/next-page/items/etc).
+- The `paginate_queryset` method is passed the initial queryset and should return an iterable object that contains only the data in the requested page. This method accepts the following arguments:
+  - `queryset`: a queryset (or iterable) returned by the api function
+  - `pagination` - the paginator.Input parameters (parsed and validated)
+  - `**params`: kwargs that will contain all the arguments that decorated function received
 
 Example:
 
@@ -126,7 +185,7 @@ class CustomPagination(PaginationBase):
     # only `skip` param, defaults to 5 per page
     class Input(Schema):
         skip: int
-        
+
 
     class Output(Schema):
         items: List[Any] # `items` is a default attribute
@@ -170,12 +229,11 @@ class CustomPagination(PaginationBase):
         results: List[Any]
         total: int
         per_page: int
-    
+
     items_attribute: str = "results"
 
 ```
 
-
 ## Apply pagination to multiple operations at once
 
 There is often a case when you need to add pagination to all views that returns querysets or list
@@ -202,7 +260,6 @@ In this example both operations will have pagination enabled
 
 to apply pagination to main `api` instance use `default_router` argument:
 
-
 ```python
 api = NinjaAPI(default_router=RouterPaginated())