diff options
| -rw-r--r-- | AUTHORS | 1 | ||||
| -rw-r--r-- | django/core/paginator.py | 324 | ||||
| -rw-r--r-- | docs/ref/paginator.txt | 46 | ||||
| -rw-r--r-- | docs/releases/6.0.txt | 8 | ||||
| -rw-r--r-- | tests/pagination/custom.py | 19 | ||||
| -rw-r--r-- | tests/pagination/tests.py | 500 |
6 files changed, 783 insertions, 115 deletions
@@ -500,6 +500,7 @@ answer newbie questions, and generally made Django that much better: Jens Page Jensen Cochran <jensen.cochran@gmail.com> Jeong-Min Lee <falsetru@gmail.com> + Jeong-Wook Lee <devwookkl@gmail.com> Jérémie Blaser <blaserje@gmail.com> Jeremy Bowman <https://github.com/jmbowman> Jeremy Carbaugh <jcarbaugh@gmail.com> diff --git a/django/core/paginator.py b/django/core/paginator.py index 7b3189cc8b..422da30aa1 100644 --- a/django/core/paginator.py +++ b/django/core/paginator.py @@ -1,8 +1,11 @@ import collections.abc import inspect import warnings +from asyncio import iscoroutinefunction from math import ceil +from asgiref.sync import sync_to_async + from django.utils.functional import cached_property from django.utils.inspect import method_has_no_args from django.utils.translation import gettext_lazy as _ @@ -24,7 +27,7 @@ class EmptyPage(InvalidPage): pass -class Paginator: +class BasePaginator: # Translators: String used to replace omitted page numbers in elided page # range generated by paginators, e.g. [1, 2, '…', 5, 6, 7, '…', 9, 10]. ELLIPSIS = _("…") @@ -53,11 +56,74 @@ class Paginator: else self.default_error_messages | error_messages ) - def __iter__(self): - for page_number in self.page_range: - yield self.page(page_number) + def _check_object_list_is_ordered(self): + """ + Warn if self.object_list is unordered (typically a QuerySet). + """ + ordered = getattr(self.object_list, "ordered", None) + if ordered is not None and not ordered: + obj_list_repr = ( + "{} {}".format( + self.object_list.model, self.object_list.__class__.__name__ + ) + if hasattr(self.object_list, "model") + else "{!r}".format(self.object_list) + ) + warnings.warn( + "Pagination may yield inconsistent results with an unordered " + "object_list: {}.".format(obj_list_repr), + UnorderedObjectListWarning, + stacklevel=3, + ) - def validate_number(self, number): + def _get_elided_page_range( + self, number, num_pages, page_range, on_each_side=3, on_ends=2 + ): + """ + Return a 1-based range of pages with some values elided. + + If the page range is larger than a given size, the whole range is not + provided and a compact form is returned instead, e.g. for a paginator + with 50 pages, if page 43 were the current page, the output, with the + default arguments, would be: + + 1, 2, …, 40, 41, 42, 43, 44, 45, 46, …, 49, 50. + """ + if num_pages <= (on_each_side + on_ends) * 2: + for page in page_range: + yield page + return + + if number > (1 + on_each_side + on_ends) + 1: + for page in range(1, on_ends + 1): + yield page + yield self.ELLIPSIS + for page in range(number - on_each_side, number + 1): + yield page + else: + for page in range(1, number + 1): + yield page + + if number < (num_pages - on_each_side - on_ends) - 1: + for page in range(number + 1, number + on_each_side + 1): + yield page + yield self.ELLIPSIS + for page in range(num_pages - on_ends + 1, num_pages + 1): + yield page + else: + for page in range(number + 1, num_pages + 1): + yield page + + def _get_page(self, *args, **kwargs): + """ + Return an instance of a single page. + + This hook can be used by subclasses to use an alternative to the + standard :cls:`Page` object. + """ + return Page(*args, **kwargs) + + def _validate_number(self, number, num_pages): """Validate the given 1-based page number.""" try: if isinstance(number, float) and not number.is_integer(): @@ -67,10 +133,19 @@ class Paginator: raise PageNotAnInteger(self.error_messages["invalid_page"]) if number < 1: raise EmptyPage(self.error_messages["min_page"]) - if number > self.num_pages: + if number > num_pages: raise EmptyPage(self.error_messages["no_results"]) return number + +class Paginator(BasePaginator): + def __iter__(self): + for page_number in self.page_range: + yield self.page(page_number) + + def validate_number(self, number): + return self._validate_number(number, self.num_pages) + def get_page(self, number): """ Return a valid page, even if the page argument isn't a number or isn't @@ -93,15 +168,6 @@ class Paginator: top = self.count return self._get_page(self.object_list[bottom:top], number, self) - def _get_page(self, *args, **kwargs): - """ - Return an instance of a single page. - - This hook can be used by subclasses to use an alternative to the - standard :cls:`Page` object. - """ - return Page(*args, **kwargs) - @cached_property def count(self): """Return the total number of objects, across all pages.""" @@ -126,56 +192,105 @@ class Paginator: """ return range(1, self.num_pages + 1) - def _check_object_list_is_ordered(self): - """ - Warn if self.object_list is unordered (typically a QuerySet). - """ - ordered = getattr(self.object_list, "ordered", None) - if ordered is not None and not ordered: - obj_list_repr = ( - "{} {}".format( - self.object_list.model, self.object_list.__class__.__name__ - ) - if hasattr(self.object_list, "model") - else "{!r}".format(self.object_list) - ) - warnings.warn( - "Pagination may yield inconsistent results with an unordered " - "object_list: {}.".format(obj_list_repr), - UnorderedObjectListWarning, - stacklevel=3, - ) - def get_elided_page_range(self, number=1, *, on_each_side=3, on_ends=2): - """ - Return a 1-based range of pages with some values elided. + number = self.validate_number(number) + yield from self._get_elided_page_range( + number, self.num_pages, self.page_range, on_each_side, on_ends + ) - If the page range is larger than a given size, the whole range is not - provided and a compact form is returned instead, e.g. for a paginator - with 50 pages, if page 43 were the current page, the output, with the - default arguments, would be: - 1, 2, …, 40, 41, 42, 43, 44, 45, 46, …, 49, 50. - """ - number = self.validate_number(number) +class AsyncPaginator(BasePaginator): + def __init__( + self, + object_list, + per_page, + orphans=0, + allow_empty_first_page=True, + error_messages=None, + ): + super().__init__( + object_list, per_page, orphans, allow_empty_first_page, error_messages + ) + self._cache_acount = None + self._cache_anum_pages = None - if self.num_pages <= (on_each_side + on_ends) * 2: - yield from self.page_range - return + async def __aiter__(self): + page_range = await self.apage_range() + for page_number in page_range: + yield await self.apage(page_number) - if number > (1 + on_each_side + on_ends) + 1: - yield from range(1, on_ends + 1) - yield self.ELLIPSIS - yield from range(number - on_each_side, number + 1) - else: - yield from range(1, number + 1) + async def avalidate_number(self, number): + num_pages = await self.anum_pages() + return self._validate_number(number, num_pages) - if number < (self.num_pages - on_each_side - on_ends) - 1: - yield from range(number + 1, number + on_each_side + 1) - yield self.ELLIPSIS - yield from range(self.num_pages - on_ends + 1, self.num_pages + 1) + async def aget_page(self, number): + """See Paginator.get_page().""" + try: + number = await self.avalidate_number(number) + except PageNotAnInteger: + number = 1 + except EmptyPage: + number = await self.anum_pages() + return await self.apage(number) + + async def apage(self, number): + """See Paginator.page().""" + number = await self.avalidate_number(number) + bottom = (number - 1) * self.per_page + top = bottom + self.per_page + count = await self.acount() + if top + self.orphans >= count: + top = count + + return self._get_page(self.object_list[bottom:top], number, self) + + def _get_page(self, *args, **kwargs): + return AsyncPage(*args, **kwargs) + + async def acount(self): + """See Paginator.count().""" + if self._cache_acount is not None: + return self._cache_acount + c = getattr(self.object_list, "acount", None) + if ( + iscoroutinefunction(c) + and not inspect.isbuiltin(c) + and method_has_no_args(c) + ): + count = await c() else: - yield from range(number + 1, self.num_pages + 1) + count = len(self.object_list) + + self._cache_acount = count + return count + + async def anum_pages(self): + """See Paginator.num_pages().""" + if self._cache_anum_pages is not None: + return self._cache_anum_pages + count = await self.acount() + if count == 0 and not self.allow_empty_first_page: + self._cache_anum_pages = 0 + return self._cache_anum_pages + hits = max(1, count - self.orphans) + num_pages = ceil(hits / self.per_page) + + self._cache_anum_pages = num_pages + return num_pages + + async def apage_range(self): + """See Paginator.page_range()""" + num_pages = await self.anum_pages() + return range(1, num_pages + 1) + + async def aget_elided_page_range(self, number=1, *, on_each_side=3, on_ends=2): + number = await self.avalidate_number(number) + num_pages = await self.anum_pages() + page_range = await self.apage_range() + for page in self._get_elided_page_range( + number, num_pages, page_range, on_each_side, on_ends + ): + yield page class Page(collections.abc.Sequence): @@ -236,3 +351,96 @@ class Page(collections.abc.Sequence): if self.number == self.paginator.num_pages: return self.paginator.count return self.number * self.paginator.per_page + + +class AsyncPage: + def __init__(self, object_list, number, paginator): + self.object_list = object_list + self.number = number + self.paginator = paginator + + def __repr__(self): + return "<Async Page %s>" % self.number + + async def __aiter__(self): + if hasattr(self.object_list, "__aiter__"): + async for obj in self.object_list: + yield obj + else: + for obj in self.object_list: + yield obj + + def __len__(self): + if not isinstance(self.object_list, list): + raise TypeError( + "AsyncPage.aget_object_list() must be awaited before calling len()." + ) + return len(self.object_list) + + def __reversed__(self): + if not isinstance(self.object_list, list): + raise TypeError( + "AsyncPage.aget_object_list() " + "must be awaited before calling reversed()." + ) + + return reversed(self.object_list) + + def __getitem__(self, index): + if not isinstance(index, (int, slice)): + raise TypeError( + "AsyncPage indices must be integers or slices, not %s." + % type(index).__name__ + ) + + if not isinstance(self.object_list, list): + raise TypeError( + "AsyncPage.aget_object_list() must be awaited before using indexing." + ) + return self.object_list[index] + + async def aget_object_list(self): + """ + Returns self.object_list as a list. + + This method must be awaited before AsyncPage can be + treated as a sequence of self.object_list. + """ + if not isinstance(self.object_list, list): + if hasattr(self.object_list, "__aiter__"): + self.object_list = [obj async for obj in self.object_list] + else: + self.object_list = await sync_to_async(list)(self.object_list) + return self.object_list + + async def ahas_next(self): + num_pages = await self.paginator.anum_pages() + return self.number < num_pages + + async def ahas_previous(self): + return self.number > 1 + + async def ahas_other_pages(self): + has_previous = await self.ahas_previous() + has_next = await self.ahas_next() + return has_previous or has_next + + async def anext_page_number(self): + return await self.paginator.avalidate_number(self.number + 1) + + async def aprevious_page_number(self): + return await self.paginator.avalidate_number(self.number - 1) + + async def astart_index(self): + """See Page.start_index().""" + count = await self.paginator.acount() + if count == 0: + return 0 + return (self.paginator.per_page * (self.number - 1)) + 1 + + async def aend_index(self): + """See Page.end_index().""" + num_pages = await self.paginator.anum_pages() + if self.number == num_pages: + return await self.paginator.acount() + return self.number * self.paginator.per_page diff --git a/docs/ref/paginator.txt b/docs/ref/paginator.txt index 03084e5d40..d5b5b0f30e 100644 --- a/docs/ref/paginator.txt +++ b/docs/ref/paginator.txt @@ -161,6 +161,30 @@ Attributes A 1-based range iterator of page numbers, e.g. yielding ``[1, 2, 3, 4]``. +``AsyncPaginator`` class +======================== + +.. versionadded:: 6.0 + +.. class:: AsyncPaginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None) + + Asynchronous version of :class:`Paginator`. + + ``AsyncPaginator`` has the same attributes and signatures as + :class:`Paginator`, with the following exceptions: + + * The attribute :attr:`.Paginator.count` is supported as an asynchronous + method ``AsyncPaginator.acount()``. + * The attribute :attr:`.Paginator.num_pages` is supported as an + asynchronous method ``AsyncPaginator.anum_pages()``. + * The attribute :attr:`.Paginator.page_range` is supported as an + asynchronous method ``AsyncPaginator.apage_range()``. + + ``AsyncPaginator`` has asynchronous versions of the same methods as + :class:`Paginator`, using an ``a`` prefix - for example, use + ``await async_paginator.aget_page(number)`` rather than + ``paginator.get_page(number)``. + ``Page`` class ============== @@ -226,6 +250,28 @@ Attributes The associated :class:`Paginator` object. +``AsyncPage`` class +=================== + +.. versionadded:: 6.0 + +.. class:: AsyncPage(object_list, number, paginator) + + Asynchronous version of :class:`Page`. + + ``AsyncPage`` has the same attributes and signatures as :class:`Page`, as + well as asynchronous versions of all the same methods, using an ``a`` + prefix - for example, use ``await async_page.ahas_next()`` rather than + ``page.has_next()``. + + ``AsyncPage`` has the following additional method: + + .. method:: AsyncPage.aget_object_list() + + Returns ``AsyncPage.object_list`` as a list. This method must be + awaited before ``AsyncPage`` can be treated as a sequence of + ``AsyncPage.object_list``. + Exceptions ========== diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt index 9e74856664..c604638deb 100644 --- a/docs/releases/6.0.txt +++ b/docs/releases/6.0.txt @@ -199,6 +199,14 @@ Models :ref:`a forced update <ref-models-force-insert>` results in no affected rows, instead of a generic :exc:`django.db.DatabaseError`. +Pagination +~~~~~~~~~~ + +* The new :class:`~django.core.paginator.AsyncPaginator` and + :class:`~django.core.paginator.AsyncPage` provide async implementations of + :class:`~django.core.paginator.Paginator` and + :class:`~django.core.paginator.Page` respectively. + Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tests/pagination/custom.py b/tests/pagination/custom.py index ea04083576..e1ffa905f1 100644 --- a/tests/pagination/custom.py +++ b/tests/pagination/custom.py @@ -1,4 +1,4 @@ -from django.core.paginator import Page, Paginator +from django.core.paginator import AsyncPage, AsyncPaginator, Page, Paginator class ValidAdjacentNumsPage(Page): @@ -16,3 +16,20 @@ class ValidAdjacentNumsPage(Page): class ValidAdjacentNumsPaginator(Paginator): def _get_page(self, *args, **kwargs): return ValidAdjacentNumsPage(*args, **kwargs) + + +class AsyncValidAdjacentNumsPage(AsyncPage): + async def anext_page_number(self): + if not await self.ahas_next(): + return None + return await super().anext_page_number() + + async def aprevious_page_number(self): + if not await self.ahas_previous(): + return None + return await super().aprevious_page_number() + + +class AsyncValidAdjacentNumsPaginator(AsyncPaginator): + def _get_page(self, *args, **kwargs): + return AsyncValidAdjacentNumsPage(*args, **kwargs) diff --git a/tests/pagination/tests.py b/tests/pagination/tests.py index cf7ec61d3b..ab2329f26f 100644 --- a/tests/pagination/tests.py +++ b/tests/pagination/tests.py @@ -1,9 +1,12 @@ import collections.abc +import inspect import unittest.mock import warnings from datetime import datetime from django.core.paginator import ( + AsyncPaginator, + BasePaginator, EmptyPage, InvalidPage, PageNotAnInteger, @@ -12,7 +15,7 @@ from django.core.paginator import ( ) from django.test import SimpleTestCase, TestCase -from .custom import ValidAdjacentNumsPaginator +from .custom import AsyncValidAdjacentNumsPaginator, ValidAdjacentNumsPaginator from .models import Article @@ -32,6 +35,13 @@ class PaginationTests(SimpleTestCase): self.check_attribute("num_pages", paginator, num_pages, params) self.check_attribute("page_range", paginator, page_range, params, coerce=list) + async def check_paginator_async(self, params, output): + """See check_paginator.""" + count, num_pages, page_range = output + paginator = AsyncPaginator(*params) + await self.check_attribute_async("acount", paginator, count, params) + await self.check_attribute_async("anum_pages", paginator, num_pages, params) + def check_attribute(self, name, paginator, expected, params, coerce=None): """ Helper method that checks a single attribute and gives a nice error @@ -47,14 +57,21 @@ class PaginationTests(SimpleTestCase): % (name, expected, got, params), ) - def test_paginator(self): - """ - Tests the paginator attributes using varying inputs. - """ + async def check_attribute_async(self, name, paginator, expected, params): + """See check_attribute.""" + got = getattr(paginator, name) + self.assertEqual( + expected, + await got(), + "For '%s', expected %s but got %s. Paginator parameters were: %s" + % (name, expected, got, params), + ) + + def get_test_cases_for_test_paginator(self): nine = [1, 2, 3, 4, 5, 6, 7, 8, 9] ten = nine + [10] eleven = ten + [11] - tests = ( + return ( # Each item is 2-tuple: # First tuple is Paginator parameters - object_list, per_page, # orphans, and allow_empty_first_page. @@ -111,9 +128,17 @@ class PaginationTests(SimpleTestCase): ((ten, 4, "1", False), (10, 3, [1, 2, 3])), ((ten, 4, "1", False), (10, 3, [1, 2, 3])), ) + + def test_paginator(self): + tests = self.get_test_cases_for_test_paginator() for params, output in tests: self.check_paginator(params, output) + async def test_paginator_async(self): + tests = self.get_test_cases_for_test_paginator() + for params, output in tests: + await self.check_paginator_async(params, output) + def test_invalid_page_number(self): """ Invalid page numbers result in the correct exception being raised. @@ -128,6 +153,12 @@ class PaginationTests(SimpleTestCase): with self.assertRaises(PageNotAnInteger): paginator.validate_number(1.2) + async def test_invalid_apage_number_async(self): + """See test_invalid_page_number.""" + paginator = AsyncPaginator([1, 2, 3], 2) + with self.assertRaises(InvalidPage): + await paginator.apage(3) + def test_error_messages(self): error_messages = { "invalid_page": "Wrong page number", @@ -186,6 +217,27 @@ class PaginationTests(SimpleTestCase): self.assertEqual(5, paginator.num_pages) self.assertEqual([1, 2, 3, 4, 5], list(paginator.page_range)) + async def test_paginate_misc_classes_async(self): + class CountContainer: + async def acount(self): + return 42 + + # AsyncPaginator can be passed other objects with an acount() method. + paginator = AsyncPaginator(CountContainer(), 10) + self.assertEqual(42, await paginator.acount()) + self.assertEqual(5, await paginator.anum_pages()) + self.assertEqual([1, 2, 3, 4, 5], list(await paginator.apage_range())) + + # AsyncPaginator can be passed other objects that implement __len__. + class LenContainer: + def __len__(self): + return 42 + + paginator = AsyncPaginator(LenContainer(), 10) + self.assertEqual(42, await paginator.acount()) + self.assertEqual(5, await paginator.anum_pages()) + self.assertEqual([1, 2, 3, 4, 5], list(await paginator.apage_range())) + def test_count_does_not_silence_attribute_error(self): class AttributeErrorContainer: def count(self): @@ -194,6 +246,14 @@ class PaginationTests(SimpleTestCase): with self.assertRaisesMessage(AttributeError, "abc"): Paginator(AttributeErrorContainer(), 10).count + async def test_acount_does_not_silence_attribute_error_async(self): + class AttributeErrorContainer: + async def acount(self): + raise AttributeError("abc") + + with self.assertRaisesMessage(AttributeError, "abc"): + await AsyncPaginator(AttributeErrorContainer(), 10).acount() + def test_count_does_not_silence_type_error(self): class TypeErrorContainer: def count(self): @@ -202,6 +262,14 @@ class PaginationTests(SimpleTestCase): with self.assertRaisesMessage(TypeError, "abc"): Paginator(TypeErrorContainer(), 10).count + async def test_acount_does_not_silence_type_error_async(self): + class TypeErrorContainer: + async def acount(self): + raise TypeError("abc") + + with self.assertRaisesMessage(TypeError, "abc"): + await AsyncPaginator(TypeErrorContainer(), 10).acount() + def check_indexes(self, params, page_num, indexes): """ Helper method that instantiates a Paginator object from the passed @@ -227,12 +295,30 @@ class PaginationTests(SimpleTestCase): msg % ("end index", page_num, end, page.end_index(), params), ) - def test_page_indexes(self): - """ - Paginator pages have the correct start and end indexes. - """ + async def check_indexes_async(self, params, page_num, indexes): + """See check_indexes.""" + paginator = AsyncPaginator(*params) + if page_num == "first": + page_num = 1 + elif page_num == "last": + page_num = await paginator.anum_pages() + page = await paginator.apage(page_num) + start, end = indexes + msg = "For %s of page %s, expected %s but got %s. Paginator parameters were: %s" + self.assertEqual( + start, + await page.astart_index(), + msg % ("start index", page_num, start, await page.astart_index(), params), + ) + self.assertEqual( + end, + await page.aend_index(), + msg % ("end index", page_num, end, await page.aend_index(), params), + ) + + def get_test_cases_for_test_page_indexes(self): ten = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - tests = ( + return ( # Each item is 3-tuple: # First tuple is Paginator parameters - object_list, per_page, # orphans, and allow_empty_first_page. @@ -265,6 +351,12 @@ class PaginationTests(SimpleTestCase): (([], 4, 1, True), (0, 0), (0, 0)), (([], 4, 2, True), (0, 0), (0, 0)), ) + + def test_page_indexes(self): + """ + Paginator pages have the correct start and end indexes. + """ + tests = self.get_test_cases_for_test_page_indexes() for params, first, last in tests: self.check_indexes(params, "first", first) self.check_indexes(params, "last", last) @@ -277,6 +369,21 @@ class PaginationTests(SimpleTestCase): with self.assertRaises(EmptyPage): self.check_indexes(([], 4, 2, False), 1, None) + async def test_page_indexes_async(self): + """See test_page_indexes""" + tests = self.get_test_cases_for_test_page_indexes() + for params, first, last in tests: + await self.check_indexes_async(params, "first", first) + await self.check_indexes_async(params, "last", last) + + # When no items and no empty first page, we should get EmptyPage error. + with self.assertRaises(EmptyPage): + await self.check_indexes_async(([], 4, 0, False), 1, None) + with self.assertRaises(EmptyPage): + await self.check_indexes_async(([], 4, 1, False), 1, None) + with self.assertRaises(EmptyPage): + await self.check_indexes_async(([], 4, 2, False), 1, None) + def test_page_sequence(self): """ A paginator page acts like a standard sequence. @@ -289,6 +396,16 @@ class PaginationTests(SimpleTestCase): self.assertEqual("".join(page2), "fghijk") self.assertEqual("".join(reversed(page2)), "kjihgf") + async def test_page_sequence_async(self): + eleven = "abcdefghijk" + page2 = await AsyncPaginator(eleven, per_page=5, orphans=1).apage(2) + await page2.aget_object_list() + self.assertEqual(len(page2), 6) + self.assertIn("k", page2) + self.assertNotIn("a", page2) + self.assertEqual("".join(page2), "fghijk") + self.assertEqual("".join(reversed(page2)), "kjihgf") + def test_get_page_hook(self): """ A Paginator subclass can use the ``_get_page`` hook to @@ -303,6 +420,20 @@ class PaginationTests(SimpleTestCase): self.assertEqual(page2.previous_page_number(), 1) self.assertIsNone(page2.next_page_number()) + async def test_get_page_hook_async(self): + """ + An AsyncPaginator subclass can use the ``_get_page`` hook to + return an alternative to the standard AsyncPage class. + """ + eleven = "abcdefghijk" + paginator = AsyncValidAdjacentNumsPaginator(eleven, per_page=6) + page1 = await paginator.apage(1) + page2 = await paginator.apage(2) + self.assertIsNone(await page1.aprevious_page_number()) + self.assertEqual(await page1.anext_page_number(), 2) + self.assertEqual(await page2.aprevious_page_number(), 1) + self.assertIsNone(await page2.anext_page_number()) + def test_page_range_iterator(self): """ Paginator.page_range should be an iterator. @@ -323,6 +454,20 @@ class PaginationTests(SimpleTestCase): # Non-integer page returns the first page. self.assertEqual(paginator.get_page(None).number, 1) + async def test_aget_page_async(self): + """ + AsyncPaginator.aget_page() returns a valid page even with invalid page + arguments. + """ + paginator = AsyncPaginator([1, 2, 3], 2) + page = await paginator.aget_page(1) + self.assertEqual(page.number, 1) + self.assertEqual(page.object_list, [1, 2]) + # An empty page returns the last page. + self.assertEqual((await paginator.aget_page(3)).number, 2) + # Non-integer page returns the first page. + self.assertEqual((await paginator.aget_page(None)).number, 1) + def test_get_page_empty_object_list(self): """Paginator.get_page() with an empty object_list.""" paginator = Paginator([], 2) @@ -332,6 +477,15 @@ class PaginationTests(SimpleTestCase): # Non-integer page returns the first page. self.assertEqual(paginator.get_page(None).number, 1) + async def test_aget_page_empty_object_list_async(self): + """AsyncPaginator.aget_page() with an empty object_list.""" + paginator = AsyncPaginator([], 2) + # An empty page returns the last page. + self.assertEqual((await paginator.aget_page(1)).number, 1) + self.assertEqual((await paginator.aget_page(2)).number, 1) + # Non-integer page returns the first page. + self.assertEqual((await paginator.aget_page(None)).number, 1) + def test_get_page_empty_object_list_and_allow_empty_first_page_false(self): """ Paginator.get_page() raises EmptyPage if allow_empty_first_page=False @@ -341,6 +495,17 @@ class PaginationTests(SimpleTestCase): with self.assertRaises(EmptyPage): paginator.get_page(1) + async def test_aget_page_empty_obj_list_and_allow_empty_first_page_false_async( + self, + ): + """ + AsyncPaginator.aget_page() raises EmptyPage if allow_empty_first_page=False + and object_list is empty. + """ + paginator = AsyncPaginator([], 2, allow_empty_first_page=False) + with self.assertRaises(EmptyPage): + await paginator.aget_page(1) + def test_paginator_iteration(self): paginator = Paginator([1, 2, 3], 2) page_iterator = iter(paginator) @@ -353,6 +518,66 @@ class PaginationTests(SimpleTestCase): ["<Page 1 of 2>", "<Page 2 of 2>"], ) + async def test_paginator_iteration_async(self): + paginator = AsyncPaginator([1, 2, 3], 2) + page_iterator = aiter(paginator) + for page, expected in enumerate(([1, 2], [3]), start=1): + with self.subTest(page=page): + async_page = await anext(page_iterator) + self.assertEqual(expected, [obj async for obj in async_page]) + self.assertEqual( + [str(page) async for page in aiter(paginator)], + ["<Async Page 1>", "<Async Page 2>"], + ) + + def get_test_cases_for_test_get_elided_page_range(self): + ELLIPSIS = Paginator.ELLIPSIS + return [ + # on_each_side=2, on_ends=1 + (1, 2, 1, [1, 2, 3, ELLIPSIS, 50]), + (4, 2, 1, [1, 2, 3, 4, 5, 6, ELLIPSIS, 50]), + (5, 2, 1, [1, 2, 3, 4, 5, 6, 7, ELLIPSIS, 50]), + (6, 2, 1, [1, ELLIPSIS, 4, 5, 6, 7, 8, ELLIPSIS, 50]), + (45, 2, 1, [1, ELLIPSIS, 43, 44, 45, 46, 47, ELLIPSIS, 50]), + (46, 2, 1, [1, ELLIPSIS, 44, 45, 46, 47, 48, 49, 50]), + (47, 2, 1, [1, ELLIPSIS, 45, 46, 47, 48, 49, 50]), + (50, 2, 1, [1, ELLIPSIS, 48, 49, 50]), + # on_each_side=1, on_ends=3 + (1, 1, 3, [1, 2, ELLIPSIS, 48, 49, 50]), + (5, 1, 3, [1, 2, 3, 4, 5, 6, ELLIPSIS, 48, 49, 50]), + (6, 1, 3, [1, 2, 3, 4, 5, 6, 7, ELLIPSIS, 48, 49, 50]), + (7, 1, 3, [1, 2, 3, ELLIPSIS, 6, 7, 8, ELLIPSIS, 48, 49, 50]), + (44, 1, 3, [1, 2, 3, ELLIPSIS, 43, 44, 45, ELLIPSIS, 48, 49, 50]), + (45, 1, 3, [1, 2, 3, ELLIPSIS, 44, 45, 46, 47, 48, 49, 50]), + (46, 1, 3, [1, 2, 3, ELLIPSIS, 45, 46, 47, 48, 49, 50]), + (50, 1, 3, [1, 2, 3, ELLIPSIS, 49, 50]), + # on_each_side=4, on_ends=0 + (1, 4, 0, [1, 2, 3, 4, 5, ELLIPSIS]), + (5, 4, 0, [1, 2, 3, 4, 5, 6, 7, 8, 9, ELLIPSIS]), + (6, 4, 0, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ELLIPSIS]), + (7, 4, 0, [ELLIPSIS, 3, 4, 5, 6, 7, 8, 9, 10, 11, ELLIPSIS]), + (44, 4, 0, [ELLIPSIS, 40, 41, 42, 43, 44, 45, 46, 47, 48, ELLIPSIS]), + (45, 4, 0, [ELLIPSIS, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50]), + (46, 4, 0, [ELLIPSIS, 42, 43, 44, 45, 46, 47, 48, 49, 50]), + (50, 4, 0, [ELLIPSIS, 46, 47, 48, 49, 50]), + # on_each_side=0, on_ends=1 + (1, 0, 1, [1, ELLIPSIS, 50]), + (2, 0, 1, [1, 2, ELLIPSIS, 50]), + (3, 0, 1, [1, 2, 3, ELLIPSIS, 50]), + (4, 0, 1, [1, ELLIPSIS, 4, ELLIPSIS, 50]), + (47, 0, 1, [1, ELLIPSIS, 47, ELLIPSIS, 50]), + (48, 0, 1, [1, ELLIPSIS, 48, 49, 50]), + (49, 0, 1, [1, ELLIPSIS, 49, 50]), + (50, 0, 1, [1, ELLIPSIS, 50]), + # on_each_side=0, on_ends=0 + (1, 0, 0, [1, ELLIPSIS]), + (2, 0, 0, [1, 2, ELLIPSIS]), + (3, 0, 0, [ELLIPSIS, 3, ELLIPSIS]), + (48, 0, 0, [ELLIPSIS, 48, ELLIPSIS]), + (49, 0, 0, [ELLIPSIS, 49, 50]), + (50, 0, 0, [ELLIPSIS, 50]), + ] + def test_get_elided_page_range(self): # Paginator.validate_number() must be called: paginator = Paginator([1, 2, 3], 2) @@ -426,51 +651,7 @@ class PaginationTests(SimpleTestCase): self.assertIn(ELLIPSIS, page_range) # Range should be elided if enough pages when using custom arguments: - tests = [ - # on_each_side=2, on_ends=1 - (1, 2, 1, [1, 2, 3, ELLIPSIS, 50]), - (4, 2, 1, [1, 2, 3, 4, 5, 6, ELLIPSIS, 50]), - (5, 2, 1, [1, 2, 3, 4, 5, 6, 7, ELLIPSIS, 50]), - (6, 2, 1, [1, ELLIPSIS, 4, 5, 6, 7, 8, ELLIPSIS, 50]), - (45, 2, 1, [1, ELLIPSIS, 43, 44, 45, 46, 47, ELLIPSIS, 50]), - (46, 2, 1, [1, ELLIPSIS, 44, 45, 46, 47, 48, 49, 50]), - (47, 2, 1, [1, ELLIPSIS, 45, 46, 47, 48, 49, 50]), - (50, 2, 1, [1, ELLIPSIS, 48, 49, 50]), - # on_each_side=1, on_ends=3 - (1, 1, 3, [1, 2, ELLIPSIS, 48, 49, 50]), - (5, 1, 3, [1, 2, 3, 4, 5, 6, ELLIPSIS, 48, 49, 50]), - (6, 1, 3, [1, 2, 3, 4, 5, 6, 7, ELLIPSIS, 48, 49, 50]), - (7, 1, 3, [1, 2, 3, ELLIPSIS, 6, 7, 8, ELLIPSIS, 48, 49, 50]), - (44, 1, 3, [1, 2, 3, ELLIPSIS, 43, 44, 45, ELLIPSIS, 48, 49, 50]), - (45, 1, 3, [1, 2, 3, ELLIPSIS, 44, 45, 46, 47, 48, 49, 50]), - (46, 1, 3, [1, 2, 3, ELLIPSIS, 45, 46, 47, 48, 49, 50]), - (50, 1, 3, [1, 2, 3, ELLIPSIS, 49, 50]), - # on_each_side=4, on_ends=0 - (1, 4, 0, [1, 2, 3, 4, 5, ELLIPSIS]), - (5, 4, 0, [1, 2, 3, 4, 5, 6, 7, 8, 9, ELLIPSIS]), - (6, 4, 0, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ELLIPSIS]), - (7, 4, 0, [ELLIPSIS, 3, 4, 5, 6, 7, 8, 9, 10, 11, ELLIPSIS]), - (44, 4, 0, [ELLIPSIS, 40, 41, 42, 43, 44, 45, 46, 47, 48, ELLIPSIS]), - (45, 4, 0, [ELLIPSIS, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50]), - (46, 4, 0, [ELLIPSIS, 42, 43, 44, 45, 46, 47, 48, 49, 50]), - (50, 4, 0, [ELLIPSIS, 46, 47, 48, 49, 50]), - # on_each_side=0, on_ends=1 - (1, 0, 1, [1, ELLIPSIS, 50]), - (2, 0, 1, [1, 2, ELLIPSIS, 50]), - (3, 0, 1, [1, 2, 3, ELLIPSIS, 50]), - (4, 0, 1, [1, ELLIPSIS, 4, ELLIPSIS, 50]), - (47, 0, 1, [1, ELLIPSIS, 47, ELLIPSIS, 50]), - (48, 0, 1, [1, ELLIPSIS, 48, 49, 50]), - (49, 0, 1, [1, ELLIPSIS, 49, 50]), - (50, 0, 1, [1, ELLIPSIS, 50]), - # on_each_side=0, on_ends=0 - (1, 0, 0, [1, ELLIPSIS]), - (2, 0, 0, [1, 2, ELLIPSIS]), - (3, 0, 0, [ELLIPSIS, 3, ELLIPSIS]), - (48, 0, 0, [ELLIPSIS, 48, ELLIPSIS]), - (49, 0, 0, [ELLIPSIS, 49, 50]), - (50, 0, 0, [ELLIPSIS, 50]), - ] + tests = self.get_test_cases_for_test_get_elided_page_range() paginator = Paginator(range(5000), 100) for number, on_each_side, on_ends, expected in tests: with self.subTest( @@ -484,6 +665,94 @@ class PaginationTests(SimpleTestCase): self.assertIsInstance(page_range, collections.abc.Generator) self.assertEqual(list(page_range), expected) + async def test_aget_elided_page_range_async(self): + # AsyncPaginator.avalidate_number() must be called: + paginator = AsyncPaginator([1, 2, 3], 2) + with unittest.mock.patch.object(paginator, "avalidate_number") as mock: + mock.assert_not_called() + [p async for p in paginator.aget_elided_page_range(2)] + mock.assert_called_with(2) + + ELLIPSIS = Paginator.ELLIPSIS + + # Range is not elided if not enough pages when using default arguments: + paginator = AsyncPaginator(range(10 * 100), 100) + page_range = paginator.aget_elided_page_range(1) + self.assertIsInstance(page_range, collections.abc.AsyncGenerator) + self.assertNotIn(ELLIPSIS, [p async for p in page_range]) + paginator = AsyncPaginator(range(10 * 100 + 1), 100) + self.assertIsInstance(page_range, collections.abc.AsyncGenerator) + page_range = paginator.aget_elided_page_range(1) + self.assertIn(ELLIPSIS, [p async for p in page_range]) + + # Range should be elided if enough pages when using default arguments: + tests = [ + # on_each_side=3, on_ends=2 + (1, [1, 2, 3, 4, ELLIPSIS, 49, 50]), + (6, [1, 2, 3, 4, 5, 6, 7, 8, 9, ELLIPSIS, 49, 50]), + (7, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ELLIPSIS, 49, 50]), + (8, [1, 2, ELLIPSIS, 5, 6, 7, 8, 9, 10, 11, ELLIPSIS, 49, 50]), + (43, [1, 2, ELLIPSIS, 40, 41, 42, 43, 44, 45, 46, ELLIPSIS, 49, 50]), + (44, [1, 2, ELLIPSIS, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50]), + (45, [1, 2, ELLIPSIS, 42, 43, 44, 45, 46, 47, 48, 49, 50]), + (50, [1, 2, ELLIPSIS, 47, 48, 49, 50]), + ] + paginator = AsyncPaginator(range(5000), 100) + for number, expected in tests: + with self.subTest(number=number): + page_range = paginator.aget_elided_page_range(number) + self.assertIsInstance(page_range, collections.abc.AsyncGenerator) + self.assertEqual([p async for p in page_range], expected) + + # Range is not elided if not enough pages when using custom arguments: + tests = [ + (6, 2, 1, 1), + (8, 1, 3, 1), + (8, 4, 0, 1), + (4, 1, 1, 1), + # When on_each_side and on_ends are both <= 1 but not both == 1 it + # is a special case where the range is not elided until an extra + # page is added. + (2, 0, 1, 2), + (2, 1, 0, 2), + (1, 0, 0, 2), + ] + for pages, on_each_side, on_ends, elided_after in tests: + for offset in range(elided_after + 1): + with self.subTest( + pages=pages, + offset=elided_after, + on_each_side=on_each_side, + on_ends=on_ends, + ): + paginator = AsyncPaginator(range((pages + offset) * 100), 100) + page_range = paginator.aget_elided_page_range( + 1, + on_each_side=on_each_side, + on_ends=on_ends, + ) + self.assertIsInstance(page_range, collections.abc.AsyncGenerator) + page_list = [p async for p in page_range] + if offset < elided_after: + self.assertNotIn(ELLIPSIS, page_list) + else: + self.assertIn(ELLIPSIS, page_list) + + # Range should be elided if enough pages when using custom arguments: + tests = self.get_test_cases_for_test_get_elided_page_range() + paginator = AsyncPaginator(range(5000), 100) + for number, on_each_side, on_ends, expected in tests: + with self.subTest( + number=number, on_each_side=on_each_side, on_ends=on_ends + ): + page_range = paginator.aget_elided_page_range( + number, + on_each_side=on_each_side, + on_ends=on_ends, + ) + self.assertIsInstance(page_range, collections.abc.AsyncGenerator) + self.assertEqual([p async for p in page_range], expected) + class ModelPaginationTests(TestCase): """ @@ -513,6 +782,21 @@ class ModelPaginationTests(TestCase): self.assertEqual(1, p.start_index()) self.assertEqual(5, p.end_index()) + async def test_first_page_async(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(1) + self.assertEqual("<Async Page 1>", str(p)) + object_list = await p.aget_object_list() + self.assertSequenceEqual(object_list, self.articles[:5]) + self.assertTrue(await p.ahas_next()) + self.assertFalse(await p.ahas_previous()) + self.assertTrue(await p.ahas_other_pages()) + self.assertEqual(2, await p.anext_page_number()) + with self.assertRaises(InvalidPage): + await p.aprevious_page_number() + self.assertEqual(1, await p.astart_index()) + self.assertEqual(5, await p.aend_index()) + def test_last_page(self): paginator = Paginator(Article.objects.order_by("id"), 5) p = paginator.page(2) @@ -527,6 +811,21 @@ class ModelPaginationTests(TestCase): self.assertEqual(6, p.start_index()) self.assertEqual(9, p.end_index()) + async def test_last_page_async(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(2) + self.assertEqual("<Async Page 2>", str(p)) + object_list = await p.aget_object_list() + self.assertSequenceEqual(object_list, self.articles[5:]) + self.assertFalse(await p.ahas_next()) + self.assertTrue(await p.ahas_previous()) + self.assertTrue(await p.ahas_other_pages()) + with self.assertRaises(InvalidPage): + await p.anext_page_number() + self.assertEqual(1, await p.aprevious_page_number()) + self.assertEqual(6, await p.astart_index()) + self.assertEqual(9, await p.aend_index()) + def test_page_getitem(self): """ Tests proper behavior of a paginator page __getitem__ (queryset @@ -551,6 +850,24 @@ class ModelPaginationTests(TestCase): # After __getitem__ is called, object_list is a list self.assertIsInstance(p.object_list, list) + async def test_page_getitem_async(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(1) + + msg = "AsyncPage indices must be integers or slices, not str." + with self.assertRaisesMessage(TypeError, msg): + p["has_previous"] + + self.assertIsNone(p.object_list._result_cache) + + self.assertNotIsInstance(p.object_list, list) + + await p.aget_object_list() + + self.assertEqual(p[0], self.articles[0]) + self.assertSequenceEqual(p[slice(2)], self.articles[:2]) + self.assertIsInstance(p.object_list, list) + def test_paginating_unordered_queryset_raises_warning(self): msg = ( "Pagination may yield inconsistent results with an unordered " @@ -562,11 +879,27 @@ class ModelPaginationTests(TestCase): # is appropriate). self.assertEqual(cm.filename, __file__) + async def test_paginating_unordered_queryset_raises_warning_async(self): + msg = ( + "Pagination may yield inconsistent results with an unordered " + "object_list: <class 'pagination.models.Article'> QuerySet." + ) + with self.assertWarnsMessage(UnorderedObjectListWarning, msg) as cm: + AsyncPaginator(Article.objects.all(), 5) + # The warning points at the BasePaginator caller. + # The reason is that the UnorderedObjectListWarning occurs in BasePaginator. + self.assertEqual(cm.filename, inspect.getfile(BasePaginator)) + def test_paginating_empty_queryset_does_not_warn(self): with warnings.catch_warnings(record=True) as recorded: Paginator(Article.objects.none(), 5) self.assertEqual(len(recorded), 0) + async def test_paginating_empty_queryset_does_not_warn_async(self): + with warnings.catch_warnings(record=True) as recorded: + AsyncPaginator(Article.objects.none(), 5) + self.assertEqual(len(recorded), 0) + def test_paginating_unordered_object_list_raises_warning(self): """ Unordered object list warning with an object that has an ordered @@ -583,3 +916,58 @@ class ModelPaginationTests(TestCase): ) with self.assertWarnsMessage(UnorderedObjectListWarning, msg): Paginator(object_list, 5) + + async def test_paginating_unordered_object_list_raises_warning_async(self): + """ + See test_paginating_unordered_object_list_raises_warning. + """ + + class ObjectList: + ordered = False + + object_list = ObjectList() + msg = ( + "Pagination may yield inconsistent results with an unordered " + "object_list: {!r}.".format(object_list) + ) + with self.assertWarnsMessage(UnorderedObjectListWarning, msg): + AsyncPaginator(object_list, 5) + + async def test_async_page_object_list_raises_type_error_before_await(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(1) + + with self.subTest(func="len"): + msg = "AsyncPage.aget_object_list() must be awaited before calling len()." + with self.assertRaisesMessage(TypeError, msg): + len(p) + + with self.subTest(func="reversed"): + msg = ( + "AsyncPage.aget_object_list() must be awaited before calling " + "reversed()." + ) + with self.assertRaisesMessage(TypeError, msg): + reversed(p) + + with self.subTest(func="index"): + msg = "AsyncPage.aget_object_list() must be awaited before using indexing." + with self.assertRaisesMessage(TypeError, msg): + p[0] + + async def test_async_page_aiteration(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(1) + object_list = [obj async for obj in p] + self.assertEqual(len(object_list), 5) + + async def test_aget_object_list(self): + paginator = AsyncPaginator(Article.objects.order_by("id"), 5) + p = await paginator.apage(1) + + # object_list queryset is converted to list. + first_called_objs = await p.aget_object_list() + self.assertIsInstance(first_called_objs, list) + # It returns the same list that was converted on the first call. + second_called_objs = await p.aget_object_list() + self.assertEqual(id(first_called_objs), id(second_called_objs)) |