From 03c4eb11305dcc9f366cdd008a5985bcf47c13ce Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Sat, 20 Dec 2014 16:32:07 +0000
Subject: Use custom ListSerializer for pagination if one is specified on the
 serializer.

---
 rest_framework/pagination.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index fb451285..f46b0dfa 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -68,7 +68,12 @@ class BasePaginationSerializer(serializers.Serializer):
         except AttributeError:
             object_serializer = DefaultObjectSerializer
 
-        self.fields[results_field] = serializers.ListSerializer(
+        try:
+            list_serializer_class = object_serializer.Meta.list_serializer_class
+        except AttributeError:
+            list_serializer_class = serializers.ListSerializer
+
+        self.fields[results_field] = list_serializer_class(
             child=object_serializer(),
             source='object_list'
         )
-- 
cgit v1.2.3


From c2e00a075cb4b44c644ad5d62f2be0fd19e62c5f Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Fri, 26 Dec 2014 15:25:13 +0000
Subject: Paginated serializers should get context.

---
 rest_framework/pagination.py | 1 +
 1 file changed, 1 insertion(+)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index f46b0dfa..f31e5fa4 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -77,6 +77,7 @@ class BasePaginationSerializer(serializers.Serializer):
             child=object_serializer(),
             source='object_list'
         )
+        self.fields[results_field].bind(field_name=results_field, parent=self)
 
 
 class PaginationSerializer(BasePaginationSerializer):
-- 
cgit v1.2.3


From 73feaf6299827607eab94ce96b77b73671880626 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Fri, 9 Jan 2015 15:30:36 +0000
Subject: First pass at 3.1 pagination API

---
 rest_framework/pagination.py | 219 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 162 insertions(+), 57 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index f31e5fa4..da2d60a4 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -3,87 +3,192 @@ Pagination serializers determine the structure of the output that should
 be used for paginated responses.
 """
 from __future__ import unicode_literals
-from rest_framework import serializers
+from django.core.paginator import InvalidPage, Paginator as DjangoPaginator
+from django.utils import six
+from django.utils.translation import ugettext as _
+from rest_framework.compat import OrderedDict
+from rest_framework.exceptions import NotFound
+from rest_framework.response import Response
+from rest_framework.settings import api_settings
 from rest_framework.templatetags.rest_framework import replace_query_param
 
 
-class NextPageField(serializers.Field):
+def _strict_positive_int(integer_string, cutoff=None):
     """
-    Field that returns a link to the next page in paginated results.
+    Cast a string to a strictly positive integer.
     """
-    page_field = 'page'
-
-    def to_representation(self, value):
-        if not value.has_next():
-            return None
-        page = value.next_page_number()
-        request = self.context.get('request')
-        url = request and request.build_absolute_uri() or ''
-        return replace_query_param(url, self.page_field, page)
+    ret = int(integer_string)
+    if ret <= 0:
+        raise ValueError()
+    if cutoff:
+        ret = min(ret, cutoff)
+    return ret
 
 
-class PreviousPageField(serializers.Field):
-    """
-    Field that returns a link to the previous page in paginated results.
-    """
-    page_field = 'page'
+class BasePagination(object):
+    def paginate_queryset(self, queryset, request):
+        raise NotImplemented('paginate_queryset() must be implemented.')
 
-    def to_representation(self, value):
-        if not value.has_previous():
-            return None
-        page = value.previous_page_number()
-        request = self.context.get('request')
-        url = request and request.build_absolute_uri() or ''
-        return replace_query_param(url, self.page_field, page)
+    def get_paginated_response(self, data, page, request):
+        raise NotImplemented('get_paginated_response() must be implemented.')
 
 
-class DefaultObjectSerializer(serializers.ReadOnlyField):
+class PageNumberPagination(BasePagination):
     """
-    If no object serializer is specified, then this serializer will be applied
-    as the default.
+    A simple page number based style that supports page numbers as
+    query parameters. For example:
+
+    http://api.example.org/accounts/?page=4
+    http://api.example.org/accounts/?page=4&page_size=100
     """
+    # The default page size.
+    # Defaults to `None`, meaning pagination is disabled.
+    paginate_by = api_settings.PAGINATE_BY
 
-    def __init__(self, source=None, many=None, context=None):
-        # Note: Swallow context and many kwargs - only required for
-        # eg. ModelSerializer.
-        super(DefaultObjectSerializer, self).__init__(source=source)
+    # Client can control the page using this query parameter.
+    page_query_param = 'page'
 
+    # Client can control the page size using this query parameter.
+    # Default is 'None'. Set to eg 'page_size' to enable usage.
+    paginate_by_param = api_settings.PAGINATE_BY_PARAM
 
-class BasePaginationSerializer(serializers.Serializer):
-    """
-    A base class for pagination serializers to inherit from,
-    to make implementing custom serializers more easy.
-    """
-    results_field = 'results'
+    # Set to an integer to limit the maximum page size the client may request.
+    # Only relevant if 'paginate_by_param' has also been set.
+    max_paginate_by = api_settings.MAX_PAGINATE_BY
 
-    def __init__(self, *args, **kwargs):
+    def paginate_queryset(self, queryset, request, view):
         """
-        Override init to add in the object serializer field on-the-fly.
+        Paginate a queryset if required, either returning a page object,
+        or `None` if pagination is not configured for this view.
         """
-        super(BasePaginationSerializer, self).__init__(*args, **kwargs)
-        results_field = self.results_field
+        for attr in (
+            'paginate_by', 'page_query_param',
+            'paginate_by_param', 'max_paginate_by'
+        ):
+            if hasattr(view, attr):
+                setattr(self, attr, getattr(view, attr))
+
+        page_size = self.get_page_size(request)
+        if not page_size:
+            return None
 
+        paginator = DjangoPaginator(queryset, page_size)
+        page_string = request.query_params.get(self.page_query_param, 1)
         try:
-            object_serializer = self.Meta.object_serializer_class
-        except AttributeError:
-            object_serializer = DefaultObjectSerializer
+            page_number = paginator.validate_number(page_string)
+        except InvalidPage:
+            if page_string == 'last':
+                page_number = paginator.num_pages
+            else:
+                msg = _(
+                    'Choose a valid page number. Page numbers must be a '
+                    'whole number, or must be the string "last".'
+                )
+                raise NotFound(msg)
 
         try:
-            list_serializer_class = object_serializer.Meta.list_serializer_class
-        except AttributeError:
-            list_serializer_class = serializers.ListSerializer
+            self.page = paginator.page(page_number)
+        except InvalidPage as exc:
+            msg = _('Invalid page "{page_number}": {message}.').format(
+                page_number=page_number, message=six.text_type(exc)
+            )
+            raise NotFound(msg)
+
+        self.request = request
+        return self.page
+
+    def get_paginated_response(self, objects):
+        return Response(OrderedDict([
+            ('count', self.page.paginator.count),
+            ('next', self.get_next_link()),
+            ('previous', self.get_previous_link()),
+            ('results', objects)
+        ]))
+
+    def get_page_size(self, request):
+        if self.paginate_by_param:
+            try:
+                return _strict_positive_int(
+                    request.query_params[self.paginate_by_param],
+                    cutoff=self.max_paginate_by
+                )
+            except (KeyError, ValueError):
+                pass
+
+        return self.paginate_by
+
+    def get_next_link(self):
+        if not self.page.has_next():
+            return None
+        url = self.request.build_absolute_uri()
+        page_number = self.page.next_page_number()
+        return replace_query_param(url, self.page_query_param, page_number)
 
-        self.fields[results_field] = list_serializer_class(
-            child=object_serializer(),
-            source='object_list'
-        )
-        self.fields[results_field].bind(field_name=results_field, parent=self)
+    def get_previous_link(self):
+        if not self.page.has_previous():
+            return None
+        url = self.request.build_absolute_uri()
+        page_number = self.page.previous_page_number()
+        return replace_query_param(url, self.page_query_param, page_number)
 
 
-class PaginationSerializer(BasePaginationSerializer):
+class LimitOffsetPagination(BasePagination):
     """
-    A default implementation of a pagination serializer.
+    A limit/offset based style. For example:
+
+    http://api.example.org/accounts/?limit=100
+    http://api.example.org/accounts/?offset=400&limit=100
     """
-    count = serializers.ReadOnlyField(source='paginator.count')
-    next = NextPageField(source='*')
-    previous = PreviousPageField(source='*')
+    default_limit = api_settings.PAGINATE_BY
+    limit_query_param = 'limit'
+    offset_query_param = 'offset'
+    max_limit = None
+
+    def paginate_queryset(self, queryset, request, view):
+        self.limit = self.get_limit(request)
+        self.offset = self.get_offset(request)
+        self.count = queryset.count()
+        self.request = request
+        return queryset[self.offset:self.offset + self.limit]
+
+    def get_paginated_response(self, objects):
+        return Response(OrderedDict([
+            ('count', self.count),
+            ('next', self.get_next_link()),
+            ('previous', self.get_previous_link()),
+            ('results', objects)
+        ]))
+
+    def get_limit(self, request):
+        if self.limit_query_param:
+            try:
+                return _strict_positive_int(
+                    request.query_params[self.limit_query_param],
+                    cutoff=self.max_limit
+                )
+            except (KeyError, ValueError):
+                pass
+
+        return self.default_limit
+
+    def get_offset(self, request):
+        try:
+            return _strict_positive_int(
+                request.query_params[self.offset_query_param],
+            )
+        except (KeyError, ValueError):
+            return 0
+
+    def get_next_link(self, page):
+        if self.offset + self.limit >= self.count:
+            return None
+        url = self.request.build_absolute_uri()
+        offset = self.offset + self.limit
+        return replace_query_param(url, self.offset_query_param, offset)
+
+    def get_previous_link(self, page):
+        if self.offset - self.limit < 0:
+            return None
+        url = self.request.build_absolute_uri()
+        offset = self.offset - self.limit
+        return replace_query_param(url, self.offset_query_param, offset)
-- 
cgit v1.2.3


From 1bcec3a0ac4346b31b655a08505d3e3dc2156604 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 13 Jan 2015 17:14:13 +0000
Subject: API tweaks and pagination documentation

---
 rest_framework/pagination.py | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index da2d60a4..b9d48796 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -25,11 +25,21 @@ def _strict_positive_int(integer_string, cutoff=None):
     return ret
 
 
+def _get_count(queryset):
+    """
+    Determine an object count, supporting either querysets or regular lists.
+    """
+    try:
+        return queryset.count()
+    except AttributeError:
+        return len(queryset)
+
+
 class BasePagination(object):
-    def paginate_queryset(self, queryset, request):
+    def paginate_queryset(self, queryset, request, view):
         raise NotImplemented('paginate_queryset() must be implemented.')
 
-    def get_paginated_response(self, data, page, request):
+    def get_paginated_response(self, data):
         raise NotImplemented('get_paginated_response() must be implemented.')
 
 
@@ -58,8 +68,8 @@ class PageNumberPagination(BasePagination):
 
     def paginate_queryset(self, queryset, request, view):
         """
