Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


build-status-image pypi-version


Pagination utilities for Django REST Framework to allow for pagination by a mutable, but time-ordered field (like 'modified').

Why use this?

If you want to ask your REST endpoint "give me everything that was updated since XXX", but where that answer might span multiple pages.

More completely...if you have:

  • a collection that you want to retrieve in a paginated way;
  • ordered by a temporal field (like a "modified" timestamp); but
  • the collection is mutable, such that it can change while you are paginating through it.

then using this library will guarantee that your pagination will only exhaust once every update has been seen.

For example, say your collection has five elements [A, B, C, D, E] and they are 'modified' in that order.

  1. You begin pagination with a page size of 3.
  2. You receive the first page which contains [A, B, C] and a link to the next page.
  3. Something modifies A and B, causing the ordered list to look like: [C, D, E, A, B].
  4. You collect the next page which returns with [D, E, A] and a new link to the next page.
  5. Something modifies A again, causing the ordered list to look like: [C, D, E, B, A].
  6. You collect the next page which returns with [B, A] and no link to the next page, indicating that you are done.

This library also takes care of the situation where all the modified times of more than one page of results are identical.


  • Python (2.7, 3.3, 3.4)
  • Django (1.8+)
  • Django REST Framework (3.1+)

Important notes

The layout of the docs and the Git project were borrowed from:

  • drf-proxy-pagination
  • django-nsync (which was borrowed from other people too!)


Install using pip

$ pip install drf-timeordered-pagination

In, hook up your own integration into the pagination, or use one of the provided ones like so:

class ExampleClass(django.Model):
    modified = DateTimeField(...)

from timeordered_pagination.views import TimeOrderedPaginationViewSetMixin
class ExampleClassView(



Install testing requirements.

$ pip install -r requirements.txt

Run with pytest.

$ py.test

You can also use the excellent tox testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

$ tox


To build the documentation, you’ll need to install mkdocs.

$ pip install mkdocs

To preview the documentation:

$ mkdocs serve
Running at:

To build the documentation:

$ mkdocs build


A set of Django Rest Framework utility classes to allow stable pagination by a mutable, time-ordered field (like 'by modified').





No packages published