documented the async paginator

Author: amirreza8002

django_async_extensions/acore/paginator.py

@@ -30,8 +30,6 @@ async def __aiter__(self):
             yield await self.apage(page_number)
 
     def _validate_number(self, number, num_pages):
-        """Validate the given 1-based page number."""
-
         try:
             if isinstance(number, float) and not number.is_integer():
                 raise ValueError
@@ -46,10 +44,15 @@ def _validate_number(self, number, num_pages):
         return number
 
     async def avalidate_number(self, number):
+        """Validate the given 1-based page number."""
         num_page = await self.anum_pages()
         return self._validate_number(number, num_page)
 
     async def aget_page(self, number):
+        """
+        Return a valid page, even if the page argument isn't a number or isn't
+        in range.
+        """
         try:
             number = await self.avalidate_number(number)
         except PageNotAnInteger:
@@ -59,7 +62,7 @@ async def aget_page(self, number):
         return await self.apage(number)
 
     async def apage(self, number):
-        """See Paginator.page()."""
+        """Return a AsyncPage object for the given 1-based page number."""
         number = await self.avalidate_number(number)
         bottom = (number - 1) * self.per_page
         top = bottom + self.per_page
@@ -71,10 +74,16 @@ async def apage(self, number):
         return self._get_page(object_list, 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:`AsyncPage` object.
+        """
         return AsyncPage(*args, **kwargs)
 
     async def acount(self):
-        """See Paginator.count()."""
+        """Return the total number of objects, across all pages."""
         if self._cache_acount is not None:
             return self._cache_acount
 
@@ -97,7 +106,7 @@ async def acount(self):
         return count
 
     async def anum_pages(self):
-        """See Paginator.num_pages()."""
+        """Return the total number of pages."""
         if self._cache_anum_pages is not None:
             return self._cache_anum_pages
 
@@ -113,11 +122,24 @@ async def anum_pages(self):
         return num_pages
 
     async def apage_range(self):
-        """See Paginator.page_range()"""
+        """
+        Return a 1-based range of pages for iterating through within
+        a template for loop.
+        """
         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):
+        """
+        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.
+        """
         number = await self.avalidate_number(number)
         num_pages = await self.anum_pages()
         page_range = await self.apage_range()
@@ -130,16 +152,6 @@ async def aget_elided_page_range(self, number=1, *, on_each_side=3, on_ends=2):
     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
@@ -201,9 +213,11 @@ async def agetitem(self, index):
         return self.object_list[index]
 
     async def alen(self):
+        """an async interface to be used instead of `len(page)`"""
         return len(await self.alist())
 
     async def alist(self):
+        """make a list of the items in the queryset"""
         if hasattr(self.object_list, "__aiter__"):
             return [obj async for obj in self.object_list]
         return await sync_to_async(list)(self.object_list)
@@ -227,14 +241,21 @@ async def aprevious_page_number(self):
         return await self.paginator.avalidate_number(self.number - 1)
 
     async def astart_index(self):
-        """See Page.start_index()."""
+        """
+        Return the 1-based index of the first object on this page,
+        relative to total objects in the paginator.
+        """
         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()."""
+        """
+        Return the 1-based index of the last object on this page,
+        relative to total objects found (hits).
+        """
+        # Special case for the last page because there can be orphans.
         num_pages = await self.paginator.anum_pages()
         if self.number == num_pages:
             return await self.paginator.acount()

docs/core/async-paginator.md

@@ -0,0 +1,168 @@
+## AsyncPaginator
+
+the `AsyncPaginator` class is an async version of django's [Paginator](https://docs.djangoproject.com/en/5.1/ref/paginator/#django.core.paginator.Paginator).
+
+although `AsyncPaginator` inherits from django's `Paginator`, but this is only for code reuse and easier migration from sync to async, and you should not call the sync methods from an async environment.
+
+the paginator can take a queryset or a list, but they have slightly different behaviours,
+if you pass in a queryset to the paginator, the queryset is preserved until it has to be evaluated, so until it is evaluated it needs to be treated as a queryset,
+and using querysets in an async environment is different from using querysets in sync environments.
+
+### Examples
+
+**note**: in normal django shell you can not `await`, to use `await` you need a shell tht supports that, such as [ipython](https://ipython.org/)
+
+#### Example of list pagination
+
+```pycon
+In [1]: from django_async_extensions.acore.paginator import AsyncPaginator
+
+In [2]: objects = ["john", "paul", "george", "ringo"]
+
+In [3]: p = AsyncPaginator(objects, 2)
+
+In [4]: await p.acount()
+Out[4]: 4
+
+In [5]: await p.anum_pages()
+Out[5]: 2
+
+In [6]: type(await p.apage_range())
+Out[6]: range
+
+In [7]: await p.apage_range()
+Out[7]: range(1, 3)
+
+In [8]: page1 = await p.apage(1)
+
+In [9]: page1
+Out[9]: <Async Page 1>
+
+In [10]: page1.object_list
+Out[10]: ['john', 'paul']
+
+In [11]: page2 = await p.apage(2)
+
+In [12]: page2.object_list
+Out[12]: ['george', 'ringo']
+
+In [13]: await page2.ahas_next()
+Out[13]: False
+
+In [14]: await page2.ahas_previous()
+Out[14]: True
+
+In [15]: await page2.ahas_other_pages()
+Out[15]: True
+
+await page2.anext_page_number()
+Traceback (most recent call last):
+...
+EmptyPage: That page contains no results
+
+In [17]: await page2.aprevious_page_number()
+Out[17]: 1
+
+In [18]: await page2.astart_index()
+Out[18]: 3
+
+In [19]: await page2.aend_index()
+Out[19]: 4
+
+In [20]: await p.apage(0)
+Traceback (most recent call last):
+...
+EmptyPage: That page number is less than 1
+
+In [21]: await p.apage(3)
+Traceback (most recent call last):
+...
+EmptyPage: That page contains no results
+```
+
+
+#### Example of queryset pagination
+
+```pycon
+In [1]: from django.contrib.auth.models import User
+
+In [2]: objs = [User(username=f"test{i}", password="testpass123") for i in range
+   ...: (1, 5)]
+
+In [3]: User.objects.bulk_create(objs)
+Out[3]: [<User: test1>, <User: test2>, <User: test3>, <User: test4>]
+
+In [4]: from django_async_extensions.acore.paginator import AsyncPaginator
+
+In [5]: users = User.objects.order_by("username")
+
+In [6]: p = AsyncPaginator(users, 2)
+
+In [7]: p.object_list
+Out[7]: <QuerySet [<User: test1>, <User: test2>, <User: test3>, <User: test4>]>
+
+In [8]: page1 = await p.apage(1)
+
+In [9]: page1
+Out[9]: <Async Page 1>
+
+In [10]: page1.object_list
+Out[10]: <QuerySet [<User: test1>, <User: test2>]>
+
+In [11]: page2 = await p.apage(2)
+
+In [12]: page2.object_list
+Out[12]: <QuerySet [<User: test3>, <User: test4>]>
+
+In [13]: await page2.ahas_next()
+Out[13]: False
+
+In [14]: await page2.alen()  # use this instead of `len()`
+Out[14]: 2
+
+In [15]: len(page2)
+---------------------------------------------------------------------------
+TypeError                                 Traceback (most recent call last)
+Cell In[15], line 1
+----> 1 len(page2)
+
+TypeError: object of type 'AsyncPage' has no len()
+
+In [16]: await page2.alist()  # use this instead of `list()`
+Out[16]: [<User: test3>, <User: test4>]
+
+In [17]: list(page2)
+---------------------------------------------------------------------------
+TypeError                                 Traceback (most recent call last)
+Cell In[17], line 1
+----> 1 list(page2)
+
+TypeError: 'AsyncPage' object is not iterable
+
+In [18]: page2.object_list
+Out[19]: <QuerySet [<User: test3>, <User: test4>]>
+
+In [20]: await page2.agetitem(1)  # use this instead of `__getitem__()`
+Out[20]: <User: test4>
+
+In [21]: page2.object_list
+Out[21]: [<User: test3>, <User: test4>]  # after `agetitem()` is called, the object list gets turned into a list
+
+In [22]: page1.object_list
+Out[22]: <QuerySet [<User: test1>, <User: test2>]>
+
+In [23]: page1[0]
+---------------------------------------------------------------------------
+TypeError                                 Traceback (most recent call last)
+Cell In[23], line 1
+----> 1 page1[0]
+
+TypeError: 'AsyncPage' object is not subscriptable
+
+In [24]: await page1.agetitem(slice(2))  # you can pass a slice to `agetitem()`
+Out[24]: [<User: test1>, <User: test2>]
+
+In [25]: page1.object_list
+Out[25]: [<User: test1>, <User: test2>]  # turned into a list
+
+```