Unclear explanation of orphans in Paginator

[Pablo Oubiña]

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.

[Tim Graham]

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

[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.

[Tim Graham]

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

​PR

[GitHub <noreply@…>]

In 27793431:

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

[Tim Graham <timograham@…>]

In 035c3a71:

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

Backport of 27793431cf21a82809c0c39a7c0188a2d83bf475 from master

[Tim Graham <timograham@…>]

In dd952d79:

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

Backport of 27793431cf21a82809c0c39a7c0188a2d83bf475 from master