-        Paginate a queryset if required, either returning a page object,
-        or `None` if pagination is not configured for this view.
+        Paginate a queryset if required, either returning a
+        page object, or `None` if pagination is not configured for this view.
         """
         for attr in (
             'paginate_by', 'page_query_param',
@@ -97,12 +107,12 @@ class PageNumberPagination(BasePagination):
         self.request = request
         return self.page
 
-    def get_paginated_response(self, objects):
+    def get_paginated_response(self, data):
         return Response(OrderedDict([
             ('count', self.page.paginator.count),
             ('next', self.get_next_link()),
             ('previous', self.get_previous_link()),
-            ('results', objects)
+            ('results', data)
         ]))
 
     def get_page_size(self, request):
@@ -147,16 +157,16 @@ class LimitOffsetPagination(BasePagination):
     def paginate_queryset(self, queryset, request, view):
         self.limit = self.get_limit(request)
         self.offset = self.get_offset(request)
-        self.count = queryset.count()
+        self.count = _get_count(queryset)
         self.request = request
         return queryset[self.offset:self.offset + self.limit]
 
-    def get_paginated_response(self, objects):
+    def get_paginated_response(self, data):
         return Response(OrderedDict([
             ('count', self.count),
             ('next', self.get_next_link()),
             ('previous', self.get_previous_link()),
-            ('results', objects)
+            ('results', data)
         ]))
 
     def get_limit(self, request):
-- 
cgit v1.2.3


From 3833a5bb8a9174e5fb09dac59a964eff24b6065e Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 14 Jan 2015 16:51:26 +0000
Subject: Include pagination control in browsable API

---
 rest_framework/pagination.py | 90 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index b9d48796..bd343c0d 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -3,14 +3,18 @@ Pagination serializers determine the structure of the output that should
 be used for paginated responses.
 """
 from __future__ import unicode_literals
+from collections import namedtuple
 from django.core.paginator import InvalidPage, Paginator as DjangoPaginator
+from django.template import Context, loader
 from django.utils import six
 from django.utils.translation import ugettext as _
 from rest_framework.compat import OrderedDict
 from rest_framework.exceptions import NotFound
 from rest_framework.response import Response
 from rest_framework.settings import api_settings
-from rest_framework.templatetags.rest_framework import replace_query_param
+from rest_framework.templatetags.rest_framework import (
+    replace_query_param, remove_query_param
+)
 
 
 def _strict_positive_int(integer_string, cutoff=None):
@@ -35,6 +39,49 @@ def _get_count(queryset):
         return len(queryset)
 
 
+def _get_displayed_page_numbers(current, final):
+    """
+    This utility function determines a list of page numbers to display.
+    This gives us a nice contextually relevant set of page numbers.
+
+    For example:
+    current=14, final=16 -> [1, None, 13, 14, 15, 16]
+    """
+    assert current >= 1
+    assert final >= current
+
+    # We always include the first two pages, last two pages, and
+    # two pages either side of the current page.
+    included = set((
+        1,
+        current - 1, current, current + 1,
+        final
+    ))
+
+    # If the break would only exclude a single page number then we
+    # may as well include the page number instead of the break.
+    if current == 4:
+        included.add(2)
+    if current == final - 3:
+        included.add(final - 1)
+
+    # Now sort the page numbers and drop anything outside the limits.
+    included = [
+        idx for idx in sorted(list(included))
+        if idx > 0 and idx <= final
+    ]
+
+    # Finally insert any `...` breaks
+    if current > 4:
+        included.insert(1, None)
+    if current < final - 3:
+        included.insert(len(included) - 1, None)
+    return included
+
+
+PageLink = namedtuple('PageLink', ['url', 'number', 'is_active', 'is_break'])
+
+
 class BasePagination(object):
     def paginate_queryset(self, queryset, request, view):
         raise NotImplemented('paginate_queryset() must be implemented.')
@@ -66,6 +113,8 @@ class PageNumberPagination(BasePagination):
     # Only relevant if 'paginate_by_param' has also been set.
     max_paginate_by = api_settings.MAX_PAGINATE_BY
 
+    template = 'rest_framework/pagination/numbers.html'
+
     def paginate_queryset(self, queryset, request, view):
         """
         Paginate a queryset if required, either returning a
@@ -104,6 +153,8 @@ class PageNumberPagination(BasePagination):
             )
             raise NotFound(msg)
 
+        # Indicate that the browsable API should display pagination controls.
+        self.mark_as_used = True
         self.request = request
         return self.page
 
@@ -139,8 +190,45 @@ class PageNumberPagination(BasePagination):
             return None
         url = self.request.build_absolute_uri()
         page_number = self.page.previous_page_number()
+        if page_number == 1:
+            return remove_query_param(url, self.page_query_param)
         return replace_query_param(url, self.page_query_param, page_number)
 
+    def to_html(self):
+        current = self.page.number
+        final = self.page.paginator.num_pages
+
+        page_links = []
+        base_url = self.request.build_absolute_uri()
+        for page_number in _get_displayed_page_numbers(current, final):
+            if page_number is None:
+                page_link = PageLink(
+                    url=None,
+                    number=None,
+                    is_active=False,
+                    is_break=True
+                )
+            else:
+                if page_number == 1:
+                    url = remove_query_param(base_url, self.page_query_param)
+                else:
+                    url = replace_query_param(url, self.page_query_param, page_number)
+                page_link = PageLink(
+                    url=url,
+                    number=page_number,
+                    is_active=(page_number == current),
+                    is_break=False
+                )
+            page_links.append(page_link)
+
+        template = loader.get_template(self.template)
+        context = Context({
+            'previous_url': self.get_previous_link(),
+            'next_url': self.get_next_link(),
+            'page_links': page_links
+        })
+        return template.render(context)
+
 
 class LimitOffsetPagination(BasePagination):
     """
-- 
cgit v1.2.3


From 313aa727e3c44016e531a7af75051fc6e6d7cb96 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 14 Jan 2015 17:46:41 +0000
Subject: Tweaks

---
 rest_framework/pagination.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index bd343c0d..69d0f77d 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -46,6 +46,12 @@ def _get_displayed_page_numbers(current, final):
 
     For example:
     current=14, final=16 -> [1, None, 13, 14, 15, 16]
+
+    This implementation gives one page to each side of the cursor,
+    for an implementation which gives two pages to each side of the cursor,
+    which is a copy of how GitHub treat pagination in their issue lists, see:
+
+    https://gist.github.com/tomchristie/321140cebb1c4a558b15
     """
     assert current >= 1
     assert final >= current
@@ -60,10 +66,12 @@ def _get_displayed_page_numbers(current, final):
 
     # If the break would only exclude a single page number then we
     # may as well include the page number instead of the break.
-    if current == 4:
+    if current <= 4:
         included.add(2)
-    if current == final - 3:
+        included.add(3)
+    if current >= final - 3:
         included.add(final - 1)
+        included.add(final - 2)
 
     # Now sort the page numbers and drop anything outside the limits.
     included = [
-- 
cgit v1.2.3


From d76e83dd78627a0cf4bcd4b28a7710fb678d8d4e Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 15 Jan 2015 16:52:07 +0000
Subject: Tweaks, and add pagination controls for offset/limit.

---
 rest_framework/pagination.py | 126 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 96 insertions(+), 30 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 69d0f77d..2b78f1f7 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -29,6 +29,15 @@ def _strict_positive_int(integer_string, cutoff=None):
     return ret
 
 
+def _divide_with_ceil(a, b):
+    """
+    Returns 'a' divded by 'b', with any remainder rounded up.
+    """
+    if a % b:
+        return (a / b) + 1
+    return a / b
+
+
 def _get_count(queryset):
     """
     Determine an object count, supporting either querysets or regular lists.
@@ -48,14 +57,21 @@ def _get_displayed_page_numbers(current, final):
     current=14, final=16 -> [1, None, 13, 14, 15, 16]
 
     This implementation gives one page to each side of the cursor,
