adds metadata implementation for the pagination

Author: sufyankhanrao

apimatic_core/api_call.py

@@ -95,8 +95,8 @@ def execute(self):
         return self._response_handler.handle(_http_response, self._global_configuration.get_global_errors())
 
 
-    def paginate(self, paginated_data_wrap_using):
-        return paginated_data_wrap_using(PaginatedData(self))
+    def paginate(self, page_iterable_creator, page_creator):
+        return page_iterable_creator(PaginatedData(self, page_creator))
 
     def clone(self, global_configuration=None, request_builder=None, response_handler=None,
               endpoint_configuration=None, pagination_stategies=None, paginated_item_converter=None):

apimatic_core/pagination/configuration/cursor_pagination.py

@@ -3,50 +3,51 @@
 
 
 class CursorPagination(PaginationStrategy):
-    def __init__(self, output=None, input_=None):
+
+    @property
+    def metadata(self):
+        return self._metadata_creator(self._cursor_value)
+
+    def __init__(self, output, input_, metadata_creator):
+        super().__init__(metadata_creator)
+
         if input_ is None:
             raise ValueError("Input pointer for cursor based pagination cannot be None")
         if output is None:
             raise ValueError("Output pointer for cursor based pagination cannot be None")
+
         self._output = output
         self._input = input_
+        self._cursor_value = None
 
     def apply(self, paginated_data):
         last_response = paginated_data.last_response
         request_builder = paginated_data.request_builder
 
         if last_response is None:
+            self._cursor_value = self._get_initial_cursor_value(request_builder, self._input)
             return request_builder
 
