Merge pull request #46 from sinch/DEVEXP-733_Auto-Pagination

DEVEXP-733: Auto pagination of elements

Author: matsk-sinch

README.md

@@ -141,8 +141,8 @@ By default, two HTTP implementations are provided:
 For creating custom HTTP client code, use either `SinchClient` or `SinchClientAsync` client and inject your transport during initialisation:
 ```python
 sinch_client = SinchClientAsync(
-    key_id="Spanish",
-    key_secret="Inquisition",
+    key_id="key_id",
+    key_secret="key_secret",
     project_id="some_project",
     transport=MyHTTPAsyncImplementation
 )

sinch/core/adapters/requests_http_transport.py

@@ -17,7 +17,6 @@ def request(self, endpoint: HTTPEndpoint) -> HTTPResponse:
             f"Sync HTTP {request_data.http_method} call with headers:"
             f" {request_data.headers} and body: {request_data.request_body} to URL: {request_data.url}"
         )
-
         response = self.http_session.request(
             method=request_data.http_method,
             url=request_data.url,

sinch/core/clients/sinch_client_configuration.py

@@ -34,18 +34,18 @@ def __init__(
         self.connection_timeout = connection_timeout
         self.sms_api_token = sms_api_token
         self.service_plan_id = service_plan_id
-        self.auth_origin = "auth.sinch.com"
-        self.numbers_origin = "numbers.api.sinch.com"
-        self.verification_origin = "verification.api.sinch.com"
-        self.voice_applications_origin = "callingapi.sinch.com"
-        self._voice_domain = "{}.api.sinch.com"
+        self.auth_origin = "https://auth.sinch.com"
+        self.numbers_origin = "https://numbers.api.sinch.com"
+        self.verification_origin = "https://verification.api.sinch.com"
+        self.voice_applications_origin = "https://callingapi.sinch.com"
+        self._voice_domain = "https://{}.api.sinch.com"
         self._voice_region = None
         self._conversation_region = "eu"
         self._conversation_domain = ".conversation.api.sinch.com"
         self._sms_region = "us"
         self._sms_region_with_service_plan_id = "us"
-        self._sms_domain = "zt.{}.sms.api.sinch.com"
-        self._sms_domain_with_service_plan_id = "{}.sms.api.sinch.com"
+        self._sms_domain = "https://zt.{}.sms.api.sinch.com"
+        self._sms_domain_with_service_plan_id = "https://{}.sms.api.sinch.com"
         self._sms_authentication = HTTPAuthentication.OAUTH.value
         self._templates_region = "eu"
         self._templates_domain = ".template.api.sinch.com"

sinch/core/pagination.py

@@ -1,49 +1,56 @@
 from abc import ABC, abstractmethod
+from typing import Generic
+from sinch.core.types import BM
 
 
 class PageIterator:
-    def __init__(self, paginator):
+    def __init__(self, paginator, yield_first_page=False):
         self.paginator = paginator
+        # If yielding the first page, set started to False
+        self.started = not yield_first_page
 
     def __iter__(self):
         return self
 
     def __next__(self):
+        if not self.started:
+            self.started = True
+            return self.paginator
+
         if self.paginator.has_next_page:
-            return self.paginator.next_page()
+            self.paginator = self.paginator.next_page()
+            return self.paginator
         else:
             raise StopIteration
 
 
 class AsyncPageIterator:
-    def __init__(self, paginator):
+    def __init__(self, paginator, yield_first_page=False):
         self.paginator = paginator
+        self.started = not yield_first_page
 
     def __aiter__(self):
         return self
 
     async def __anext__(self):
+        if not self.started:
+            self.started = True
+            return self.paginator
+
         if self.paginator.has_next_page:
-            return await self.paginator.next_page()
+            next_paginator = await self.paginator.next_page()
+            if next_paginator:
+                self.paginator = next_paginator
+                return self.paginator
         else:
             raise StopAsyncIteration
 
 
-class Paginator(ABC):
+class Paginator(ABC, Generic[BM]):
     """
     Pagination response object.
-
-    auto_paging_iter method returns an iterator object that can be used for iterator-based page traversing.
-    For example:
-        for page in paginated_response.auto_paging_iter():
-            ...process page object
-
-    For manual pagination use has_next_page property with next_page() method.
-    For example:
-        if paginated_response.has_next_page:
-            paginated_response = paginated_response.next_page()
     """
-    def __init__(self, sinch, endpoint, result):
+    def __init__(self, sinch, endpoint, result: BM):
         self._sinch = sinch
         self.result = result
         self.endpoint = endpoint
@@ -53,8 +60,14 @@ def __init__(self, sinch, endpoint, result):
     def __repr__(self):
         return "Paginated response content: " + str(self.result)
 
-    @abstractmethod
-    def auto_paging_iter(self):
+    # TODO: Make content() method abstract in Parent class as we implement in the other domains:
+    #  - Refactor pydantic models in other domains to have a content property.
+    def content(self):
+        pass
+
+    # TODO: Make iterator() method abstract in Parent class as we implement in the other domains:
+    #  - Refactor pydantic models in other domains to have a content property.
+    def iterator(self):
         pass
 
     @abstractmethod
@@ -105,51 +118,79 @@ async def next_page(self):
         return self
 
     def auto_paging_iter(self):
-        return AsyncPageIterator(self)
+        return AsyncPageIterator(self, yield_first_page=True)
 
     @classmethod
     async def _initialize(cls, sinch, endpoint):
         result = await sinch.configuration.transport.request(endpoint)
         return cls(sinch, endpoint, result)
 
 
-class TokenBasedPaginator(Paginator):
-    __doc__ = Paginator.__doc__
+class TokenBasedPaginator(Paginator[BM]):
+    """Base paginator for token-based pagination with explicit page navigation and metadata."""
 
-    def _calculate_next_page(self):
-        if self.result.next_page_token:
-            self.has_next_page = True
-        else:
-            self.has_next_page = False
+    def __init__(self, sinch, endpoint, result=None):
+        super().__init__(sinch, endpoint, result or sinch.configuration.transport.request(endpoint))
+
+    def content(self) -> list[BM]:
+        return getattr(self.result, "content", [])
 
     def next_page(self):
+        """Returns a new paginator instance for the next page."""
+        if not self.has_next_page:
+            return None
+
         self.endpoint.request_data.page_token = self.result.next_page_token
         self.result = self._sinch.configuration.transport.request(self.endpoint)
         self._calculate_next_page()
         return self
 
-    def auto_paging_iter(self):
-        return PageIterator(self)
+    def iterator(self):
+        """Iterates over individual items across all pages."""
+        paginator = self
+        while paginator:
+            yield from paginator.content()
+
+            next_page_instance = paginator.next_page()
+            if not next_page_instance:
+                break
+            paginator = next_page_instance
+
+    def _calculate_next_page(self):
+        self.has_next_page = bool(getattr(self.result, "next_page_token", None))
 
     @classmethod
     def _initialize(cls, sinch, endpoint):
+        """Creates an instance of the paginator skipping first page."""
         result = sinch.configuration.transport.request(endpoint)
-        return cls(sinch, endpoint, result)
+        return cls(sinch, endpoint, result=result)
 
 
 class AsyncTokenBasedPaginator(TokenBasedPaginator):
-    __doc__ = TokenBasedPaginator.__doc__
+    """Asynchronous token-based paginator."""
 
     async def next_page(self):
+        if not self.has_next_page:
+            return None
+
         self.endpoint.request_data.page_token = self.result.next_page_token
-        self.result = await self._sinch.configuration.transport.request(self.endpoint)
-        self._calculate_next_page()
-        return self
+        next_result = await self._sinch.configuration.transport.request(self.endpoint)
 
-    def auto_paging_iter(self):
-        return AsyncPageIterator(self)
+        return self.__class__(self._sinch, self.endpoint, result=next_result)
+
+    async def iterator(self):
+        """Iterates asynchronously over individual items across all pages."""
+        paginator = self
+        while paginator:
+            for item in paginator.content():
+                yield item
+
+            next_page_instance = await paginator.next_page()
+            if not next_page_instance:
+                break
+            paginator = next_page_instance
 
     @classmethod
     async def _initialize(cls, sinch, endpoint):
         result = await sinch.configuration.transport.request(endpoint)
-        return cls(sinch, endpoint, result)
+        return cls(sinch, endpoint, result=result)

sinch/core/types.py

@@ -0,0 +1,4 @@
+from typing import TypeVar
+from pydantic import BaseModel
+
+BM = TypeVar("BM", bound=BaseModel)

sinch/domains/numbers/__init__.py

@@ -1,23 +1,11 @@
-from sinch.core.pagination import TokenBasedPaginator, AsyncTokenBasedPaginator
 from sinch.domains.numbers.available_numbers import AvailableNumbers
+from sinch.domains.numbers.active_numbers import ActiveNumbers, ActiveNumbersWithAsyncPagination
 from sinch.domains.numbers.endpoints.callbacks.get_configuration import GetNumbersCallbackConfigurationEndpoint
 from sinch.domains.numbers.endpoints.callbacks.update_configuration import UpdateNumbersCallbackConfigurationEndpoint
-from sinch.domains.numbers.endpoints.active.list_active_numbers_for_project import ListActiveNumbersEndpoint
-from sinch.domains.numbers.endpoints.active.update_number_configuration import UpdateNumberConfigurationEndpoint
-from sinch.domains.numbers.endpoints.active.get_number_configuration import GetNumberConfigurationEndpoint
-from sinch.domains.numbers.endpoints.active.release_number_from_project import ReleaseNumberFromProjectEndpoint
 from sinch.domains.numbers.endpoints.regions.list_available_regions import ListAvailableRegionsEndpoint
 
 from sinch.domains.numbers.models.regions.requests import ListAvailableRegionsForProjectRequest
-from sinch.domains.numbers.models.active.requests import (
-    ListActiveNumbersRequest, GetNumberConfigurationRequest,
-    UpdateNumberConfigurationRequest, ReleaseNumberFromProjectRequest
-)
 from sinch.domains.numbers.models.regions.responses import ListAvailableRegionsResponse
-from sinch.domains.numbers.models.active.responses import (
-    ListActiveNumbersResponse, UpdateNumberConfigurationResponse,
-    GetNumberConfigurationResponse, ReleaseNumberFromProjectResponse
-)
 from sinch.domains.numbers.models.callbacks.responses import (
     GetNumbersCallbackConfigurationResponse,
     UpdateNumbersCallbackConfigurationResponse
@@ -27,123 +15,6 @@
 )
 
 
-class ActiveNumbers:
-    def __init__(self, sinch):
-        self._sinch = sinch
-
-    def list(
-        self,
-        region_code: str,
-        number_type: str,
-        number_pattern: str = None,
-        number_search_pattern: str = None,
-        capabilities: list = None,
-        page_size: int = None,
-        page_token: str = None
-    ) -> ListActiveNumbersResponse:
-        """
-        Search for all active virtual numbers associated with a certain project.
-        For additional documentation, see https://www.sinch.com and visit our developer portal.
-        """
-        return TokenBasedPaginator._initialize(
-            sinch=self._sinch,
-            endpoint=ListActiveNumbersEndpoint(
-                project_id=self._sinch.configuration.project_id,
-                request_data=ListActiveNumbersRequest(
-                    region_code=region_code,
-                    number_type=number_type,
-                    page_size=page_size,
-                    capabilities=capabilities,
-                    number_pattern=number_pattern,
-                    number_search_pattern=number_search_pattern,
-                    page_token=page_token
-                )
-            )
-        )
-
-    def update(
-        self,
-        phone_number: str = None,
-        display_name: str = None,
-        sms_configuration: dict = None,
-        voice_configuration: dict = None,
-        app_id: str = None
-    ) -> UpdateNumberConfigurationResponse:
-        """
-        Make updates to the configuration of your virtual number.
-        Update the display name, change the currency type, or reconfigure for either SMS and/or Voice.
-        For additional documentation, see https://www.sinch.com and visit our developer portal.
-        """
-        return self._sinch.configuration.transport.request(
-            UpdateNumberConfigurationEndpoint(
-                project_id=self._sinch.configuration.project_id,
-                request_data=UpdateNumberConfigurationRequest(
-                    phone_number=phone_number,
-                    display_name=display_name,
-                    sms_configuration=sms_configuration,
-                    voice_configuration=voice_configuration,
-                    app_id=app_id
-                )
-            )
-        )
-
-    def get(self, phone_number: str) -> GetNumberConfigurationResponse:
-        """
-        List of configuration settings for your virtual number.
-        For additional documentation, see https://www.sinch.com and visit our developer portal.
-        """
-        return self._sinch.configuration.transport.request(
-            GetNumberConfigurationEndpoint(
-                project_id=self._sinch.configuration.project_id,
-                request_data=GetNumberConfigurationRequest(
-                    phone_number=phone_number
-                )
-            )
-        )
-
-    def release(self, phone_number: str) -> ReleaseNumberFromProjectResponse:
-        """
-        Release numbers you no longer need from your project.
-        For additional documentation, see https://www.sinch.com and visit our developer portal.
-        """
-        return self._sinch.configuration.transport.request(
-            ReleaseNumberFromProjectEndpoint(
-                project_id=self._sinch.configuration.project_id,
-                request_data=ReleaseNumberFromProjectRequest(
-                    phone_number=phone_number
-                )
-            )
-        )
-
-
-class ActiveNumbersWithAsyncPagination(ActiveNumbers):
-    async def list(
-        self,
-        region_code: str,
-        number_type: str,
-        number_pattern: str = None,
-        number_search_pattern: str = None,
-        capabilities: list = None,
-        page_size: int = None,
-        page_token: str = None
-    ) -> ListActiveNumbersResponse:
-        return await AsyncTokenBasedPaginator._initialize(
-            sinch=self._sinch,
-            endpoint=ListActiveNumbersEndpoint(
-                project_id=self._sinch.configuration.project_id,
-                request_data=ListActiveNumbersRequest(
-                    region_code=region_code,
-                    number_type=number_type,
-                    page_size=page_size,
-                    capabilities=capabilities,
-                    number_pattern=number_pattern,
-                    number_search_pattern=number_search_pattern,
-                    page_token=page_token
-                )
-            )
-        )
-
-
 class AvailableRegions:
     def __init__(self, sinch):
         self._sinch = sinch