-    for an implementation which gives two pages to each side of the cursor,
-    which is a copy of how GitHub treat pagination in their issue lists, see:
+    or two pages to the side when the cursor is at the edge, then
+    ensures that any breaks between non-continous page numbers never
+    remove only a single page.
+
+    For an alernativative implementation which gives two pages to each side of
+    the cursor, eg. as in GitHub issue list pagination, see:
 
     https://gist.github.com/tomchristie/321140cebb1c4a558b15
     """
     assert current >= 1
     assert final >= current
 
+    if final <= 5:
+        return range(1, final + 1)
+
     # We always include the first two pages, last two pages, and
     # two pages either side of the current page.
     included = set((
@@ -87,16 +103,46 @@ def _get_displayed_page_numbers(current, final):
     return included
 
 
+def _get_page_links(page_numbers, current, url_func):
+    """
+    Given a list of page numbers and `None` page breaks,
+    return a list of `PageLink` objects.
+    """
+    page_links = []
+    for page_number in page_numbers:
+        if page_number is None:
+            page_link = PageLink(
+                url=None,
+                number=None,
+                is_active=False,
+                is_break=True
+            )
+        else:
+            page_link = PageLink(
+                url=url_func(page_number),
+                number=page_number,
+                is_active=(page_number == current),
+                is_break=False
+            )
+        page_links.append(page_link)
+    return page_links
+
+
 PageLink = namedtuple('PageLink', ['url', 'number', 'is_active', 'is_break'])
 
 
 class BasePagination(object):
+    display_page_controls = False
+
     def paginate_queryset(self, queryset, request, view):
         raise NotImplemented('paginate_queryset() must be implemented.')
 
     def get_paginated_response(self, data):
         raise NotImplemented('get_paginated_response() must be implemented.')
 
+    def to_html(self):
+        raise NotImplemented('to_html() must be implemented to display page controls.')
+
 
 class PageNumberPagination(BasePagination):
     """
@@ -161,8 +207,9 @@ class PageNumberPagination(BasePagination):
             )
             raise NotFound(msg)
 
-        # Indicate that the browsable API should display pagination controls.
-        self.mark_as_used = True
+        if paginator.count > 1:
+            # The browsable API should display pagination controls.
+            self.display_page_controls = True
         self.request = request
         return self.page
 
@@ -203,31 +250,17 @@ class PageNumberPagination(BasePagination):
         return replace_query_param(url, self.page_query_param, page_number)
 
     def to_html(self):
-        current = self.page.number
-        final = self.page.paginator.num_pages
-
-        page_links = []
         base_url = self.request.build_absolute_uri()
-        for page_number in _get_displayed_page_numbers(current, final):
-            if page_number is None:
-                page_link = PageLink(
-                    url=None,
-                    number=None,
-                    is_active=False,
-                    is_break=True
-                )
+        def page_number_to_url(page_number):
+            if page_number == 1:
+                return remove_query_param(base_url, self.page_query_param)
             else:
-                if page_number == 1:
-                    url = remove_query_param(base_url, self.page_query_param)
-                else:
-                    url = replace_query_param(url, self.page_query_param, page_number)
-                page_link = PageLink(
-                    url=url,
-                    number=page_number,
-                    is_active=(page_number == current),
-                    is_break=False
-                )
-            page_links.append(page_link)
+                return replace_query_param(base_url, self.page_query_param, page_number)
+
+        current = self.page.number
+        final = self.page.paginator.num_pages
+        page_numbers = _get_displayed_page_numbers(current, final)
+        page_links = _get_page_links(page_numbers, current, page_number_to_url)
 
         template = loader.get_template(self.template)
         context = Context({
@@ -250,11 +283,15 @@ class LimitOffsetPagination(BasePagination):
     offset_query_param = 'offset'
     max_limit = None
 
+    template = 'rest_framework/pagination/numbers.html'
+
     def paginate_queryset(self, queryset, request, view):
         self.limit = self.get_limit(request)
         self.offset = self.get_offset(request)
         self.count = _get_count(queryset)
         self.request = request
+        if self.count > self.limit:
+            self.display_page_controls = True
         return queryset[self.offset:self.offset + self.limit]
 
     def get_paginated_response(self, data):
@@ -285,16 +322,45 @@ class LimitOffsetPagination(BasePagination):
         except (KeyError, ValueError):
             return 0
 
-    def get_next_link(self, page):
+    def get_next_link(self):
         if self.offset + self.limit >= self.count:
             return None
+
         url = self.request.build_absolute_uri()
         offset = self.offset + self.limit
         return replace_query_param(url, self.offset_query_param, offset)
 
-    def get_previous_link(self, page):
-        if self.offset - self.limit < 0:
+    def get_previous_link(self):
+        if self.offset <= 0:
             return None
+
         url = self.request.build_absolute_uri()
+
+        if self.offset - self.limit <= 0:
+            return remove_query_param(url, self.offset_query_param)
+
         offset = self.offset - self.limit
         return replace_query_param(url, self.offset_query_param, offset)
+
+    def to_html(self):
+        base_url = self.request.build_absolute_uri()
+        current = _divide_with_ceil(self.offset, self.limit) + 1
+        final = _divide_with_ceil(self.count, self.limit)
+
+        def page_number_to_url(page_number):
+            if page_number == 1:
+                return remove_query_param(base_url, self.offset_query_param)
+            else:
+                offset = self.offset + ((page_number - current) * self.limit)
+                return replace_query_param(base_url, self.offset_query_param, offset)
+
+        page_numbers = _get_displayed_page_numbers(current, final)
+        page_links = _get_page_links(page_numbers, current, page_number_to_url)
+
+        template = loader.get_template(self.template)
+        context = Context({
+            'previous_url': self.get_previous_link(),
+            'next_url': self.get_next_link(),
+            'page_links': page_links
+        })
+        return template.render(context)
\ No newline at end of file
-- 
cgit v1.2.3


From 68dfa369b5ca877643b41c8df7c5fc0c786a9f08 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 15 Jan 2015 16:55:04 +0000
Subject: Flake 8 fixes

---
 rest_framework/pagination.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 2b78f1f7..61b8e07a 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -251,6 +251,7 @@ class PageNumberPagination(BasePagination):
 
     def to_html(self):
         base_url = self.request.build_absolute_uri()
+
         def page_number_to_url(page_number):
             if page_number == 1:
                 return remove_query_param(base_url, self.page_query_param)
@@ -363,4 +364,4 @@ class LimitOffsetPagination(BasePagination):
             'next_url': self.get_next_link(),
             'page_links': page_links
         })
-        return template.render(context)
\ No newline at end of file
+        return template.render(context)
-- 
cgit v1.2.3


From 53edd37df5aa0ac29dbe7824db2e33da1d901f98 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 15 Jan 2015 21:07:05 +0000
Subject: Tests for LimitOffsetPagination

---
 rest_framework/pagination.py | 57 +++++++++++++++++++++-----------------------
 1 file changed, 27 insertions(+), 30 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 61b8e07a..0dac5683 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -44,7 +44,7 @@ def _get_count(queryset):
     """
     try:
         return queryset.count()
-    except AttributeError:
+    except (AttributeError, TypeError):
         return len(queryset)
 
 
@@ -111,12 +111,7 @@ def _get_page_links(page_numbers, current, url_func):
     page_links = []
     for page_number in page_numbers:
         if page_number is None:
-            page_link = PageLink(
-                url=None,
-                number=None,
-                is_active=False,
-                is_break=True
-            )
+            page_link = PAGE_BREAK
         else:
             page_link = PageLink(
                 url=url_func(page_number),
@@ -130,11 +125,13 @@ def _get_page_links(page_numbers, current, url_func):
 
 PageLink = namedtuple('PageLink', ['url', 'number', 'is_active', 'is_break'])
 
+PAGE_BREAK = PageLink(url=None, number=None, is_active=False, is_break=True)
+
 
 class BasePagination(object):
     display_page_controls = False
 
-    def paginate_queryset(self, queryset, request, view):
+    def paginate_queryset(self, queryset, request, view=None):
         raise NotImplemented('paginate_queryset() must be implemented.')
 
     def get_paginated_response(self, data):
@@ -167,9 +164,11 @@ class PageNumberPagination(BasePagination):
     # Only relevant if 'paginate_by_param' has also been set.
     max_paginate_by = api_settings.MAX_PAGINATE_BY
 
+    last_page_strings = ('last',)
+
     template = 'rest_framework/pagination/numbers.html'
 
-    def paginate_queryset(self, queryset, request, view):
+    def paginate_queryset(self, queryset, request, view=None):
         """
         Paginate a queryset if required, either returning a
         page object, or `None` if pagination is not configured for this view.
@@ -186,18 +185,9 @@ class PageNumberPagination(BasePagination):
             return None
 
         paginator = DjangoPaginator(queryset, page_size)
-        page_string = request.query_params.get(self.page_query_param, 1)
-        try:
-            page_number = paginator.validate_number(page_string)
-        except InvalidPage:
-            if page_string == 'last':
-                page_number = paginator.num_pages
-            else:
-                msg = _(
-                    'Choose a valid page number. Page numbers must be a '
-                    'whole number, or must be the string "last".'
-                )
-                raise NotFound(msg)
+        page_number = request.query_params.get(self.page_query_param, 1)
+        if page_number in self.last_page_strings:
+            page_number = paginator.num_pages
 
         try:
             self.page = paginator.page(page_number)
@@ -210,6 +200,7 @@ class PageNumberPagination(BasePagination):
         if paginator.count > 1:
             # The browsable API should display pagination controls.
             self.display_page_controls = True
+
         self.request = request
         return self.page
 
@@ -249,7 +240,7 @@ class PageNumberPagination(BasePagination):
             return remove_query_param(url, self.page_query_param)
         return replace_query_param(url, self.page_query_param, page_number)
 
-    def to_html(self):
+    def get_html_context(self):
         base_url = self.request.build_absolute_uri()
 
         def page_number_to_url(page_number):
@@ -263,12 +254,15 @@ class PageNumberPagination(BasePagination):
         page_numbers = _get_displayed_page_numbers(current, final)
         page_links = _get_page_links(page_numbers, current, page_number_to_url)
 
-        template = loader.get_template(self.template)
-        context = Context({
+        return {
             'previous_url': self.get_previous_link(),
             'next_url': self.get_next_link(),
             'page_links': page_links
-        })
+        }
+
+    def to_html(self):
+        template = loader.get_template(self.template)
+        context = Context(self.get_html_context())
         return template.render(context)
 
 
@@ -286,7 +280,7 @@ class LimitOffsetPagination(BasePagination):
 
     template = 'rest_framework/pagination/numbers.html'
 
-    def paginate_queryset(self, queryset, request, view):
+    def paginate_queryset(self, queryset, request, view=None):
         self.limit = self.get_limit(request)
         self.offset = self.get_offset(request)
         self.count = _get_count(queryset)
@@ -343,7 +337,7 @@ class LimitOffsetPagination(BasePagination):
         offset = self.offset - self.limit
         return replace_query_param(url, self.offset_query_param, offset)
 
-    def to_html(self):
+    def get_html_context(self):
         base_url = self.request.build_absolute_uri()
         current = _divide_with_ceil(self.offset, self.limit) + 1
         final = _divide_with_ceil(self.count, self.limit)
@@ -358,10 +352,13 @@ class LimitOffsetPagination(BasePagination):
         page_numbers = _get_displayed_page_numbers(current, final)
         page_links = _get_page_links(page_numbers, current, page_number_to_url)
 
-        template = loader.get_template(self.template)
-        context = Context({
+        return {
             'previous_url': self.get_previous_link(),
             'next_url': self.get_next_link(),
             'page_links': page_links
-        })
+        }
+
+    def to_html(self):
+        template = loader.get_template(self.template)
+        context = Context(self.get_html_context())
         return template.render(context)
-- 
cgit v1.2.3


From 8b0f25aa0a91cb7b56f9ce4dde4330fe5daaad9b Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Fri, 16 Jan 2015 16:55:46 +0000
Subject: More pagination tests & cleanup

---
 rest_framework/pagination.py | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 0dac5683..c5a364f0 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -131,13 +131,13 @@ PAGE_BREAK = PageLink(url=None, number=None, is_active=False, is_break=True)
 class BasePagination(object):
     display_page_controls = False
 
-    def paginate_queryset(self, queryset, request, view=None):
+    def paginate_queryset(self, queryset, request, view=None):  # pragma: no cover
         raise NotImplemented('paginate_queryset() must be implemented.')
 
-    def get_paginated_response(self, data):
+    def get_paginated_response(self, data):  # pragma: no cover
         raise NotImplemented('get_paginated_response() must be implemented.')
 
-    def to_html(self):
+    def to_html(self):  # pragma: no cover
         raise NotImplemented('to_html() must be implemented to display page controls.')
 
 
@@ -168,10 +168,11 @@ class PageNumberPagination(BasePagination):
 
     template = 'rest_framework/pagination/numbers.html'
 
-    def paginate_queryset(self, queryset, request, view=None):
+    def _handle_backwards_compat(self, view):
         """
-        Paginate a queryset if required, either returning a
-        page object, or `None` if pagination is not configured for this view.
+        Prior to version 3.1, pagination was handled in the view, and the
+        attributes were set there. The attributes should now be set on
+        the pagination class, but the old style is still pending deprecation.
         """
         for attr in (
             'paginate_by', 'page_query_param',
@@ -180,6 +181,13 @@ class PageNumberPagination(BasePagination):
             if hasattr(view, attr):
                 setattr(self, attr, getattr(view, attr))
 
+    def paginate_queryset(self, queryset, request, view=None):
+        """
+        Paginate a queryset if required, either returning a
+        page object, or `None` if pagination is not configured for this view.
+        """
+        self._handle_backwards_compat(view)
+
         page_size = self.get_page_size(request)
         if not page_size:
             return None
@@ -277,7 +285,6 @@ class LimitOffsetPagination(BasePagination):
     limit_query_param = 'limit'
     offset_query_param = 'offset'
     max_limit = None
-
     template = 'rest_framework/pagination/numbers.html'
 
     def paginate_queryset(self, queryset, request, view=None):
@@ -340,7 +347,15 @@ class LimitOffsetPagination(BasePagination):
     def get_html_context(self):
         base_url = self.request.build_absolute_uri()
         current = _divide_with_ceil(self.offset, self.limit) + 1
-        final = _divide_with_ceil(self.count, self.limit)
+        # The number of pages is a little bit fiddly.
+        # We need to sum both the number of pages from current offset to end
+        # plus the number of pages up to the current offset.
+        # When offset is not strictly divisible by the limit then we may
+        # end up introducing an extra page as an artifact.
+        final = (
+            _divide_with_ceil(self.count - self.offset, self.limit) +
+            _divide_with_ceil(self.offset, self.limit)
+        )
 
         def page_number_to_url(page_number):
             if page_number == 1:
-- 
cgit v1.2.3


From 86d2774cf30351fd4174e97501532056ed0d8f95 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Fri, 16 Jan 2015 20:30:46 +0000
Subject: Fix compat issues

---
 rest_framework/pagination.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index c5a364f0..1b7524c6 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -12,7 +12,7 @@ from rest_framework.compat import OrderedDict
 from rest_framework.exceptions import NotFound
 from rest_framework.response import Response
 from rest_framework.settings import api_settings
-from rest_framework.templatetags.rest_framework import (
+from rest_framework.utils.urls import (
     replace_query_param, remove_query_param
 )
 
@@ -34,8 +34,8 @@ def _divide_with_ceil(a, b):
     Returns 'a' divded by 'b', with any remainder rounded up.
     """
     if a % b:
-        return (a / b) + 1
-    return a / b
+        return (a // b) + 1
+    return a // b
 
 
 def _get_count(queryset):
@@ -70,7 +70,7 @@ def _get_displayed_page_numbers(current, final):
     assert final >= current
 
     if final <= 5:
-        return range(1, final + 1)
+        return list(range(1, final + 1))
 
     # We always include the first two pages, last two pages, and
     # two pages either side of the current page.
-- 
cgit v1.2.3


From 4919492582547d227a22852ad2339fa73739cc94 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Sat, 17 Jan 2015 00:10:43 +0000
Subject: First pass at cursor pagination

---
 rest_framework/pagination.py | 51 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 1b7524c6..89d6f9f4 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -3,10 +3,12 @@ Pagination serializers determine the structure of the output that should
 be used for paginated responses.
 """
 from __future__ import unicode_literals
+from base64 import b64encode, b64decode
 from collections import namedtuple
 from django.core.paginator import InvalidPage, Paginator as DjangoPaginator
 from django.template import Context, loader
 from django.utils import six
+from django.utils.six.moves.urllib import parse as urlparse
 from django.utils.translation import ugettext as _
 from rest_framework.compat import OrderedDict
 from rest_framework.exceptions import NotFound
@@ -377,3 +379,52 @@ class LimitOffsetPagination(BasePagination):
         template = loader.get_template(self.template)
         context = Context(self.get_html_context())
         return template.render(context)
+
+
+class CursorPagination(BasePagination):
+    # reverse
+    # limit
+    # multiple orderings
+    cursor_query_param = 'cursor'
+    page_size = 5
+
+    def paginate_queryset(self, queryset, request, view=None):
+        self.base_url = request.build_absolute_uri()
+        self.ordering = self.get_ordering()
+        encoded = request.query_params.get(self.cursor_query_param)
+
+        if encoded is None:
+            cursor = None
+        else:
+            cursor = self.decode_cursor(encoded, self.ordering)
+
+        if cursor is not None:
+            kwargs = {self.ordering + '__gt': cursor}
+            queryset = queryset.filter(**kwargs)
+
+        results = list(queryset[:self.page_size + 1])
+        self.page = results[:self.page_size]
+        self.has_next = len(results) > len(self.page)
+        return self.page
+
+    def get_next_link(self):
+        if not self.has_next:
+            return None
+        last_item = self.page[-1]
+        cursor = self.get_cursor_from_instance(last_item, self.ordering)
+        encoded = self.encode_cursor(cursor, self.ordering)
+        return replace_query_param(self.base_url, self.cursor_query_param, encoded)
+
+    def get_ordering(self):
+        return 'created'
+
+    def get_cursor_from_instance(self, instance, ordering):
+        return getattr(instance, ordering)
+
+    def decode_cursor(self, encoded, ordering):
+        items = urlparse.parse_qs(b64decode(encoded))
+        return items.get(ordering)[0]
+
+    def encode_cursor(self, cursor, ordering):
+        items = [(ordering, cursor)]
+        return b64encode(urlparse.urlencode(items, doseq=True))
-- 
cgit v1.2.3


From 492f3c410d3a91a3f37218e93485a693d9078000 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Sat, 17 Jan 2015 00:59:02 +0000
Subject: Cleaning up cursor implementation

---
 rest_framework/pagination.py | 51 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 38 insertions(+), 13 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 89d6f9f4..3984da13 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -381,10 +381,33 @@ class LimitOffsetPagination(BasePagination):
         return template.render(context)
 
 
+Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
+
+
+def decode_cursor(encoded):
+    tokens = urlparse.parse_qs(b64decode(encoded))
+    try:
+        offset = int(tokens['offset'][0])
+        reverse = bool(int(tokens['reverse'][0]))
+        position = tokens['position'][0]
+    except (TypeError, ValueError):
+        return None
+
+    return Cursor(offset=offset, reverse=reverse, position=position)
+
+
+def encode_cursor(cursor):
+    tokens = {
+        'offset': str(cursor.offset),
+        'reverse': '1' if cursor.reverse else '0',
+        'position': cursor.position
+    }
+    return b64encode(urlparse.urlencode(tokens, doseq=True))
+
+
 class CursorPagination(BasePagination):
     # reverse
     # limit
-    # multiple orderings
     cursor_query_param = 'cursor'
     page_size = 5
 
@@ -396,10 +419,11 @@ class CursorPagination(BasePagination):
         if encoded is None:
             cursor = None
         else:
-            cursor = self.decode_cursor(encoded, self.ordering)
+            cursor = decode_cursor(encoded)
+            # TODO: Invalid cursors should 404
 
         if cursor is not None:
-            kwargs = {self.ordering + '__gt': cursor}
+            kwargs = {self.ordering + '__gt': cursor.position}
             queryset = queryset.filter(**kwargs)
 
         results = list(queryset[:self.page_size + 1])
@@ -411,20 +435,21 @@ class CursorPagination(BasePagination):
         if not self.has_next:
             return None
         last_item = self.page[-1]
-        cursor = self.get_cursor_from_instance(last_item, self.ordering)
-        encoded = self.encode_cursor(cursor, self.ordering)
+        position = self.get_position_from_instance(last_item, self.ordering)
+        cursor = Cursor(offset=0, reverse=False, position=position)
+        encoded = encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
     def get_ordering(self):
         return 'created'
 
-    def get_cursor_from_instance(self, instance, ordering):
-        return getattr(instance, ordering)
+    def get_position_from_instance(self, instance, ordering):
+        return str(getattr(instance, ordering))
 
-    def decode_cursor(self, encoded, ordering):
-        items = urlparse.parse_qs(b64decode(encoded))
-        return items.get(ordering)[0]
+    # def decode_cursor(self, encoded, ordering):
+    #     items = urlparse.parse_qs(b64decode(encoded))
+    #     return items.get(ordering)[0]
 
-    def encode_cursor(self, cursor, ordering):
-        items = [(ordering, cursor)]
-        return b64encode(urlparse.urlencode(items, doseq=True))
+    # def encode_cursor(self, cursor, ordering):
+    #     items = [(ordering, cursor)]
+    #     return b64encode(urlparse.urlencode(items, doseq=True))
-- 
cgit v1.2.3


From dbb684117f6fe0f9c34f98d5e914fc106090cdbc Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 19 Jan 2015 09:24:42 +0000
Subject: Add offset support for cursor pagination

---
 rest_framework/pagination.py | 67 +++++++++++++++++++++++++++++++-------------
 1 file changed, 48 insertions(+), 19 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 3984da13..f56f55ce 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -1,3 +1,4 @@
+# coding: utf-8
 """
 Pagination serializers determine the structure of the output that should
 be used for paginated responses.
@@ -385,7 +386,7 @@ Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
 
 
 def decode_cursor(encoded):
-    tokens = urlparse.parse_qs(b64decode(encoded))
+    tokens = urlparse.parse_qs(b64decode(encoded), keep_blank_values=True)
     try:
         offset = int(tokens['offset'][0])
         reverse = bool(int(tokens['reverse'][0]))
@@ -406,8 +407,7 @@ def encode_cursor(cursor):
 
 
 class CursorPagination(BasePagination):
-    # reverse
-    # limit
+    # TODO: reverse cursors
     cursor_query_param = 'cursor'
     page_size = 5
 
@@ -417,26 +417,63 @@ class CursorPagination(BasePagination):
         encoded = request.query_params.get(self.cursor_query_param)
 
         if encoded is None:
-            cursor = None
+            self.cursor = None
         else:
-            cursor = decode_cursor(encoded)
+            self.cursor = decode_cursor(encoded)
             # TODO: Invalid cursors should 404
 
-        if cursor is not None:
-            kwargs = {self.ordering + '__gt': cursor.position}
+        if self.cursor is not None and self.cursor.position != '':
+            kwargs = {self.ordering + '__gt': self.cursor.position}
             queryset = queryset.filter(**kwargs)
 
-        results = list(queryset[:self.page_size + 1])
+        # The offset is used in order to deal with cases where we have
+        # items with an identical position. This allows the cursors
+        # to gracefully deal with non-unique fields as the ordering.
+        offset = 0 if (self.cursor is None) else self.cursor.offset
+
+        # We fetch an extra item in order to determine if there is a next page.
+        results = list(queryset[offset:offset + self.page_size + 1])
         self.page = results[:self.page_size]
         self.has_next = len(results) > len(self.page)
+        self.next_item = results[-1] if self.has_next else None
         return self.page
 
     def get_next_link(self):
         if not self.has_next:
             return None
-        last_item = self.page[-1]
-        position = self.get_position_from_instance(last_item, self.ordering)
-        cursor = Cursor(offset=0, reverse=False, position=position)
+
+        compare = self.get_position_from_instance(self.next_item, self.ordering)
+        offset = 0
+        for item in reversed(self.page):
+            position = self.get_position_from_instance(item, self.ordering)
+            if position != compare:
+                # The item in this position and the item following it
+                # have different positions. We can use this position as
+                # our marker.
+                break
+
+            # The item in this postion has the same position as the item
+            # following it, we can't use it as a marker position, so increment
+            # the offset and keep seeking to the previous item.
+            compare = position
+            offset += 1
+
+        else:
+            if self.cursor is None:
+                # There were no unique positions in the page, and we were
+                # on the first page, ie. there was no existing cursor.
+                # Our cursor will have an offset equal to the page size,
+                # but no position to filter against yet.
+                offset = self.page_size
+                position = ''
+            else:
+                # There were no unique positions in the page.
+                # Use the position from the existing cursor and increment
+                # it's offset by the page size.
+                offset = self.cursor.offset + self.page_size
+                position = self.cursor.position
+
+        cursor = Cursor(offset=offset, reverse=False, position=position)
         encoded = encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
@@ -445,11 +482,3 @@ class CursorPagination(BasePagination):
 
     def get_position_from_instance(self, instance, ordering):
         return str(getattr(instance, ordering))
-
-    # def decode_cursor(self, encoded, ordering):
-    #     items = urlparse.parse_qs(b64decode(encoded))
-    #     return items.get(ordering)[0]
-
-    # def encode_cursor(self, cursor, ordering):
-    #     items = [(ordering, cursor)]
-    #     return b64encode(urlparse.urlencode(items, doseq=True))
-- 
cgit v1.2.3


From 3cc39ffbceffc5fdbb511d9a10e7732329e8baa4 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 19 Jan 2015 15:22:38 +0000
Subject: NotImplemented -> NotImplementedError

---
 rest_framework/pagination.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 1b7524c6..55c173df 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -132,13 +132,13 @@ class BasePagination(object):
     display_page_controls = False
 
     def paginate_queryset(self, queryset, request, view=None):  # pragma: no cover
-        raise NotImplemented('paginate_queryset() must be implemented.')
+        raise NotImplementedError('paginate_queryset() must be implemented.')
 
     def get_paginated_response(self, data):  # pragma: no cover
-        raise NotImplemented('get_paginated_response() must be implemented.')
+        raise NotImplementedError('get_paginated_response() must be implemented.')
 
     def to_html(self):  # pragma: no cover
-        raise NotImplemented('to_html() must be implemented to display page controls.')
+        raise NotImplementedError('to_html() must be implemented to display page controls.')
 
 
 class PageNumberPagination(BasePagination):
-- 
cgit v1.2.3


From cae9528c54ea13863ea056d40168e8d8df68b276 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 10:28:19 +0000
Subject: Add support for reverse cursors

---
 rest_framework/pagination.py | 126 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 106 insertions(+), 20 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 5482788a..9e22a8bf 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -407,45 +407,84 @@ def encode_cursor(cursor):
 
 
 class CursorPagination(BasePagination):
-    # TODO: reverse cursors
+    # TODO: handle queries with '' as a legitimate position
     cursor_query_param = 'cursor'
     page_size = 5
 
     def paginate_queryset(self, queryset, request, view=None):
         self.base_url = request.build_absolute_uri()
         self.ordering = self.get_ordering()
-        encoded = request.query_params.get(self.cursor_query_param)
 
+        # Determine if we have a cursor, and if so then decode it.
+        encoded = request.query_params.get(self.cursor_query_param)
         if encoded is None:
             self.cursor = None
+            (offset, reverse, current_position) = (0, False, '')
         else:
             self.cursor = decode_cursor(encoded)
+            (offset, reverse, current_position) = self.cursor
             # TODO: Invalid cursors should 404
 
-        if self.cursor is not None and self.cursor.position != '':
-            kwargs = {self.ordering + '__gt': self.cursor.position}
-            queryset = queryset.filter(**kwargs)
+        # Cursor pagination always enforces an ordering.
+        if reverse:
+            queryset = queryset.order_by('-' + self.ordering)
+        else:
+            queryset = queryset.order_by(self.ordering)
 
-        # The offset is used in order to deal with cases where we have
-        # items with an identical position. This allows the cursors
-        # to gracefully deal with non-unique fields as the ordering.
-        offset = 0 if (self.cursor is None) else self.cursor.offset
+        # If we have a cursor with a fixed position then filter by that.
+        if current_position != '':
+            if self.cursor.reverse:
+                kwargs = {self.ordering + '__lt': current_position}
+            else:
+                kwargs = {self.ordering + '__gt': current_position}
+            queryset = queryset.filter(**kwargs)
 
-        # We fetch an extra item in order to determine if there is a next page.
+        # If we have an offset cursor then offset the entire page by that amount.
+        # We also always fetch an extra item in order to determine if there is a
+        # page following on from this one.
         results = list(queryset[offset:offset + self.page_size + 1])
         self.page = results[:self.page_size]
-        self.has_next = len(results) > len(self.page)
-        self.next_item = results[-1] if self.has_next else None
+
+        # Determine the position of the final item following the page.
+        if len(results) > len(self.page):
+            has_following_postion = True
+            following_position = self._get_position_from_instance(results[-1], self.ordering)
+        else:
+            has_following_postion = False
+            following_position = None
+
+        # If we have a reverse queryset, then the query ordering was in reverse
+        # so we need to reverse the items again before returning them to the user.
+        if reverse:
+            self.page = reversed(self.page)
+
+        if reverse:
+            # Determine next and previous positions for reverse cursors.
+            self.has_next = current_position != '' or offset > 0
+            self.has_previous = has_following_postion
+            if self.has_next:
+                self.next_position = current_position
+            if self.has_previous:
+                self.previous_position = following_position
+        else:
+            # Determine next and previous positions for forward cursors.
+            self.has_next = has_following_postion
+            self.has_previous = current_position != '' or offset > 0
+            if self.has_next:
+                self.next_position = following_position
+            if self.has_previous:
+                self.previous_position = current_position
+
         return self.page
 
     def get_next_link(self):
         if not self.has_next:
             return None
 
-        compare = self.get_position_from_instance(self.next_item, self.ordering)
+        compare = self.next_position
         offset = 0
         for item in reversed(self.page):
-            position = self.get_position_from_instance(item, self.ordering)
+            position = self._get_position_from_instance(item, self.ordering)
             if position != compare:
                 # The item in this position and the item following it
                 # have different positions. We can use this position as
@@ -459,26 +498,73 @@ class CursorPagination(BasePagination):
             offset += 1
 
         else:
-            if self.cursor is None:
-                # There were no unique positions in the page, and we were
-                # on the first page, ie. there was no existing cursor.
+            # There were no unique positions in the page.
+            if not self.has_previous:
+                # We are on the first page.
                 # Our cursor will have an offset equal to the page size,
                 # but no position to filter against yet.
                 offset = self.page_size
                 position = ''
+            elif self.cursor.reverse:
+                # The change in direction will introduce a paging artifact,
+                # where we end up skipping forward a few extra items.
+                offset = 0
+                position = self.previous_position
             else:
-                # There were no unique positions in the page.
                 # Use the position from the existing cursor and increment
                 # it's offset by the page size.
                 offset = self.cursor.offset + self.page_size
-                position = self.cursor.position
+                position = self.previous_position
 
         cursor = Cursor(offset=offset, reverse=False, position=position)
         encoded = encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
+    def get_previous_link(self):
+        if not self.has_previous:
+            return None
+
+        compare = self.previous_position
+        offset = 0
+        for item in self.page:
+            position = self._get_position_from_instance(item, self.ordering)
+            if position != compare:
+                # The item in this position and the item following it
+                # have different positions. We can use this position as
+                # our marker.
+                break
+
+            # The item in this postion has the same position as the item
+            # following it, we can't use it as a marker position, so increment
+            # the offset and keep seeking to the previous item.
+            compare = position
+            offset += 1
+
+        else:
+            # There were no unique positions in the page.
+            if not self.has_next:
+                # We are on the final page.
+                # Our cursor will have an offset equal to the page size,
+                # but no position to filter against yet.
+                offset = self.page_size
+                position = ''
+            elif self.cursor.reverse:
+                # Use the position from the existing cursor and increment
+                # it's offset by the page size.
+                offset = self.cursor.offset + self.page_size
+                position = self.next_position
+            else:
+                # The change in direction will introduce a paging artifact,
+                # where we end up skipping back a few extra items.
+                offset = 0
+                position = self.next_position
+
+        cursor = Cursor(offset=offset, reverse=True, position=position)
+        encoded = encode_cursor(cursor)
+        return replace_query_param(self.base_url, self.cursor_query_param, encoded)
+
     def get_ordering(self):
         return 'created'
 
-    def get_position_from_instance(self, instance, ordering):
+    def _get_position_from_instance(self, instance, ordering):
         return str(getattr(instance, ordering))
-- 
cgit v1.2.3


From f1af603fb05fce236a4258e18df8af8888043247 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 10:51:04 +0000
Subject: Tests for reverse pagination

---
 rest_framework/pagination.py | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 9e22a8bf..d5af2ac8 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -408,6 +408,8 @@ def encode_cursor(cursor):
 
 class CursorPagination(BasePagination):
     # TODO: handle queries with '' as a legitimate position
+    # Support case where ordering is already negative
+    # Support tuple orderings
     cursor_query_param = 'cursor'
     page_size = 5
 
-- 
cgit v1.2.3


From 94b5f7a86e401e46f14fb8982afaa7a8c61847c9 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 12:14:52 +0000
Subject: Tidy up cursor tests and make more comprehensive

---
 rest_framework/pagination.py | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index d5af2ac8..61835239 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -171,6 +171,8 @@ class PageNumberPagination(BasePagination):
 
     template = 'rest_framework/pagination/numbers.html'
 
+    invalid_page_message = _('Invalid page "{page_number}": {message}.')
+
     def _handle_backwards_compat(self, view):
         """
         Prior to version 3.1, pagination was handled in the view, and the
@@ -203,7 +205,7 @@ class PageNumberPagination(BasePagination):
         try:
             self.page = paginator.page(page_number)
         except InvalidPage as exc:
-            msg = _('Invalid page "{page_number}": {message}.').format(
+            msg = self.invalid_page_message.format(
                 page_number=page_number, message=six.text_type(exc)
             )
             raise NotFound(msg)
@@ -386,8 +388,8 @@ Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
 
 
 def decode_cursor(encoded):
-    tokens = urlparse.parse_qs(b64decode(encoded), keep_blank_values=True)
     try:
+        tokens = urlparse.parse_qs(b64decode(encoded), keep_blank_values=True)
         offset = int(tokens['offset'][0])
         reverse = bool(int(tokens['reverse'][0]))
         position = tokens['position'][0]
@@ -411,7 +413,8 @@ class CursorPagination(BasePagination):
     # Support case where ordering is already negative
     # Support tuple orderings
     cursor_query_param = 'cursor'
-    page_size = 5
+    page_size = api_settings.PAGINATE_BY
+    invalid_cursor_message = _('Invalid cursor')
 
     def paginate_queryset(self, queryset, request, view=None):
         self.base_url = request.build_absolute_uri()
@@ -424,8 +427,9 @@ class CursorPagination(BasePagination):
             (offset, reverse, current_position) = (0, False, '')
         else:
             self.cursor = decode_cursor(encoded)
+            if self.cursor is None:
+                raise NotFound(self.invalid_cursor_message)
             (offset, reverse, current_position) = self.cursor
-            # TODO: Invalid cursors should 404
 
         # Cursor pagination always enforces an ordering.
         if reverse:
@@ -458,7 +462,7 @@ class CursorPagination(BasePagination):
         # If we have a reverse queryset, then the query ordering was in reverse
         # so we need to reverse the items again before returning them to the user.
         if reverse:
-            self.page = reversed(self.page)
+            self.page = list(reversed(self.page))
 
         if reverse:
             # Determine next and previous positions for reverse cursors.
@@ -483,8 +487,14 @@ class CursorPagination(BasePagination):
         if not self.has_next:
             return None
 
-        compare = self.next_position
+        if self.cursor and self.cursor.reverse and self.cursor.offset != 0:
+            # If we're reversing direction and we have an offset cursor
+            # then we cannot use the first position we find as a marker.
+            compare = self._get_position_from_instance(self.page[-1], self.ordering)
+        else:
+            compare = self.next_position
         offset = 0
+
         for item in reversed(self.page):
             position = self._get_position_from_instance(item, self.ordering)
             if position != compare:
@@ -526,8 +536,14 @@ class CursorPagination(BasePagination):
         if not self.has_previous:
             return None
 
-        compare = self.previous_position
+        if self.cursor and not self.cursor.reverse and self.cursor.offset != 0:
+            # If we're reversing direction and we have an offset cursor
+            # then we cannot use the first position we find as a marker.
+            compare = self._get_position_from_instance(self.page[0], self.ordering)
+        else:
+            compare = self.previous_position
         offset = 0
+
         for item in self.page:
             position = self._get_position_from_instance(item, self.ordering)
             if position != compare:
-- 
cgit v1.2.3


From ca372ef6ef1cf95eb9282a484782e1a3721cb72b Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 13:50:51 +0000
Subject: Fix for python 3

---
 rest_framework/pagination.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 61835239..0c5abccb 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -389,7 +389,7 @@ Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
 
 def decode_cursor(encoded):
     try:
-        tokens = urlparse.parse_qs(b64decode(encoded), keep_blank_values=True)
+        tokens = urlparse.parse_qs(b64decode(encoded).decode('ascii'), keep_blank_values=True)
         offset = int(tokens['offset'][0])
         reverse = bool(int(tokens['reverse'][0]))
         position = tokens['position'][0]
@@ -405,7 +405,7 @@ def encode_cursor(cursor):
         'reverse': '1' if cursor.reverse else '0',
         'position': cursor.position
     }
-    return b64encode(urlparse.urlencode(tokens, doseq=True))
+    return b64encode(urlparse.urlencode(tokens, doseq=True).encode('ascii'))
 
 
 class CursorPagination(BasePagination):
-- 
cgit v1.2.3


From 38a2ed6f62adcdcb2eba94f6133d4dd976a53af1 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 14:04:25 +0000
Subject: Python 3 fixes for cursor pagination

---
 rest_framework/pagination.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 0c5abccb..cf1f1afa 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -389,7 +389,8 @@ Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
 
 def decode_cursor(encoded):
     try:
-        tokens = urlparse.parse_qs(b64decode(encoded).decode('ascii'), keep_blank_values=True)
+        querystring = b64decode(encoded.encode('ascii')).decode('ascii')
+        tokens = urlparse.parse_qs(querystring, keep_blank_values=True)
         offset = int(tokens['offset'][0])
         reverse = bool(int(tokens['reverse'][0]))
         position = tokens['position'][0]
@@ -405,7 +406,8 @@ def encode_cursor(cursor):
         'reverse': '1' if cursor.reverse else '0',
         'position': cursor.position
     }
-    return b64encode(urlparse.urlencode(tokens, doseq=True).encode('ascii'))
+    querystring = urlparse.urlencode(tokens, doseq=True)
+    return b64encode(querystring.encode('ascii')).decode('ascii')
 
 
 class CursorPagination(BasePagination):
-- 
cgit v1.2.3


From 83a82b44a56a303d43a16dd675fae116e51b9d85 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 15:07:01 +0000
Subject: Support for tuple ordering in cursor pagination

---
 rest_framework/pagination.py | 113 +++++++++++++++++++++++++------------------
 1 file changed, 67 insertions(+), 46 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index cf1f1afa..58223f49 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -20,12 +20,12 @@ from rest_framework.utils.urls import (
 )
 
 
-def _strict_positive_int(integer_string, cutoff=None):
+def _positive_int(integer_string, strict=False, cutoff=None):
     """
     Cast a string to a strictly positive integer.
     """
     ret = int(integer_string)
-    if ret <= 0:
+    if ret < 0 or (ret == 0 and strict):
         raise ValueError()
     if cutoff:
         ret = min(ret, cutoff)
@@ -126,6 +126,47 @@ def _get_page_links(page_numbers, current, url_func):
     return page_links
 
 
+def _decode_cursor(encoded):
+    """
+    Given a string representing an encoded cursor, return a `Cursor` instance.
+    """
+    try:
+        querystring = b64decode(encoded.encode('ascii')).decode('ascii')
+        tokens = urlparse.parse_qs(querystring, keep_blank_values=True)
+        offset = _positive_int(tokens['offset'][0])
+        reverse = bool(int(tokens['reverse'][0]))
+        position = tokens.get('position', [None])[0]
+    except (TypeError, ValueError):
+        return None
+
+    return Cursor(offset=offset, reverse=reverse, position=position)
+
+
+def _encode_cursor(cursor):
+    """
+    Given a Cursor instance, return an encoded string representation.
+    """
+    tokens = {
+        'offset': str(cursor.offset),
+        'reverse': '1' if cursor.reverse else '0',
+    }
+    if cursor.position is not None:
+        tokens['position'] = cursor.position
+
+    querystring = urlparse.urlencode(tokens, doseq=True)
+    return b64encode(querystring.encode('ascii')).decode('ascii')
+
+
+def _reverse_ordering(ordering_tuple):
+    """
+    Given an order_by tuple such as `('-created', 'uuid')` reverse the
+    ordering and return a new tuple, eg. `('created', '-uuid')`.
+    """
+    invert = lambda x: x[1:] if (x.startswith('-')) else '-' + x
+    return tuple([invert(item) for item in ordering_tuple])
+
+
+Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
 PageLink = namedtuple('PageLink', ['url', 'number', 'is_active', 'is_break'])
 
 PAGE_BREAK = PageLink(url=None, number=None, is_active=False, is_break=True)
@@ -228,8 +269,9 @@ class PageNumberPagination(BasePagination):
     def get_page_size(self, request):
         if self.paginate_by_param:
             try:
-                return _strict_positive_int(
+                return _positive_int(
                     request.query_params[self.paginate_by_param],
+                    strict=True,
                     cutoff=self.max_paginate_by
                 )
             except (KeyError, ValueError):
@@ -312,7 +354,7 @@ class LimitOffsetPagination(BasePagination):
     def get_limit(self, request):
         if self.limit_query_param:
             try:
-                return _strict_positive_int(
+                return _positive_int(
                     request.query_params[self.limit_query_param],
                     cutoff=self.max_limit
                 )
@@ -323,7 +365,7 @@ class LimitOffsetPagination(BasePagination):
 
     def get_offset(self, request):
         try:
-            return _strict_positive_int(
+            return _positive_int(
                 request.query_params[self.offset_query_param],
             )
         except (KeyError, ValueError):
@@ -384,36 +426,10 @@ class LimitOffsetPagination(BasePagination):
         return template.render(context)
 
 
-Cursor = namedtuple('Cursor', ['offset', 'reverse', 'position'])
-
-
-def decode_cursor(encoded):
-    try:
-        querystring = b64decode(encoded.encode('ascii')).decode('ascii')
-        tokens = urlparse.parse_qs(querystring, keep_blank_values=True)
-        offset = int(tokens['offset'][0])
-        reverse = bool(int(tokens['reverse'][0]))
-        position = tokens['position'][0]
-    except (TypeError, ValueError):
-        return None
-
-    return Cursor(offset=offset, reverse=reverse, position=position)
-
-
-def encode_cursor(cursor):
-    tokens = {
-        'offset': str(cursor.offset),
-        'reverse': '1' if cursor.reverse else '0',
-        'position': cursor.position
-    }
-    querystring = urlparse.urlencode(tokens, doseq=True)
-    return b64encode(querystring.encode('ascii')).decode('ascii')
-
-
 class CursorPagination(BasePagination):
-    # TODO: handle queries with '' as a legitimate position
     # Support case where ordering is already negative
     # Support tuple orderings
+    # Determine how/if True, False and None positions work
     cursor_query_param = 'cursor'
     page_size = api_settings.PAGINATE_BY
     invalid_cursor_message = _('Invalid cursor')
@@ -426,25 +442,26 @@ class CursorPagination(BasePagination):
         encoded = request.query_params.get(self.cursor_query_param)
         if encoded is None:
             self.cursor = None
-            (offset, reverse, current_position) = (0, False, '')
+            (offset, reverse, current_position) = (0, False, None)
         else:
-            self.cursor = decode_cursor(encoded)
+            self.cursor = _decode_cursor(encoded)
             if self.cursor is None:
                 raise NotFound(self.invalid_cursor_message)
             (offset, reverse, current_position) = self.cursor
 
         # Cursor pagination always enforces an ordering.
         if reverse:
-            queryset = queryset.order_by('-' + self.ordering)
+            queryset = queryset.order_by(_reverse_ordering(self.ordering))
         else:
             queryset = queryset.order_by(self.ordering)
 
         # If we have a cursor with a fixed position then filter by that.
-        if current_position != '':
+        if current_position is not None:
+            primary_ordering_attr = self.ordering[0].lstrip('-')
             if self.cursor.reverse:
-                kwargs = {self.ordering + '__lt': current_position}
+                kwargs = {primary_ordering_attr + '__lt': current_position}
             else:
-                kwargs = {self.ordering + '__gt': current_position}
+                kwargs = {primary_ordering_attr + '__gt': current_position}
             queryset = queryset.filter(**kwargs)
 
         # If we have an offset cursor then offset the entire page by that amount.
@@ -468,7 +485,7 @@ class CursorPagination(BasePagination):
 
         if reverse:
             # Determine next and previous positions for reverse cursors.
-            self.has_next = current_position != '' or offset > 0
+            self.has_next = (current_position is not None) or (offset > 0)
             self.has_previous = has_following_postion
             if self.has_next:
                 self.next_position = current_position
@@ -477,7 +494,7 @@ class CursorPagination(BasePagination):
         else:
             # Determine next and previous positions for forward cursors.
             self.has_next = has_following_postion
-            self.has_previous = current_position != '' or offset > 0
+            self.has_previous = (current_position is not None) or (offset > 0)
             if self.has_next:
                 self.next_position = following_position
             if self.has_previous:
@@ -518,7 +535,7 @@ class CursorPagination(BasePagination):
                 # Our cursor will have an offset equal to the page size,
                 # but no position to filter against yet.
                 offset = self.page_size
-                position = ''
+                position = None
             elif self.cursor.reverse:
                 # The change in direction will introduce a paging artifact,
                 # where we end up skipping forward a few extra items.
@@ -531,7 +548,7 @@ class CursorPagination(BasePagination):
                 position = self.previous_position
 
         cursor = Cursor(offset=offset, reverse=False, position=position)
-        encoded = encode_cursor(cursor)
+        encoded = _encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
     def get_previous_link(self):
@@ -567,7 +584,7 @@ class CursorPagination(BasePagination):
                 # Our cursor will have an offset equal to the page size,
                 # but no position to filter against yet.
                 offset = self.page_size
-                position = ''
+                position = None
             elif self.cursor.reverse:
                 # Use the position from the existing cursor and increment
                 # it's offset by the page size.
@@ -580,11 +597,15 @@ class CursorPagination(BasePagination):
                 position = self.next_position
 
         cursor = Cursor(offset=offset, reverse=True, position=position)
-        encoded = encode_cursor(cursor)
+        encoded = _encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
     def get_ordering(self):
-        return 'created'
+        """
+        Return a tuple of strings, that may be used in an `order_by` method.
+        """
+        return ('created',)
 
     def _get_position_from_instance(self, instance, ordering):
-        return str(getattr(instance, ordering))
+        attr = getattr(instance, ordering[0])
+        return six.text_type(attr)
-- 
cgit v1.2.3


From 408261ee02b176732b7f840f7042e7c24f3ecd27 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 15:15:52 +0000
Subject: Support ordering attribute either on view or on pagination class for
 CursorPagination

---
 rest_framework/pagination.py | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 58223f49..7b28b47f 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -427,16 +427,16 @@ class LimitOffsetPagination(BasePagination):
 
 
 class CursorPagination(BasePagination):
-    # Support case where ordering is already negative
-    # Support tuple orderings
+    # Support usage with OrderingFilter
     # Determine how/if True, False and None positions work
     cursor_query_param = 'cursor'
     page_size = api_settings.PAGINATE_BY
     invalid_cursor_message = _('Invalid cursor')
+    ordering = None
 
     def paginate_queryset(self, queryset, request, view=None):
         self.base_url = request.build_absolute_uri()
-        self.ordering = self.get_ordering()
+        self.ordering = self.get_ordering(view)
 
         # Determine if we have a cursor, and if so then decode it.
         encoded = request.query_params.get(self.cursor_query_param)
@@ -600,11 +600,25 @@ class CursorPagination(BasePagination):
         encoded = _encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
-    def get_ordering(self):
+    def get_ordering(self, view):
         """
         Return a tuple of strings, that may be used in an `order_by` method.
         """
-        return ('created',)
+        ordering = getattr(view, 'ordering', getattr(self, 'ordering', None))
+
+        assert ordering is not None, (
+            'Using cursor pagination, but no ordering attribute was declared '
+            'on the view or on the pagination class.'
+        )
+        assert isinstance(ordering, (six.string_types, list, tuple)), (
+            'Invalid ordering. Expected string or tuple, but got {type}'.format(
+                type=type(ordering).__name__
+            )
+        )
+
+        if isinstance(ordering, six.string_types):
+            return (ordering,)
+        return ordering
 
     def _get_position_from_instance(self, instance, ordering):
         attr = getattr(instance, ordering[0])
-- 
cgit v1.2.3


From 0822c9e55820f8e4737329e38abc2e21718af9e5 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 16:12:05 +0000
Subject: Cursor pagination now works with OrderingFilter

---
 rest_framework/pagination.py | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 7b28b47f..1b4174bc 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -427,8 +427,9 @@ class LimitOffsetPagination(BasePagination):
 
 
 class CursorPagination(BasePagination):
-    # Support usage with OrderingFilter
-    # Determine how/if True, False and None positions work
+    # Determine how/if True, False and None positions work - do the string
+    # encodings work with Django queryset filters?
+    # Consider a max offset cap.
     cursor_query_param = 'cursor'
     page_size = api_settings.PAGINATE_BY
     invalid_cursor_message = _('Invalid cursor')
@@ -436,7 +437,7 @@ class CursorPagination(BasePagination):
 
     def paginate_queryset(self, queryset, request, view=None):
         self.base_url = request.build_absolute_uri()
-        self.ordering = self.get_ordering(view)
+        self.ordering = self.get_ordering(request, queryset, view)
 
         # Determine if we have a cursor, and if so then decode it.
         encoded = request.query_params.get(self.cursor_query_param)
@@ -600,16 +601,36 @@ class CursorPagination(BasePagination):
         encoded = _encode_cursor(cursor)
         return replace_query_param(self.base_url, self.cursor_query_param, encoded)
 
-    def get_ordering(self, view):
+    def get_ordering(self, request, queryset, view):
         """
         Return a tuple of strings, that may be used in an `order_by` method.
         """
-        ordering = getattr(view, 'ordering', getattr(self, 'ordering', None))
+        ordering_filters = [
+            filter_cls for filter_cls in getattr(view, 'filter_backends', [])
+            if hasattr(filter_cls, 'get_ordering')
+        ]
+
+        if ordering_filters:
+            # If a filter exists on the view that implements `get_ordering`
+            # then we defer to that filter to determine the ordering.
+            filter_cls = ordering_filters[0]
+            filter_instance = filter_cls()
+            ordering = filter_instance.get_ordering(request, queryset, view)
+            assert ordering is not None, (
+                'Using cursor pagination, but filter class {filter_cls} '
+                'returned a `None` ordering.'.format(
+                    filter_cls=filter_cls.__name__
+                )
+            )
+        else:
+            # The default case is to check for an `ordering` attribute,
+            # first on the view instance, and then on this pagination instance.
+            ordering = getattr(view, 'ordering', getattr(self, 'ordering', None))
+            assert ordering is not None, (
+                'Using cursor pagination, but no ordering attribute was declared '
+                'on the view or on the pagination class.'
+            )
 
-        assert ordering is not None, (
-            'Using cursor pagination, but no ordering attribute was declared '
-            'on the view or on the pagination class.'
-        )
         assert isinstance(ordering, (six.string_types, list, tuple)), (
             'Invalid ordering. Expected string or tuple, but got {type}'.format(
                 type=type(ordering).__name__
@@ -618,7 +639,7 @@ class CursorPagination(BasePagination):
 
         if isinstance(ordering, six.string_types):
             return (ordering,)
-        return ordering
+        return tuple(ordering)
 
     def _get_position_from_instance(self, instance, ordering):
         attr = getattr(instance, ordering[0])
-- 
cgit v1.2.3


From 43d983fae82ab23ca94f52deb29e938eb2a40e88 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Thu, 22 Jan 2015 17:25:12 +0000
Subject: Add paging controls

---
 rest_framework/pagination.py | 66 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 15 deletions(-)

(limited to 'rest_framework/pagination.py')

diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py
index 1b4174bc..b3658aca 100644
--- a/rest_framework/pagination.py
+++ b/rest_framework/pagination.py
@@ -133,9 +133,14 @@ def _decode_cursor(encoded):
     try:
         querystring = b64decode(encoded.encode('ascii')).decode('ascii')
         tokens = urlparse.parse_qs(querystring, keep_blank_values=True)
-        offset = _positive_int(tokens['offset'][0])
-        reverse = bool(int(tokens['reverse'][0]))
-        position = tokens.get('position', [None])[0]
+
+        offset = tokens.get('o', ['0'])[0]
+        offset = _positive_int(offset)
+
+        reverse = tokens.get('r', ['0'])[0]
+        reverse = bool(int(reverse))
+
+        position = tokens.get('p', [None])[0]
     except (TypeError, ValueError):
         return None
 
@@ -146,12 +151,13 @@ def _encode_cursor(cursor):
     """
     Given a Cursor instance, return an encoded string representation.
     """
-    tokens = {
-        'offset': str(cursor.offset),
-        'reverse': '1' if cursor.reverse else '0',
-    }
+    tokens = {}
+    if cursor.offset != 0:
+        tokens['o'] = str(cursor.offset)
+    if cursor.reverse:
+        tokens['r'] = '1'
     if cursor.position is not None:
-        tokens['position'] = cursor.position
+        tokens['p'] = cursor.position
 
     querystring = urlparse.urlencode(tokens, doseq=True)
     return b64encode(querystring.encode('ascii')).decode('ascii')
@@ -430,10 +436,12 @@ class CursorPagination(BasePagination):
     # Determine how/if True, False and None positions work - do the string
     # encodings work with Django queryset filters?
     # Consider a max offset cap.
+    # Tidy up the `get_ordering` API (eg remove queryset from it)
     cursor_query_param = 'cursor'
     page_size = api_settings.PAGINATE_BY
     invalid_cursor_message = _('Invalid cursor')
     ordering = None
+    template = 'rest_framework/pagination/previous_and_next.html'
 
     def paginate_queryset(self, queryset, request, view=None):
         self.base_url = request.build_absolute_uri()
@@ -452,17 +460,22 @@ class CursorPagination(BasePagination):
 
         # Cursor pagination always enforces an ordering.
         if reverse:
-            queryset = queryset.order_by(_reverse_ordering(self.ordering))
+            queryset = queryset.order_by(*_reverse_ordering(self.ordering))
         else:
-            queryset = queryset.order_by(self.ordering)
+            queryset = queryset.order_by(*self.ordering)
 
         # If we have a cursor with a fixed position then filter by that.
         if current_position is not None:
-            primary_ordering_attr = self.ordering[0].lstrip('-')
-            if self.cursor.reverse:
-                kwargs = {primary_ordering_attr + '__lt': current_position}
+            order = self.ordering[0]
+            is_reversed = order.startswith('-')
+            order_attr = order.lstrip('-')
+
+            # Test for: (cursor reversed) XOR (queryset reversed)
+            if self.cursor.reverse != is_reversed:
+                kwargs = {order_attr + '__lt': current_position}
             else:
-                kwargs = {primary_ordering_attr + '__gt': current_position}
+                kwargs = {order_attr + '__gt': current_position}
+
             queryset = queryset.filter(**kwargs)
 
         # If we have an offset cursor then offset the entire page by that amount.
@@ -501,6 +514,11 @@ class CursorPagination(BasePagination):
             if self.has_previous:
                 self.previous_position = current_position
 
+        # Display page controls in the browsable API if there is more
+        # than one page.
+        if self.has_previous or self.has_next:
+            self.display_page_controls = True
+
         return self.page
 
     def get_next_link(self):
@@ -642,5 +660,23 @@ class CursorPagination(BasePagination):
         return tuple(ordering)
 
     def _get_position_from_instance(self, instance, ordering):
-        attr = getattr(instance, ordering[0])
+        attr = getattr(instance, ordering[0].lstrip('-'))
         return six.text_type(attr)
+
+    def get_paginated_response(self, data):
+        return Response(OrderedDict([
+            ('next', self.get_next_link()),
+            ('previous', self.get_previous_link()),
+            ('results', data)
+        ]))
+
+    def get_html_context(self):
+        return {
+            'previous_url': self.get_previous_link(),
+            'next_url': self.get_next_link()
+        }
+
+    def to_html(self):
+        template = loader.get_template(self.template)
+        context = Context(self.get_html_context())
+        return template.render(context)
-- 
cgit v1.2.3