Added a new and improved Paginator class, which allows you to pass a Page object to the template instead of 5 or 6 separate variables. ObjectPaginator still exists for backwards compatibility but issues a DeprecationWarning

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7306 bcc190cf-cafb-0310-a4f2-bffc1f526a37

tests/modeltests/pagination/models.py

@@ -4,6 +4,11 @@
 Django provides a framework for paginating a list of objects in a few lines
 of code. This is often useful for dividing search results or long lists of
 objects into easily readable pages.
+
+In Django 0.96 and earlier, a single ObjectPaginator class implemented this
+functionality. In the Django development version, the behavior is split across
+two classes -- Paginator and Page -- that are more easier to use. The legacy
+ObjectPaginator class is deprecated.
 """
 
 from django.db import models
@@ -16,70 +21,206 @@ class Article(models.Model):
         return self.headline
 
 __test__ = {'API_TESTS':"""
-# prepare a list of objects for pagination
+# Prepare a list of objects for pagination.
 >>> from datetime import datetime
 >>> for x in range(1, 10):
 ...     a = Article(headline='Article %s' % x, pub_date=datetime(2005, 7, 29))
 ...     a.save()
 
-# create a basic paginator, 5 articles per page
+####################################
+# New/current API (Paginator/Page) #
+####################################
+
+>>> from django.core.paginator import Paginator, InvalidPage
+>>> paginator = Paginator(Article.objects.all(), 5)
+>>> paginator.count
+9
+>>> paginator.num_pages
+2
+>>> paginator.page_range
+[1, 2]
+
+# Get the first page.
+>>> p = paginator.page(1)
+>>> p
+<Page 1 of 2>
+>>> p.object_list
+[<Article: Article 1>, <Article: Article 2>, <Article: Article 3>, <Article: Article 4>, <Article: Article 5>]
+>>> p.has_next()
+True
+>>> p.has_previous()
+False
+>>> p.has_other_pages()
+True
+>>> p.next_page_number()
+2
+>>> p.previous_page_number()
+0
+>>> p.start_index()
+1
+>>> p.end_index()
+5
+
+# Get the second page.
+>>> p = paginator.page(2)
+>>> p
+<Page 2 of 2>
+>>> p.object_list
+[<Article: Article 6>, <Article: Article 7>, <Article: Article 8>, <Article: Article 9>]
+>>> p.has_next()
+False
+>>> p.has_previous()
+True
+>>> p.has_other_pages()
+True
+>>> p.next_page_number()
+3
+>>> p.previous_page_number()
+1
+>>> p.start_index()
+6
+>>> p.end_index()
+9
+
+# Invalid pages raise InvalidPage.
+>>> paginator.page(0)
+Traceback (most recent call last):
+...
+InvalidPage: ...
+>>> paginator.page(3)
+Traceback (most recent call last):
+...
+InvalidPage: ...
+
+# Empty paginators with allow_empty_first_page=True.
+>>> paginator = Paginator(Article.objects.filter(id=0), 5, allow_empty_first_page=True)
+>>> paginator.count
+0
+>>> paginator.num_pages
+1
+>>> paginator.page_range
+[1]
+
+# Empty paginators with allow_empty_first_page=False.
+>>> paginator = Paginator(Article.objects.filter(id=0), 5, allow_empty_first_page=False)
+>>> paginator.count
+0
+>>> paginator.num_pages
+0
+>>> paginator.page_range
+[]
+
+# Paginators work with regular lists/tuples, too -- not just with QuerySets.
+>>> paginator = Paginator([1, 2, 3, 4, 5, 6, 7, 8, 9], 5)
+>>> paginator.count
+9
+>>> paginator.num_pages
+2
+>>> paginator.page_range
+[1, 2]
+
+# Get the first page.
+>>> p = paginator.page(1)
+>>> p
+<Page 1 of 2>
+>>> p.object_list
+[1, 2, 3, 4, 5]
+>>> p.has_next()
+True
+>>> p.has_previous()
+False
+>>> p.has_other_pages()
+True
+>>> p.next_page_number()
+2
+>>> p.previous_page_number()
+0
+>>> p.start_index()
+1
+>>> p.end_index()
+5
+
+################################
+# Legacy API (ObjectPaginator) #
+################################
+
 >>> from django.core.paginator import ObjectPaginator, InvalidPage
 >>> paginator = ObjectPaginator(Article.objects.all(), 5)
-
-# the paginator knows how many hits and pages it contains
 >>> paginator.hits
 9
-
 >>> paginator.pages
 2
+>>> paginator.page_range
+[1, 2]
 
-# get the first page (zero-based)
+# Get the first page.
 >>> paginator.get_page(0)
 [<Article: Article 1>, <Article: Article 2>, <Article: Article 3>, <Article: Article 4>, <Article: Article 5>]
-
-# get the second page
->>> paginator.get_page(1)
-[<Article: Article 6>, <Article: Article 7>, <Article: Article 8>, <Article: Article 9>]
-
-# does the first page have a next or previous page?
 >>> paginator.has_next_page(0)
 True
-
 >>> paginator.has_previous_page(0)
 False
-
-# check the second page
->>> paginator.has_next_page(1)
-False
-
->>> paginator.has_previous_page(1)
-True
-
 >>> paginator.first_on_page(0)
 1
->>> paginator.first_on_page(1)
-6
 >>> paginator.last_on_page(0)
 5
+
+# Get the second page.
+>>> paginator.get_page(1)
+[<Article: Article 6>, <Article: Article 7>, <Article: Article 8>, <Article: Article 9>]
+>>> paginator.has_next_page(1)
+False
+>>> paginator.has_previous_page(1)
+True
+>>> paginator.first_on_page(1)
+6
 >>> paginator.last_on_page(1)
 9
 
+# Invalid pages raise InvalidPage.
+>>> paginator.get_page(-1)
+Traceback (most recent call last):
+...
+InvalidPage: ...
+>>> paginator.get_page(2)
+Traceback (most recent call last):
+...
+InvalidPage: ...
+
+# Empty paginators with allow_empty_first_page=True.
+>>> paginator = ObjectPaginator(Article.objects.filter(id=0), 5)
+>>> paginator.count
+0
+>>> paginator.num_pages
+1
+>>> paginator.page_range
+[1]
+
+##################
+# Orphan support #
+##################
+
 # Add a few more records to test out the orphans feature.
 >>> for x in range(10, 13):
 ...     Article(headline="Article %s" % x, pub_date=datetime(2006, 10, 6)).save()
 
-# With orphans set to 3 and 10 items per page, we should get all 12 items on a single page:
+# With orphans set to 3 and 10 items per page, we should get all 12 items on a single page.
+>>> paginator = Paginator(Article.objects.all(), 10, orphans=3)
+>>> paginator.num_pages
+1
+
+# With orphans only set to 1, we should get two pages.
+>>> paginator = ObjectPaginator(Article.objects.all(), 10, orphans=1)
+>>> paginator.num_pages
+2
+
+# LEGACY: With orphans set to 3 and 10 items per page, we should get all 12 items on a single page.
 >>> paginator = ObjectPaginator(Article.objects.all(), 10, orphans=3)
 >>> paginator.pages
 1
 
-# With orphans only set to 1, we should get two pages:
+# LEGACY: With orphans only set to 1, we should get two pages.
 >>> paginator = ObjectPaginator(Article.objects.all(), 10, orphans=1)
 >>> paginator.pages
 2
-
-# The paginator can provide a list of all available pages.
->>> paginator = ObjectPaginator(Article.objects.all(), 10)
->>> paginator.page_range
-[1, 2]
 """}