Merge pull request #130 from david-lev/result-all

[types] adding `all` method to `Result` and fix `next` and `previous` to return empty result

Author: david-lev

docs/source/content/types/others.rst

@@ -13,7 +13,7 @@ Others
 .. currentmodule:: pywa.types.others
 
 .. autoclass:: Result()
-    :members: has_next, next, has_previous, previous, before, after
+    :members: has_next, next, has_previous, previous, all, before, after, empty
 
 .. autoclass:: Pagination()
 

pywa/types/others.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import time
+
 from ..errors import WhatsAppError
 
 """Types for other objects."""
@@ -1123,15 +1125,26 @@ class Result(Generic[_T]):
 
         >>> from pywa import WhatsApp, types
         >>> wa = WhatsApp(...)
-        >>> all_blocked_users = []
         >>> res = wa.get_blocked_users(pagination=types.Pagination(limit=100))
-        >>> while True:
-        ...     all_blocked_users.extend(res)
-        ...     if not res.has_next:
-        ...         break
-        ...     res = res.next()
-        >>> all_blocked_users
-        [User(...), User(...), User(...), ...]
+        >>> for user in res:
+        ...     print(user.name, user.wa_id)
+        ...
+        >>> if res.has_next:
+        ...     next_res = res.next()
+        ...
+        >>> print(res.all())
+
+    Methods:
+        next: Get the next page of results. if there is no next page, it returns empty Result.
+        previous: Get the previous page of results. if there is no previous page, it returns empty Result.
+        all: Get all results from the current page, previous pages, and next pages.
+        empty: Returns an empty Result instance.
+
+    Properties:
+        has_next: Check if there is a next page of results.
+        has_previous: Check if there is a previous page of results.
+        before: Cursor that points to the start of the page of data that has been returned.
+        after: Cursor that points to the end of the page of data that has been returned.
     """
 
     def __init__(
@@ -1169,18 +1182,38 @@ def after(self) -> str | None:
         """Cursor that points to the end of the page of data that has been returned."""
         return self._cursors.get("after")
 
-    def next(self) -> Result[_T] | None:
-        """Get the next page of results."""
+    @property
+    def empty(self) -> Result[_T]:
+        """Returns an empty Result instance."""
+        return Result(
+            wa=self._wa,
+            response={
+                "data": [],
+                "paging": {"next": self._next_url, "cursors": self._cursors},
+            },
+            item_factory=self._item_factory,
+        )
+
+    def next(self) -> Result[_T]:
+        """
+        Get the next page of results. if there is no next page, it returns empty Result.
+
+        - Check if there is a next page using the :attr:`~pywa.types.others.Result.has_next` property before calling this method.
+        """
         if self.has_next:
             # noinspection PyProtectedMember
             response = self._wa.api._make_request(method="GET", endpoint=self._next_url)
             return Result(
                 wa=self._wa, response=response, item_factory=self._item_factory
             )
-        return None
+        return self.empty
+
+    def previous(self) -> Result[_T]:
+        """
+        Get the previous page of results. if there is no previous page, it returns empty Result.
 
