django-cursor-pagination

0.3.0 verified Mon Apr 27 auth: no python

Cursor-based pagination for Django models, providing efficient and stable pagination for large datasets. Current version: 0.3.0. Released sporadically, last update in 2024.

pip install django-cursor-pagination

Common errors

error AttributeError: module 'cursor_pagination' has no attribute 'CursorPagination' ↓

cause Incorrect import: using old import path or missing install.

fix

Install with 'pip install django-cursor-pagination' and import 'from cursor_pagination import CursorPagination'.

error TypeError: __init__() missing 1 required positional argument: 'request' ↓

cause Calling CursorPagination directly without passing request object (DRF expects it to be instantiated by framework).

fix

Do not instantiate pagination manually. Use it as a class attribute in DRF view: pagination_class = MyPagination.

error ValueError: Cannot order by field 'name' because it is not unique and may cause duplicates. Please use a unique field for cursor pagination. ↓

cause Ordering by a non-unique field can break pagination stability.

fix

Use a unique field like 'id' or a timestamp field that is unique enough. Composite ordering can help.

Warnings

gotcha The 'ordering' field must be a unique or nearly unique field (e.g., primary key, created timestamp with timezone). Non-unique ordering can cause missing or duplicate results. ↓

fix Use a field like '-created' or 'id' that is unique in practice. Avoid fields with many duplicates.

gotcha Cursor pagination does not support arbitrary page numbers. It only provides 'next' and 'previous' cursors. Do not expect page query parameter like '?page=3'. ↓

fix Use cursor-based links from response instead of manual page numbers.

breaking Version 0.3.0 added async queryset evaluation support. If you upgrade from <0.3.0, ensure your code doesn't rely on synchronous-only behavior. ↓

fix Test with async views if applicable. The change is backward-compatible for sync usage.

Imports

CursorPagination

wrong

from django_cursor_pagination import CursorPagination

correct

from cursor_pagination import CursorPagination

Module name is 'cursor_pagination', not 'django_cursor_pagination'.

CURSOR_PAGINATION_PAGE_SIZE
```
from cursor_pagination import CURSOR_PAGINATION_PAGE_SIZE
```
Settings import, used to override default page size.

Quickstart

Create a custom pagination class and use it in a Django REST Framework view. Cursor pagination provides stable, efficient pagination for large datasets.

from cursor_pagination import CursorPagination

class MyPagination(CursorPagination):
    ordering = '-created'  # or use 'created' for ASC
    page_size = 20

# Then in your view:
# from rest_framework.generics import ListAPIView
# class MyListView(ListAPIView):
#     queryset = MyModel.objects.all()
#     pagination_class = MyPagination