django-cursor-pagination

Cursor-based pagination for Django

Showing:

Popularity

Downloads/wk

0

GitHub Stars

122

Maintenance

Last Commit

3mos ago

Contributors

11

Package

Dependencies

0

License

BSD

Categories

Readme

Django cursor pagination Build Status

A cursor based pagination system for Django. Instead of refering to specific pages by number, we give every item in the queryset a cursor based on its ordering values. We then ask for subsequent records by asking for records after the cursor of the last item we currently have. Similarly we can ask for records before the cursor of the first item to navigate back through the list.

This approach has two major advantages over traditional pagination. Firstly, it ensures that when new data is written into the table, records cannot be moved onto the next page. Secondly, it is much faster to query against the database as we are not using very large offset values.

There are some significant drawbacks over "traditional" pagination. The data must be ordered by some database field(s) which are unique across all records. A typical use case would be ordering by a creation timestamp and an id. It is also more difficult to get the range of possible pages for the data.

The inspiration for this project is largely taken from this post by David Cramer, and the connection spec for Relay GraphQL. Much of the implementation is inspired by Django rest framework's Cursor pagination.. The main difference between the Disqus approach and the one used here is that we require the ordering to be totally determinate instead of using offsets.

Installation

pip install django-cursor-pagination

Usage

from cursor_pagination import CursorPaginator

from myapp.models import Post


def posts_api(request, after=None):
    qs = Post.objects.all()
    page_size = 10
    paginator = CursorPaginator(qs, ordering=('-created', '-id'))
    page = paginator.page(first=page_size, after=after)
    data = {
        'objects': [serialize_page(p) for p in page],
        'has_next_page': page.has_next,
        'last_cursor': paginator.cursor(page[-1])
    }
    return data

Reverse pagination can be achieved by using the last and before arguments to paginator.page.

Caveats

  • The ordering specified must uniquely identify the object.
  • If there are multiple ordering fields, then they must all have the same direction.
  • If a cursor is given and it does not refer to a valid object, the values of has_previous (for after) or has_next (for before) will always return True.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial