Ticket #10941: querystring-methods.diff

django/core/paginator.py

@@ -10 +10 @@
     pass
 
 class Paginator(object):
-    def __init__(self, object_list, per_page, orphans=0, allow_empty_first_page=True):
+    def __init__(self, object_list, per_page, orphans=0, allow_empty_first_page=True, request=None):
         self.object_list = object_list
         self.per_page = per_page
         self.orphans = orphans
         self.allow_empty_first_page = allow_empty_first_page
+        self.request = request
         self._num_pages = self._count = None
 
     def validate_number(self, number):
@@ -99 +100 @@
     def previous_page_number(self):
         return self.number - 1
 
+    def _other_page_querystring(self, page_number):
+        """
+        Returns a query string for the given page, preserving any
+        GET parameters present.
+        """
+        try:
+            querydict = self.paginator.request.GET.copy()
+            querydict['page'] = page_number
+            querystring = querydict.urlencode()
+        except AttributeError:
+            querystring = 'page=%s' % page_number
+        return querystring
+
+    def next_page_querystring(self):
+        return self._other_page_querystring(self.next_page_number())
+
+    def previous_page_querystring(self):
+        return self._other_page_querystring(self.previous_page_number())
+
     def start_index(self):
         """
         Returns the 1-based index of the first object on this page,

docs/topics/pagination.txt

@@ -137 +137 @@
 
 The :class:`Paginator` class has this constructor:
 
-.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)
+.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, request=None)
 
 Required arguments
 ------------------
@@ -167 +167 @@
     Whether or not the first page is allowed to be empty.  If ``False`` and
     ``object_list`` is  empty, then an ``EmptyPage`` error will be raised.
 
+``request``
+    An :class:`HttpRequest` object, used for creating pagination query strings.
+
 Methods
 -------
 
@@ -252 +255 @@
     Returns the previous page number. Note that this is "dumb" and will return
     the previous page number regardless of whether a previous page exists.
 
+.. method:: Page.next_page_querystring()
+
+    Returns the query string for the next page. This is useful when pagination
+    is handled with a query string (as opposed to a URL pattern). It is common
+    for there to be other parameters in the query string that need to remain
+    intact on the the next page e.g, paginated search results.
+
+    Note that this is "dumb" and will return the next query string regardless
+    of whether a subsequent page exists.
+
+    .. admonition:: Where's my query string?
+
+        If the :class:`Page`'s associated :class:`Paginator` was not passed an
+        :class:`HttpRequest` object when it was instantiated, this method will
+        only return the ``page`` parameter. In order to return the whole
+        query string the :class:`Paginator` must have been constructed with a
+        valid ``request`` argument.
+
+.. method:: Page.previous_page_querystring()
+
+    Returns the query string for the previous page. See :meth:`~Page.next_page_querystring`.
+
+    Note that this is "dumb" and will return the previous query string
+    regardless of whether a previous page exists.
+
 .. method:: Page.start_index()
 
     Returns the 1-based index of the first object on the page, relative to all