feat(python): add support for offset, cursor, link and page based pagination (#95)

Since many APIs use different pagination strategies, and this change ensures the SDK can handle them flexibly. This commit adds support for offset, link, page, and cursor-based pagination types in the core library, including relevant unit tests for each type.

Author: MaryamAdnan3

.github/workflows/test-runner.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-22.04]
-        python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python

.gitignore

@@ -160,4 +160,5 @@ cython_debug/
 .idea/
 
 # Visual Studio Code
-.vscode/
+.vscode/
+.qodo

README.md

@@ -96,6 +96,16 @@ pip install apimatic-core
 | [`AnyOf`](apimatic_core/types/union_types/any_of.py )                         | A class to represent information about AnyOf union types                     |
 | [`LeafType`](apimatic_core/types/union_types/leaf_type.py )                   | A class to represent the case information in an OneOf or AnyOf union type    |
 
+## Pagination
+| Name                                                                           | Description                                                                                                                                                                                                                                                                                     |
+|--------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`CursorPagination`](apimatic_core/pagination/strategies/cursor_pagination.py) | This class manages the extraction and injection of cursor values between API requests and responses, enabling seamless traversal of paginated data. It validates required pointers, updates the request builder with the appropriate cursor, and applies a metadata wrapper to paged responses. |
+| [`LinkPagination`](apimatic_core/pagination/strategies/link_pagination.py)     | This class updates the request builder with query parameters from the next page link and applies a metadata wrapper to the paged response.                                                                                                                                                      |
+| [`OffsetPagination`](apimatic_core/pagination/strategies/offset_pagination.py) | This class manages pagination by updating an offset parameter in the request builder, allowing sequential retrieval of paginated data. It extracts and updates the offset based on a configurable JSON pointer and applies a metadata wrapper to each page response.                            |
+| [`PagePagination`](apimatic_core/pagination/strategies/page_pagination.py)     | This class manages pagination by updating the request builder with the appropriate page number, using a JSON pointer to identify the pagination parameter. It also applies a metadata wrapper to each paged response, including the current page number.                                        |
+| [`PaginatedData`](apimatic_core/pagination/paginated_data.py)                  | Provides methods to iterate over items and pages, fetch next pages using defined pagination strategies, and access the latest HTTP response and request builder. Supports independent iterators for concurrent traversals.                                                                      |
+
+
 ## Utilities
 | Name                                                               | Description                                                                                              |
 |--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|

apimatic_core/__init__.py

@@ -11,5 +11,6 @@
     'types',
     'logger',
     'exceptions',
-    'constants'
+    'constants',
+    'pagination'
 ]

apimatic_core/api_call.py

@@ -1,15 +1,28 @@
 from apimatic_core.configurations.endpoint_configuration import EndpointConfiguration
 from apimatic_core.configurations.global_configuration import GlobalConfiguration
 from apimatic_core.logger.sdk_logger import LoggerFactory
+from apimatic_core.pagination.paginated_data import PaginatedData
 from apimatic_core.response_handler import ResponseHandler
-
+import copy
 
 class ApiCall:
 
     @property
     def new_builder(self):
         return ApiCall(self._global_configuration)
 