-        cursor_value = ApiHelper.resolve_response_pointer(
+        self._cursor_value = ApiHelper.resolve_response_pointer(
             self._output,
             last_response.text,
             last_response.headers
         )
 
-        if cursor_value is None:
+        if self._cursor_value is None:
             return None
 
-        return self._get_updated_request_builder(request_builder, cursor_value)
+        return self.get_updated_request_builder(request_builder, self._input, self._cursor_value)
 
-    def _get_updated_request_builder(self, request_builder, cursor_value):
-        path_prefix, field_path = ApiHelper.split_into_parts(self._input)
-        template_params = request_builder.template_params
-        query_params = request_builder.query_params
-        header_params = request_builder.header_params
+    @staticmethod
+    def _get_initial_cursor_value(request_builder, input_pointer):
+        path_prefix, field_path = ApiHelper.split_into_parts(input_pointer)
 
         if path_prefix == "$request.path":
-            template_params = ApiHelper.update_entry_by_json_pointer(
-                template_params.copy(), field_path, cursor_value, inplace=True)
+            return ApiHelper.get_value_by_json_pointer(request_builder.template_params, field_path)
         elif path_prefix == "$request.query":
-            query_params = ApiHelper.update_entry_by_json_pointer(
-                query_params.copy(), field_path, cursor_value, inplace=True)
+            return ApiHelper.get_value_by_json_pointer(request_builder.query_params, field_path)
         elif path_prefix == "$request.headers":
-            header_params = ApiHelper.update_entry_by_json_pointer(
-                header_params.copy(), field_path, cursor_value, inplace=True)
-
-        return request_builder.clone_with(
-            template_params=template_params,
-            query_params=query_params,
-            header_params=header_params
-        )
+            return ApiHelper.get_value_by_json_pointer(request_builder.header_params, field_path)
+
+        return None

apimatic_core/pagination/configuration/link_pagination.py

@@ -6,16 +6,18 @@
 class LinkPagination(PaginationStrategy):
     """Pagination manager implementation for link-based pagination."""
 
-    def __init__(self, next_link):
-        """
-        Initializes a new instance of the LinkPagination class.
-
-        Args:
-            next (str): JSON pointer of a field in the response, representing the next request query URL.
-        """
-        if next_link is None:
+    @property
+    def metadata(self):
+        return self._metadata_creator(self._next_link)
+
+    def __init__(self, next_link_pointer, metadata_creator):
+        super().__init__(metadata_creator)
+
+        if next_link_pointer is None:
             raise ValueError("Next link pointer for cursor based pagination cannot be None")
-        self._next_link = next_link
+
+        self._next_link_pointer = next_link_pointer
+        self._next_link = None
 
     def apply(self, paginated_data):
         last_response = paginated_data.last_response
@@ -24,20 +26,19 @@ def apply(self, paginated_data):
         if last_response is None:
             return request_builder
 
-        link_value = ApiHelper.resolve_response_pointer(
-            self._next_link,
+        self._next_link = ApiHelper.resolve_response_pointer(
+            self._next_link_pointer,
             last_response.text,
             last_response.headers
         )
 
-        if link_value is None:
+        if self._next_link is None:
             return None
 
-        query_params = ApiHelper.get_query_parameters(link_value)
+        query_params = ApiHelper.get_query_parameters(self._next_link)
         updated_query_params = request_builder.query_params.copy()
         updated_query_params.update(query_params)
 
         return request_builder.clone_with(
             query_params=updated_query_params
         )
-

apimatic_core/pagination/configuration/offset_pagination.py

@@ -6,13 +6,19 @@
 class OffsetPagination(PaginationStrategy):
     """Pagination manager implementation for offset-based pagination."""
 
-    def __init__(self, input_):
+    @property
+    def metadata(self):
+        return self._metadata_creator(self._offset)
+
+    def __init__(self, input_, metadata_creator):
         """
         Initializes a new instance of the OffsetPagination class.
 
         Args:
             input_ (str): JSON pointer to the request field representing the offset.
         """
+        super().__init__(metadata_creator)
+
         if input_ is None:
             raise ValueError("Input pointer for offset based pagination cannot be None")
 
@@ -42,4 +48,4 @@ def _get_initial_offset(self, request_builder):
         elif path_prefix == "$request.headers":
             return int(ApiHelper.get_value_by_json_pointer(request_builder.header_params, field_path))
 
-        return 0
+        return 0

apimatic_core/pagination/configuration/page_pagination.py

@@ -2,13 +2,14 @@
 from apimatic_core.utilities.api_helper import ApiHelper
 
 class PagePagination(PaginationStrategy):
-    def __init__(self, input_):
-        """
-        Initializes a new instance of the OffsetPagination class.
 
-        Args:
-            input_ (str): JSON pointer to the request field representing the offset.
-        """
+    @property
+    def metadata(self):
+        return self._metadata_creator(self._page_number)
+
+    def __init__(self, input_, metadata_creator):
+        super().__init__(metadata_creator)
+
         if input_ is None:
             raise ValueError("Input pointer for page based pagination cannot be None")
 
@@ -25,42 +26,7 @@ def apply(self, paginated_data):
             return request_builder
         self._page_number += 1 if last_page_size > 0 else 0
 
-        return self._get_updated_request_builder(request_builder, last_page_size)
-
-    def _get_updated_request_builder(self, request_builder, last_page_size):
-        """
-        Updates the given request builder with the new offset or cursor value for pagination.
-
-        Depending on the JSON pointer prefix, updates the appropriate field in the path, query, or headers
-        with the new offset or cursor value, and returns a cloned request builder with these updated parameters.
-
-        Args:
-            request_builder: The request builder instance to update.
-
-        Returns:
-            A new request builder instance with updated pagination parameters.
-        """
-        path_prefix, field_path = ApiHelper.split_into_parts(self._input)
-        template_params = request_builder.template_params
-        query_params = request_builder.query_params
-        header_params = request_builder.header_params
-        self._page_number += 1 if last_page_size > 0 else 0
-
-        if path_prefix == "$request.path":
-            template_params = ApiHelper.update_entry_by_json_pointer(
-                template_params.copy(), field_path, self._page_number, inplace=True)
-        elif path_prefix == "$request.query":
-            query_params = ApiHelper.update_entry_by_json_pointer(
-                query_params.copy(), field_path, self._page_number, inplace=True)
-        elif path_prefix == "$request.headers":
-            header_params = ApiHelper.update_entry_by_json_pointer(
-                header_params.copy(), field_path, self._page_number, inplace=True)
-
-        return request_builder.clone_with(
-            template_params=template_params,
-            query_params=query_params,
-            header_params=header_params
-        )
+        return self.get_updated_request_builder(request_builder, self._input, self._page_number)
 
     def _get_initial_page_offset(self, request_builder):
         path_prefix, field_path = ApiHelper.split_into_parts(self._input)

apimatic_core/pagination/paginated_data.py

@@ -17,10 +17,11 @@ def request_builder(self):
 
     @property
     def page_size(self):
-        return len(self._page)
+        return len(self._items)
 
-    def __init__(self, api_call):
+    def __init__(self, api_call, page_creator):
         self._api_call = copy.deepcopy(api_call)
+        self._page_creator = page_creator
         self._initial_request_builder = api_call.request_builder
         self._pagination_strategies = self._api_call.get_pagination_stategies
         self._http_call_context =\
@@ -29,21 +30,22 @@ def __init__(self, api_call):
             http_callback=self._http_call_context)
         self._global_configuration = self._api_call.global_configuration.clone_with(
             http_client_configuration=_http_client_configuration)
-        self._page = []
+        self._page = None
+        self._items = []
         self._current_index = 0
 
     def __iter__(self):
         return self._get_new_self_instance()
 
     def __next__(self):
         if self._current_index >= self.page_size:
-            self._page = self._fetch_next_page()
+            _, self._items = self._fetch_next_page()
             self._current_index = 0
 
-        if not self._page:
+        if not self._items:
             raise StopIteration
 
-        item = self._page[self._current_index]
+        item = self._items[self._current_index]
         self._current_index += 1
         return item
 
@@ -55,12 +57,15 @@ def pages(self):
         paginated_data = self._get_new_self_instance()
 
         while True:
-            paginated_data._page = paginated_data._fetch_next_page(should_convert_items=False)
-            if not paginated_data._page:
+            metadata, paginated_data._page = paginated_data._fetch_next_page(is_page_iterator=True)
+            if not paginated_data._page or not metadata:
                 break
-            yield paginated_data._page
+            paginated_data._items = self._api_call.get_paginated_item_converter(paginated_data._page)
+            if not paginated_data._items:
+                break
+            yield self._page_creator(metadata, paginated_data._page)
 
-    def _fetch_next_page(self, should_convert_items=True):
+    def _fetch_next_page(self, is_page_iterator=False):
         for pagination_strategy in self._pagination_strategies:
             request_builder = pagination_strategy.apply(self)
             if request_builder is None:
@@ -69,10 +74,12 @@ def _fetch_next_page(self, should_convert_items=True):
                 response = self._api_call.clone(
                     global_configuration=self._global_configuration, request_builder=request_builder
                 ).execute()
-                return self._api_call.get_paginated_item_converter(response) if should_convert_items else response
+                response = response if is_page_iterator else self._api_call.get_paginated_item_converter(response)
+                metadata = pagination_strategy.metadata if is_page_iterator else None
+                return metadata, response
             except Exception as ex:
                 raise ex
         return []
 
     def _get_new_self_instance(self):
-        return PaginatedData(self._api_call.clone(request_builder=self._initial_request_builder))
+        return PaginatedData(self._api_call.clone(request_builder=self._initial_request_builder), self._page_creator)

apimatic_core/pagination/pagination_strategy.py

@@ -11,6 +11,12 @@ class PaginationStrategy(ABC):
     to provide specific pagination management logic for paginated API responses.
     """
 
+    def __init__(self, metadata_creator):
+        if metadata_creator is None:
+            raise ValueError("Metadata creator for offset based pagination cannot be None")
+
+        self._metadata_creator = metadata_creator
+
     @abstractmethod
     def apply(self, paginated_data):
         """
@@ -24,6 +30,11 @@ def apply(self, paginated_data):
         """
         ...
 
+    @property
+    @abstractmethod
+    def metadata(self):
+        ...
+
     @staticmethod
     def get_updated_request_builder(request_builder, input_pointer, offset):
         """