Ticket #7005: misc-orphans-fixes-8147.diff

django/views/generic/list_detail.py

@@ -4 +4 @@
 from django.core.paginator import Paginator, InvalidPage
 from django.core.exceptions import ObjectDoesNotExist
 
-def object_list(request, queryset, paginate_by=None, page=None,
+def object_list(request, queryset, paginate_by=None, page=None, orphans=None,
         allow_empty=True, template_name=None, template_loader=loader,
         extra_context=None, context_processors=None, template_object_name='object',
         mimetype=None):
@@ -45 +45 @@
     if extra_context is None: extra_context = {}
     queryset = queryset._clone()
     if paginate_by:
-        paginator = Paginator(queryset, paginate_by, allow_empty_first_page=allow_empty)
+        paginator = Paginator(queryset, paginate_by, allow_empty_first_page=allow_empty, orphans=orphans)
         if not page:
             page = request.GET.get('page', 1)
         try:

docs/pagination.txt

@@ -59 +59 @@
     ...
     InvalidPage
 
+    #################
+    # Orphan support
+    #################
+
+    # With orphans=2 and 2 items per page, we get all 4 items on a single page.
+    >>> paginator = Paginator(objects, 2, orphans=2)
+    >>> paginator.num_pages
+    1
+    >>> page = paginator.page(1)
+    >>> page.object_list
+    ['john', 'paul', 'george', 'ringo']
+    
+    # With orphans only set to 1, we get two pages.
+    >>> paginator = Paginator(objects, 2, orphans=1)
+    >>> paginator.num_pages
+    2
+    >>> page = paginator.page(1)
+    >>> page.object_list
+    ['john', 'paul']
+    >>> page = paginator.page(2)
+    >>> page.object_list
+    ['george', 'ringo']
+
+
 Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or
 any other object with a ``count()`` or ``__len__()`` method. When determining
 the number of objects contained in the passed object, ``Paginator`` will first
@@ -66 +90 @@
 has no ``count()`` method. This allows objects such as Django's ``QuerySet`` to
 use a more efficient ``count()`` method when available.
 
+``Paginator`` also accepts an optional argument ``orphans`` which specifies the
+number of objects that can be included over the specified page limit (when
+creating a ``Paginator`` instance) in order to preclude a final page which
+contains only a few objects. For example, if paginating a list of 101 objects
+by 20 with no orphans, the ``Paginator`` will generate 5 pages with 20 objects
+each, and a sixth page with a single object.  Under the same scenario but with
+the ``orphans`` argument set to 1 (or greater), the ``Paginator`` will generate
+4 pages with 20 objects each, and a fifth page with 21 objects.
+
 ``Paginator`` objects
 =====================
 

docs/generic_views.txt

@@ -704 +704 @@
     * ``page``: The current (1-based) page number, as an integer, or the string
       ``'last'``. See `Notes on pagination`_ below.
 
+    * ``orphans``: The number of extra objects to allow the Paginator to include
+      on the last page. This optionally extends the ``paginate_by`` limit in
+      order to keep the last page from having a very small number of objects.
+      This only has effect when ``paginate_by`` is used.
+      See `Notes on pagination`_ below.
+
     * ``template_name``: The full name of a template to use in rendering the
       page. This lets you override the default template name (see below).