fnp_django_pagination/paginator.py

   1 # Copyright (c) 2008, Eric Florenzano
   2 # Copyright (c) 2010, 2011 Linaro Limited
   3 # All rights reserved.
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions are
   7 # met:
   8 #
   9 #     * Redistributions of source code must retain the above copyright
  10 #       notice, this list of conditions and the following disclaimer.
  11 #     * Redistributions in binary form must reproduce the above
  12 #       copyright notice, this list of conditions and the following
  13 #       disclaimer in the documentation and/or other materials provided
  14 #       with the distribution.
  15 #     * Neither the name of the author nor the names of other
  16 #       contributors may be used to endorse or promote products derived
  17 #       from this software without specific prior written permission.
  18 #
  19 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31
  32 from django.core.paginator import Paginator, Page, PageNotAnInteger, EmptyPage
  33
  34
  35 class InfinitePaginator(Paginator):
  36     """
  37     Paginator designed for cases when it's not important to know how many total
  38     pages.  This is useful for any object_list that has no count() method or
  39     can be used to improve performance for MySQL by removing counts.
  40
  41     The orphans parameter has been removed for simplicity and there's a link
  42     template string for creating the links to the next and previous pages.
  43     """
  44
  45     def __init__(self, object_list, per_page, allow_empty_first_page=True,
  46         link_template='/page/%d/'):
  47         orphans = 0  # no orphans
  48         super(InfinitePaginator, self).__init__(object_list, per_page, orphans,
  49             allow_empty_first_page)
  50         # no count or num pages
  51         try:
  52             del self._num_pages, self._count
  53         except AttributeError:
  54             # These are just cached properties anyway.
  55             pass
  56         # bonus links
  57         self.link_template = link_template
  58
  59     def validate_number(self, number):
  60         """
  61         Validates the given 1-based page number.
  62         """
  63         try:
  64             number = int(number)
  65         except ValueError:
  66             raise PageNotAnInteger('That page number is not an integer')
  67         if number < 1:
  68             raise EmptyPage('That page number is less than 1')
  69         return number
  70
  71     def page(self, number):
  72         """
  73         Returns a Page object for the given 1-based page number.
  74         """
  75         number = self.validate_number(number)
  76         bottom = (number - 1) * self.per_page
  77         top = bottom + self.per_page
  78         page_items = self.object_list[bottom:top]
  79         # check moved from validate_number
  80         if not page_items:
  81             if number == 1 and self.allow_empty_first_page:
  82                 pass
  83             else:
  84                 raise EmptyPage('That page contains no results')
  85         return InfinitePage(page_items, number, self)
  86
  87     def _get_count(self):
  88         """
  89         Returns the total number of objects, across all pages.
  90         """
  91         raise NotImplementedError
  92     count = property(_get_count)
  93
  94     def _get_num_pages(self):
  95         """
  96         Returns the total number of pages.
  97         """
  98         raise NotImplementedError
  99     num_pages = property(_get_num_pages)
 100
 101     def _get_page_range(self):
 102         """
 103         Returns a 1-based range of pages for iterating through within
 104         a template for loop.
 105         """
 106         raise NotImplementedError
 107     page_range = property(_get_page_range)
 108
 109
 110 class InfinitePage(Page):
 111
 112     def __repr__(self):
 113         return '<Page %s>' % self.number
 114
 115     def has_next(self):
 116         """
 117         Checks for one more item than last on this page.
 118         """
 119         try:
 120             self.paginator.object_list[self.number * self.paginator.per_page]
 121         except IndexError:
 122             return False
 123         return True
 124
 125     def end_index(self):
 126         """
 127         Returns the 1-based index of the last object on this page,
 128         relative to total objects found (hits).
 129         """
 130         return ((self.number - 1) * self.paginator.per_page +
 131             len(self.object_list))
 132
 133     #Bonus methods for creating links
 134
 135     def next_link(self):
 136         if self.has_next():
 137             return self.paginator.link_template % (self.number + 1)
 138         return None
 139
 140     def previous_link(self):
 141         if self.has_previous():
 142             return self.paginator.link_template % (self.number - 1)
 143         return None
 144
 145
 146 class FinitePaginator(InfinitePaginator):
 147     """
 148     Paginator for cases when the list of items is already finite.
 149
 150     A good example is a list generated from an API call. This is a subclass
 151     of InfinitePaginator because we have no idea how many items exist in the
 152     full collection.
 153
 154     To accurately determine if the next page exists, a FinitePaginator MUST be
 155     created with an object_list_plus that may contain more items than the
 156     per_page count.  Typically, you'll have an object_list_plus with one extra
 157     item (if there's a next page).  You'll also need to supply the offset from
 158     the full collection in order to get the page start_index.
 159
 160     This is a very silly class but useful if you love the Django pagination
 161     conventions.
 162     """
 163
 164     def __init__(self, object_list_plus, per_page, offset=None,
 165         allow_empty_first_page=True, link_template='/page/%d/'):
 166         super(FinitePaginator, self).__init__(object_list_plus, per_page,
 167             allow_empty_first_page, link_template)
 168         self.offset = offset
 169
 170     def validate_number(self, number):
 171         super(FinitePaginator, self).validate_number(number)
 172         # check for an empty list to see if the page exists
 173         if not self.object_list:
 174             if number == 1 and self.allow_empty_first_page:
 175                 pass
 176             else:
 177                 raise EmptyPage('That page contains no results')
 178         return number
 179
 180     def page(self, number):
 181         """
 182         Returns a Page object for the given 1-based page number.
 183         """
 184         number = self.validate_number(number)
 185         # remove the extra item(s) when creating the page
 186         page_items = self.object_list[:self.per_page]
 187         return FinitePage(page_items, number, self)
 188
 189
 190 class FinitePage(InfinitePage):
 191
 192     def has_next(self):
 193         """
 194         Checks for one more item than last on this page.
 195         """
 196         try:
 197             self.paginator.object_list[self.paginator.per_page]
 198         except IndexError:
 199             return False
 200         return True
 201
 202     def start_index(self):
 203         """
 204         Returns the 1-based index of the first object on this page,
 205         relative to total objects in the paginator.
 206         """
 207         ## TODO should this holler if you haven't defined the offset?
 208         return self.paginator.offset