f67aa23218c19794ce76a4e9443d684359ae974b
[django-pagination.git] / pagination / paginator.py
1 from django.core.paginator import Paginator, Page, PageNotAnInteger, EmptyPage
2
3 class InfinitePaginator(Paginator):
4     """
5     Paginator designed for cases when it's not important to know how many total
6     pages.  This is useful for any object_list that has no count() method or can
7     be used to improve performance for MySQL by removing counts.
8
9     The orphans parameter has been removed for simplicity and there's a link
10     template string for creating the links to the next and previous pages.
11     """
12
13     def __init__(self, object_list, per_page, allow_empty_first_page=True,
14         link_template='/page/%d/'):
15         orphans = 0 # no orphans
16         super(InfinitePaginator, self).__init__(object_list, per_page, orphans,
17             allow_empty_first_page)
18         # no count or num pages
19         del self._num_pages, self._count
20         # bonus links
21         self.link_template = link_template
22
23     def validate_number(self, number):
24         """
25         Validates the given 1-based page number.
26         """
27         try:
28             number = int(number)
29         except ValueError:
30             raise PageNotAnInteger('That page number is not an integer')
31         if number < 1:
32             raise EmptyPage('That page number is less than 1')
33         return number
34
35     def page(self, number):
36         """
37         Returns a Page object for the given 1-based page number.
38         """
39         number = self.validate_number(number)
40         bottom = (number - 1) * self.per_page
41         top = bottom + self.per_page
42         page_items = self.object_list[bottom:top]
43         # check moved from validate_number
44         if not page_items:
45             if number == 1 and self.allow_empty_first_page:
46                 pass
47             else:
48                 raise EmptyPage('That page contains no results')
49         return InfinitePage(page_items, number, self)
50
51     def _get_count(self):
52         """
53         Returns the total number of objects, across all pages.
54         """
55         raise NotImplementedError
56     count = property(_get_count)
57
58     def _get_num_pages(self):
59         """
60         Returns the total number of pages.
61         """
62         raise NotImplementedError
63     num_pages = property(_get_num_pages)
64
65     def _get_page_range(self):
66         """
67         Returns a 1-based range of pages for iterating through within
68         a template for loop.
69         """
70         raise NotImplementedError
71     page_range = property(_get_page_range)
72
73
74 class InfinitePage(Page):
75
76     def __repr__(self):
77         return '<Page %s>' % self.number
78
79     def has_next(self):
80         """
81         Checks for one more item than last on this page.
82         """
83         try:
84             next_item = self.paginator.object_list[
85                 self.number * self.paginator.per_page]
86         except IndexError:
87             return False
88         return True
89
90     def end_index(self):
91         """
92         Returns the 1-based index of the last object on this page,
93         relative to total objects found (hits).
94         """
95         return ((self.number - 1) * self.paginator.per_page +
96             len(self.object_list))
97
98     #Bonus methods for creating links
99
100     def next_link(self):
101         if self.has_next():
102             return self.paginator.link_template % (self.number + 1)
103         return None
104
105     def previous_link(self):
106         if self.has_previous():
107             return self.paginator.link_template % (self.number - 1)
108         return None
109
110 class FinitePaginator(InfinitePaginator):
111     """
112     Paginator for cases when the list of items is already finite.
113
114     A good example is a list generated from an API call. This is a subclass
115     of InfinitePaginator because we have no idea how many items exist in the
116     full collection.
117
118     To accurately determine if the next page exists, a FinitePaginator MUST be
119     created with an object_list_plus that may contain more items than the
120     per_page count.  Typically, you'll have an object_list_plus with one extra
121     item (if there's a next page).  You'll also need to supply the offset from
122     the full collection in order to get the page start_index.
123
124     This is a very silly class but useful if you love the Django pagination
125     conventions.
126     """
127
128     def __init__(self, object_list_plus, per_page, offset=None,
129         allow_empty_first_page=True, link_template='/page/%d/'):
130         super(FinitePaginator, self).__init__(object_list_plus, per_page,
131             allow_empty_first_page, link_template)
132         self.offset = offset
133
134     def validate_number(self, number):
135         super(FinitePaginator, self).validate_number(number)
136         # check for an empty list to see if the page exists
137         if not self.object_list:
138             if number == 1 and self.allow_empty_first_page:
139                 pass
140             else:
141                 raise EmptyPage('That page contains no results')
142         return number
143
144     def page(self, number):
145         """
146         Returns a Page object for the given 1-based page number.
147         """
148         number = self.validate_number(number)
149         # remove the extra item(s) when creating the page
150         page_items = self.object_list[:self.per_page]
151         return FinitePage(page_items, number, self)
152
153 class FinitePage(InfinitePage):
154
155     def has_next(self):
156         """
157         Checks for one more item than last on this page.
158         """
159         try:
160             next_item = self.paginator.object_list[self.paginator.per_page]
161         except IndexError:
162             return False
163         return True
164
165     def start_index(self):
166         """
167         Returns the 1-based index of the first object on this page,
168         relative to total objects in the paginator.
169         """
170         ## TODO should this holler if you haven't defined the offset?
171         return self.paginator.offset