-    def previous(self) -> Result[_T] | None:
-        """Get the previous page of results."""
+        - Check if there is a previous page using the :attr:`~pywa.types.others.Result.has_previous` property before calling this method.
+        """
         if self.has_previous:
             # noinspection PyProtectedMember
             response = self._wa.api._make_request(
@@ -1189,22 +1222,53 @@ def previous(self) -> Result[_T] | None:
             return Result(
                 wa=self._wa, response=response, item_factory=self._item_factory
             )
-        return None
+        return self.empty
+
+    def all(
+        self,
+        *,
+        sleep: float = 0.0,
+    ) -> list[_T]:
+        """
+        Get all results from the current page, previous pages, and next pages.
+
+        - Make sure to provide higher limit in the ``Pagination`` parameter to avoid hitting rate limits.
+        - Also consider using the ``sleep`` parameter to avoid hitting rate limits.
+
+        Args:
+            sleep: The number of seconds to sleep between requests to avoid hitting rate limits. Default is 0.0 (no sleep).
+
+        Returns:
+            A list of all results from the current page, previous pages, and next pages.
+        """
+        before_data = []
+        after_data = []
+
+        prev = self
+        while prev.has_previous:
+            if sleep > 0:
+                time.sleep(sleep)
+            prev = prev.previous()
+            before_data = prev._data + before_data
+
+        next_page = self
+        while next_page.has_next:
+            if sleep > 0:
+                time.sleep(sleep)
+            next_page = next_page.next()
+            after_data += next_page._data
+
+        return before_data + self._data + after_data
 
     def __iter__(self) -> Iterator[_T]:
-        yield from self._data
+        return iter(self._data)
 
     def __len__(self) -> int:
         return len(self._data)
 
     def __getitem__(self, index: int) -> _T:
         return self._data[index]
 
-    def __next__(self) -> _T:
-        if self._data:
-            return self._data.pop(0)
-        raise StopIteration
-
     def __bool__(self) -> bool:
         return bool(self._data)
 

pywa_async/types/others.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 from typing import TYPE_CHECKING
 
 from pywa.types.others import *  # noqa MUST BE IMPORTED FIRST
@@ -96,23 +97,50 @@ class Result(_Result[_T]):
 
     Example:
 
-        >>> from pywa_async import WhatsApp, types
+        >>> from pywa import WhatsApp, types
         >>> wa = WhatsApp(...)
-        >>> all_blocked_users = []
-        >>> res = await wa.get_blocked_users(pagination=types.Pagination(limit=100))
-        >>> while True:
-        ...     all_blocked_users.extend(res)
-        ...     if not res.has_next:
-        ...         break
-        ...     res = await res.next()
-        >>> all_blocked_users
-        [User(...), User(...), User(...), ...]
+        >>> res = wa.get_blocked_users(pagination=types.Pagination(limit=100))
+        >>> for user in res:
+        ...     print(user.name, user.wa_id)
+        ...
+        >>> if res.has_next:
+        ...     next_res = res.next()
+        ...
+        >>> print(res.all())
+
+    Methods:
+        next: Get the next page of results. if there is no next page, it returns empty Result.
+        previous: Get the previous page of results. if there is no previous page, it returns empty Result.
+        all: Get all results from the current page, previous pages, and next pages.
+        empty: Returns an empty Result instance.
+
+    Properties:
+        has_next: Check if there is a next page of results.
+        has_previous: Check if there is a previous page of results.
+        before: Cursor that points to the start of the page of data that has been returned.
+        after: Cursor that points to the end of the page of data that has been returned.
     """
 
     _wa: WhatsAppAsync
 
-    async def next(self) -> Result[_T] | None:
-        """Get the next page of results."""
+    @property
+    def empty(self) -> Result[_T]:
+        """Returns an empty Result instance."""
+        return Result(
+            wa=self._wa,
+            response={
+                "data": [],
+                "paging": {"next": self._next_url, "cursors": self._cursors},
+            },
+            item_factory=self._item_factory,
+        )
+
+    async def next(self) -> Result[_T]:
+        """
+        Get the next page of results. if there is no next page, it returns empty Result.
+
+        - Check if there is a next page using the :attr:`~pywa.types.others.Result.has_next` property before calling this method.
+        """
         if self.has_next:
             # noinspection PyProtectedMember
             response = await self._wa.api._make_request(
@@ -121,10 +149,14 @@ async def next(self) -> Result[_T] | None:
             return Result(
                 wa=self._wa, response=response, item_factory=self._item_factory
             )
-        return None
+        return self.empty
+
+    async def previous(self) -> Result[_T]:
+        """
+        Get the previous page of results. if there is no previous page, it returns empty Result.
 
-    async def previous(self) -> Result[_T] | None:
-        """Get the previous page of results."""
+        - Check if there is a previous page using the :attr:`~pywa.types.others.Result.has_previous` property before calling this method.
+        """
         if self.has_previous:
             # noinspection PyProtectedMember
             response = await self._wa.api._make_request(
@@ -133,4 +165,41 @@ async def previous(self) -> Result[_T] | None:
             return Result(
                 wa=self._wa, response=response, item_factory=self._item_factory
             )
-        return None
+        return self.empty
+
+    async def all(
+        self,
+        *,
+        sleep: float = 0.0,
+    ) -> list[_T]:
+        """
+        Get all results from the current page, previous pages, and next pages.
+
+        - Make sure to provide higher limit in the ``Pagination`` parameter to avoid hitting rate limits.
+        - Also consider using the ``sleep`` parameter to avoid hitting rate limits.
+
+        Args:
+            sleep: The number of seconds to sleep between requests to avoid hitting rate limits. Default is 0.0 (no sleep).
+
+        Returns:
+            A list of all results from the current page, previous pages, and next pages.
+        """
+        before_data = []
+        after_data = []
+
+        prev = self
+        while prev.has_previous:
+            if sleep > 0:
+                await asyncio.sleep(sleep)
+            prev = await prev.previous()
+            # noinspection PyProtectedMember
+            before_data = prev._data + before_data
+
+        next_page = self
+        while next_page.has_next:
+            if sleep > 0:
+                await asyncio.sleep(sleep)
+            next_page = await next_page.next()
+            after_data += next_page._data
+
+        return before_data + self._data + after_data