+    @property
+    def request_builder(self):
+        return self._request_builder
+
+    @property
+    def get_pagination_strategies(self):
+        return self._pagination_strategies
+
+    @property
+    def global_configuration(self):
+        return self._global_configuration
+
     def __init__(
             self,
             global_configuration=GlobalConfiguration()
@@ -20,6 +33,7 @@ def __init__(
         self._endpoint_configuration = EndpointConfiguration()
         self._api_logger = LoggerFactory.get_api_logger(self._global_configuration.get_http_client_configuration()
                                                         .logging_configuration)
+        self._pagination_strategies = None
 
     def request(self, request_builder):
         self._request_builder = request_builder
@@ -29,6 +43,10 @@ def response(self, response_handler):
         self._response_handler = response_handler
         return self
 
+    def pagination_strategies(self, *pagination_strategies):
+        self._pagination_strategies = pagination_strategies
+        return self
+
     def endpoint_configuration(self, endpoint_configuration):
         self._endpoint_configuration = endpoint_configuration
         return self
@@ -62,3 +80,25 @@ def execute(self):
             _http_callback.on_after_response(_http_response)
 
         return self._response_handler.handle(_http_response, self._global_configuration.get_global_errors())
+
+
+    def paginate(self, page_iterable_creator, paginated_items_converter):
+        return page_iterable_creator(PaginatedData(self, paginated_items_converter))
+
+    def clone(self, global_configuration=None, request_builder=None, response_handler=None,
+              endpoint_configuration=None, pagination_strategies=None):
+        new_instance = copy.deepcopy(self)
+        new_instance._global_configuration = global_configuration or self._global_configuration
+        new_instance._request_builder = request_builder or self._request_builder
+        new_instance._response_handler = response_handler or self._response_handler
+        new_instance._endpoint_configuration = endpoint_configuration or self._endpoint_configuration
+        new_instance._pagination_strategies = pagination_strategies or self._pagination_strategies
+        return new_instance
+
+    def __deepcopy__(self, memodict={}):
+        copy_instance = ApiCall(self._global_configuration)
+        copy_instance._request_builder = copy.deepcopy(self._request_builder, memo=memodict)
+        copy_instance._response_handler = copy.deepcopy(self._response_handler, memo=memodict)
+        copy_instance._endpoint_configuration = copy.deepcopy(self._endpoint_configuration, memo=memodict)
+        copy_instance._pagination_strategies = copy.deepcopy(self._pagination_strategies, memo=memodict)
+        return copy_instance

apimatic_core/configurations/endpoint_configuration.py

@@ -1,25 +1,60 @@
-
 class EndpointConfiguration:
+    """Configuration for an API endpoint, including binary response handling,
+    retry behavior, and request builder management.
+    """
+
+    def __init__(self):
+        self._has_binary_response = None
+        self._to_retry = None
 
     @property
     def contains_binary_response(self):
+        """Indicates whether the response is expected to be binary."""
         return self._has_binary_response
 
     @property
     def should_retry(self):
+        """Indicates whether the request should be retried on failure."""
         return self._to_retry
 
-    def __init__(
-            self
-    ):
-        self._has_binary_response = None
-        self._to_retry = None
-
     def has_binary_response(self, has_binary_response):
+        """Sets whether the response should be treated as binary.
+
+        Args:
+            has_binary_response (bool): True if the response is binary.
+
+        Returns:
+            EndpointConfiguration: The current instance for chaining.
+        """
         self._has_binary_response = has_binary_response
         return self
 
     def to_retry(self, to_retry):
+        """Sets whether the request should be retried on failure.
+
+        Args:
+            to_retry (bool): True if retries should be attempted.
+
+        Returns:
+            EndpointConfiguration: The current instance for chaining.
+        """
         self._to_retry = to_retry
         return self
 
+    def __deepcopy__(self, memo={}):
+        if id(self) in memo:
+            return memo[id(self)]
+        copy_instance = EndpointConfiguration()
+        copy_instance._has_binary_response = self._has_binary_response
+        copy_instance._to_retry = self._to_retry
+        memo[id(self)] = copy_instance
+        return copy_instance
+
+    def clone_with(self, **kwargs):
+        clone_instance = self.__deepcopy__()
+        for key, value in kwargs.items():
+            if hasattr(clone_instance, key):
+                setattr(clone_instance, key, value)
+            else:
+                raise AttributeError(f"'EndpointConfiguration' object has no attribute '{key}'")
+        return clone_instance

apimatic_core/configurations/global_configuration.py

@@ -2,7 +2,7 @@
 
 from apimatic_core.http.configurations.http_client_configuration import HttpClientConfiguration
 from apimatic_core.utilities.api_helper import ApiHelper
-
+import copy
 
 class GlobalConfiguration:
 
@@ -72,3 +72,18 @@ def add_useragent_in_global_headers(self, user_agent, user_agent_parameters):
                 user_agent, user_agent_parameters).replace('  ', ' ')
         if user_agent:
             self._global_headers['user-agent'] = user_agent
+
+    def clone_with(self, http_client_configuration=None):
+        clone_instance = self.__deepcopy__()
+        clone_instance._http_client_configuration = http_client_configuration or self._http_client_configuration
+        return clone_instance
+
+    def __deepcopy__(self, memo={}):
+        copy_instance = GlobalConfiguration()
+        copy_instance._http_client_configuration = copy.deepcopy(self._http_client_configuration, memo)
+        copy_instance._global_errors = copy.deepcopy(self._global_errors, memo)
+        copy_instance._global_headers = copy.deepcopy(self._global_headers, memo)
+        copy_instance._additional_headers = copy.deepcopy(self._additional_headers, memo)
+        copy_instance._auth_managers = copy.deepcopy(self._auth_managers, memo)
+        copy_instance._base_uri_executor = copy.deepcopy(self._base_uri_executor, memo)
+        return copy_instance

apimatic_core/http/__init__.py

@@ -2,5 +2,6 @@
     'http_callback',
     'configurations',
     'request',
-    'response'
+    'response',
+    'http_call_context'
 ]

apimatic_core/http/configurations/http_client_configuration.py

@@ -1,6 +1,6 @@
-# -*- coding: utf-8 -*-
-from apimatic_core.factories.http_response_factory import HttpResponseFactory
 
+from apimatic_core.factories.http_response_factory import HttpResponseFactory
+import copy
 
 class HttpClientConfiguration(object):  # pragma: no cover
     """A class used for configuring the SDK by a user.
@@ -95,3 +95,14 @@ def __init__(self, http_client_instance=None,
 
     def set_http_client(self, http_client):
         self._http_client = http_client
+
+    def clone(self, http_callback=None):
+        http_client_instance = HttpClientConfiguration(
+            http_client_instance=self.http_client_instance,
+            override_http_client_configuration=self.override_http_client_configuration,
+            http_call_back=http_callback or self.http_callback,
+            timeout=self.timeout, max_retries=self.max_retries, backoff_factor=self.backoff_factor,
+            retry_statuses=self.retry_statuses, retry_methods=self.retry_methods,
+            logging_configuration=self.logging_configuration)
+        http_client_instance.set_http_client(self.http_client)
+        return http_client_instance

apimatic_core/http/http_call_context.py

@@ -0,0 +1,41 @@
+from apimatic_core.http.http_callback import HttpCallBack
+
+
+class HttpCallContext(HttpCallBack):
+
+    @property
+    def request(self):
+        return self._request
+
+    @property
+    def response(self):
+        return self._response
+
+    def __init__(self):
+        self._request = None
+        self._response = None
+
+    """An interface for  the callback to be called before and after the
+    HTTP call for an endpoint is made.
+
+    This class should not be instantiated but should be used as a base class
+    for HttpCallBack classes.
+
+    """
+
+    def on_before_request(self, request):  # pragma: no cover
+        """The controller will call this method before making the HttpRequest.
+
+        Args:
+            request (HttpRequest): The request object which will be sent
+                to the HttpClient to be executed.
+        """
+        self._request = request
+
+    def on_after_response(self, response):  # pragma: no cover
+        """The controller will call this method after making the HttpRequest.
+
+        Args:
+            response (HttpResponse): The HttpResponse of the API call.
+        """
+        self._response = response