Opened 22 months ago

Closed 22 months ago

Last modified 22 months ago

#27814 closed Bug (fixed)

Unclear explanation of orphans in Paginator

Reported by: Pablo Oubiña Owned by: nobody
Component: Documentation Version: 1.10
Severity: Normal Keywords: paginator, orphans,
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Hi there!

From Django documentation:
"Paginator objects
...
orphans
The minimum number of items allowed on the last page, defaults to zero..."

Current implementation:

>>> from django.core.paginator import Paginator
>>> objects = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
>>> p = Paginator(objects, 3, orphans=2)
>>> page2 = p.page(2)
>>> page2.object_list
output: ['d', 'e', 'f', 'g', 'h']
>>> page2.has_next()
output: False

As I understand it:

>>> from django.core.paginator import Paginator
>>> objects = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
>>> p = Paginator(objects, 3, orphans=2)
>>> page2 = p.page(2)
>>> page2.object_list
output: ['d', 'e', 'f']
>>> page2.has_next()
output: True
>>> page3 = p.page(3)
>>> page3.object_list
output: ['g', 'h']

In my opinion, the orphans definition is confusing. What do you think? Am I missing something?

Thanks.

Change History (6)

comment:1 Changed 22 months ago by Tim Graham

Triage Stage: UnreviewedAccepted
Type: UncategorizedBug

I think the correct definition is "One less than the minimum number of items allowed on the last page." -- agreed?

comment:2 in reply to:  1 Changed 22 months ago by Pablo Oubiña

Replying to Tim Graham:

I think the correct definition is "One less than the minimum number of items allowed on the last page." -- agreed?

Hi Tim!
Much better, but it's still confusing. In the future maybe we should consider the possibility of doing something like that:

>>> from django.core.paginator import Paginator
>>> objects = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
>>> p = Paginator(objects, 3, min_orphans=2)
>>> page2 = p.page(2)
>>> page2.object_list
output: ['d', 'e', 'f']
>>> page2.has_next()
output: True
>>> page3 = p.page(3)
>>> page3.object_list
output: ['g', 'h']

Optional arguments
min_orphans: The minimum number of items allowed on the last page.
It would be much more obvious. On the other hand, I know it implies breaking backwards compatibility. Just and idea.
Thanks.

comment:3 Changed 22 months ago by Tim Graham

Has patch: set

Yes, it's probably better to remove that sentence entirely. I don't think changing the behavior is worth breaking backwards compatibility.

PR

comment:4 Changed 22 months ago by GitHub <noreply@…>

Resolution: fixed
Status: newclosed

In 27793431:

Fixed #27814 -- Removed an inaccurate sentence about Paginator.orphans.

comment:5 Changed 22 months ago by Tim Graham <timograham@…>

In 035c3a71:

[1.11.x] Fixed #27814 -- Removed an inaccurate sentence about Paginator.orphans.

Backport of 27793431cf21a82809c0c39a7c0188a2d83bf475 from master

comment:6 Changed 22 months ago by Tim Graham <timograham@…>

In dd952d79:

[1.10.x] Fixed #27814 -- Removed an inaccurate sentence about Paginator.orphans.

Backport of 27793431cf21a82809c0c39a7c0188a2d83bf475 from master

Note: See TracTickets for help on using tickets.
Back to Top