refactors the code based from doc blocks perspective

Author: sufyankhanrao

apimatic_core/pagination/configuration/cursor_pagination.py

@@ -3,8 +3,29 @@
 
 
 class CursorPagination(PaginationStrategy):
+    """
+    Implements a cursor-based pagination strategy for API responses.
+
+    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.
+    """
 
     def __init__(self, output, input_, metadata_wrapper):
+        """
+        Initializes a CursorPagination instance with the specified output and input pointers and a metadata wrapper.
+
+        Validates that both input and output pointers are provided,
+         and sets up internal state for cursor-based pagination.
+
+        Args:
+            output: JSON pointer to extract the cursor from the API response.
+            input_: JSON pointer indicating where to set the cursor in the request.
+            metadata_wrapper: Function to wrap paged responses with additional metadata.
+
+        Raises:
+            ValueError: If either input_ or output is None.
+        """
         super().__init__(metadata_wrapper)
 
         if input_ is None:
@@ -17,6 +38,19 @@ def __init__(self, output, input_, metadata_wrapper):
         self._cursor_value = None
 
     def apply(self, paginated_data):
+        """
+        Advances the pagination by updating the request builder with the next cursor value.
+
+        If there is no previous response, initializes the cursor from the request builder.
+        Otherwise, extracts the cursor from the last response using the configured output pointer,
+        and updates the request builder for the next page. Returns None if no further pages are available.
+
+        Args:
+            paginated_data: An object containing the last response and the current request builder.
+
+        Returns:
+            A new request builder for the next page, or None if pagination is complete.
+        """
         last_response = paginated_data.last_response
         request_builder = paginated_data.request_builder
 
@@ -36,10 +70,29 @@ def apply(self, paginated_data):
         return self.get_updated_request_builder(request_builder, self._input, self._cursor_value)
 
     def apply_metadata_wrapper(self, paged_response):
+        """
+        Applies the configured metadata wrapper to the paged response, including the current cursor value.
+
+        Args:
+            paged_response: The response object from the current page.
+
+        Returns:
+            The result of the metadata wrapper applied to the paged response and cursor value.
+        """
         return self._metadata_wrapper(paged_response, self._cursor_value)
 
     @staticmethod
     def _get_initial_cursor_value(request_builder, input_pointer):
+        """
+        Retrieves the initial cursor value from the request builder using the specified input pointer.
+
+        Args:
+            request_builder: The request builder containing request parameters.
+            input_pointer (str): The JSON pointer indicating the location of the cursor value.
+
+        Returns:
+            The initial cursor value if found, otherwise None.
+        """
         path_prefix, field_path = ApiHelper.split_into_parts(input_pointer)
 
         if path_prefix == "$request.path":

apimatic_core/pagination/configuration/link_pagination.py

@@ -4,9 +4,24 @@
 
 
 class LinkPagination(PaginationStrategy):
-    """Pagination manager implementation for link-based pagination."""
+    """
+    Implements a pagination strategy that extracts the next page link from API responses using a JSON pointer.
+
+    This class updates the request builder with query parameters from the next page link and applies a metadata
+     wrapper to the paged response.
+    """
 
     def __init__(self, next_link_pointer, metadata_wrapper):
+        """
+        Initializes a LinkPagination instance with the given next link pointer and metadata wrapper.
+
+        Args:
+            next_link_pointer: JSON pointer to extract the next page link from the API response.
+            metadata_wrapper: Callable to wrap the paged response metadata.
+
+        Raises:
+            ValueError: If next_link_pointer is None.
+        """
         super().__init__(metadata_wrapper)
 
         if next_link_pointer is None:
@@ -16,6 +31,17 @@ def __init__(self, next_link_pointer, metadata_wrapper):
         self._next_link = None
 
     def apply(self, paginated_data):
+        """
+        Updates the request builder with query parameters from the next page
+         link extracted from the last API response.
+
+        Args:
+            paginated_data: An object containing the last API response and the current request builder.
+
+        Returns:
+            A new request builder instance with updated query parameters for the next page,
+             or None if no next link is found.
+        """
         last_response = paginated_data.last_response
         request_builder = paginated_data.request_builder
 
@@ -40,4 +66,13 @@ def apply(self, paginated_data):
         )
 
     def apply_metadata_wrapper(self, paged_response):
+        """
+        Applies the metadata wrapper to the paged response, including the next page link.
+
+        Args:
+            paged_response: The API response object for the current page.
+
+        Returns:
+            The result of the metadata wrapper, typically containing the response and next link information.
+        """
         return self._metadata_wrapper(paged_response, self._next_link)

apimatic_core/pagination/configuration/offset_pagination.py

@@ -4,14 +4,24 @@
 
 
 class OffsetPagination(PaginationStrategy):
-    """Pagination manager implementation for offset-based pagination."""
+    """
+    Implements offset-based pagination strategy for API responses.
+
+    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.
+    """
 
     def __init__(self, input_, metadata_wrapper):
         """
-        Initializes a new instance of the OffsetPagination class.
+        Initializes an OffsetPagination instance with the given input pointer and metadata wrapper.
 
         Args:
-            input_ (str): JSON pointer to the request field representing the offset.
+            input_: JSON pointer indicating the pagination parameter to update.
+            metadata_wrapper: Callable for handling pagination metadata.
+
+        Raises:
+            ValueError: If input_ is None.
         """
         super().__init__(metadata_wrapper)
 
@@ -22,6 +32,18 @@ def __init__(self, input_, metadata_wrapper):
         self._offset = 0
 
     def apply(self, paginated_data):
+        """
+        Updates the request builder to fetch the next page of results using offset-based pagination.
+
+        If this is the first page, initializes the offset from the request builder. Otherwise,
+         increments the offset by the previous page size and updates the pagination parameter.
+
+        Args:
+            paginated_data: The PaginatedData instance containing the last response, request builder, and page size.
+
+        Returns:
+            An updated request builder configured for the next page request.
+        """
         last_response = paginated_data.last_response
         request_builder = paginated_data.request_builder
         last_page_size = paginated_data.page_size
@@ -35,9 +57,28 @@ def apply(self, paginated_data):
         return self.get_updated_request_builder(request_builder, self._input, self._offset)
 
     def apply_metadata_wrapper(self, page_response):
+        """
+        Applies the metadata wrapper to the given page response, passing the current offset.
+
+        Args:
+            page_response: The response object for the current page.
+
+        Returns:
+            The result of the metadata wrapper callable with the page response and offset.
+        """
         return self._metadata_wrapper(page_response, self._offset)
 
     def _get_initial_offset(self, request_builder):
+        """
+        Determines the initial offset value for pagination by extracting it from the request builder
+        based on the configured JSON pointer input.
+
+        Args:
+            request_builder: The request builder containing path, query, and header parameters.
+
+        Returns:
+            int: The initial offset value extracted from the appropriate request parameter, or 0 if not found.
+        """
         path_prefix, field_path = ApiHelper.split_into_parts(self._input)
 
         if path_prefix == "$request.path":

apimatic_core/pagination/configuration/page_pagination.py

@@ -2,8 +2,25 @@
 from apimatic_core.utilities.api_helper import ApiHelper
 
 class PagePagination(PaginationStrategy):
+    """
+    Implements a page-based pagination strategy for API requests.
+
+    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.
+    """
 
     def __init__(self, input_, metadata_wrapper):
+        """
+        Initializes a PagePagination instance with the given input pointer and metadata wrapper.
+
+        Args:
+            input_: The JSON pointer indicating the pagination parameter in the request.
+            metadata_wrapper: A callable for wrapping pagination metadata.
+
+        Raises:
+            ValueError: If input_ is None.
+        """
         super().__init__(metadata_wrapper)
 
         if input_ is None:
@@ -13,6 +30,15 @@ def __init__(self, input_, metadata_wrapper):
         self._page_number = 1
 
     def apply(self, paginated_data):
+        """
+        Updates the request builder to fetch the next page of results based on the current paginated data.
+
+        Args:
+            paginated_data: An object containing the last response, request builder, and page size.
+
+        Returns:
+            The updated request builder configured for the next page request.
+        """
         last_response = paginated_data.last_response
         request_builder = paginated_data.request_builder
         last_page_size = paginated_data.page_size
@@ -25,9 +51,28 @@ def apply(self, paginated_data):
         return self.get_updated_request_builder(request_builder, self._input, self._page_number)
 
     def apply_metadata_wrapper(self, paged_response):
+        """
+        Applies the metadata wrapper to the paged response, including the current page number.
+
+        Args:
+            paged_response: The response object for the current page.
+
+        Returns:
+            The result of the metadata wrapper with the paged response and current page number.
+        """
         return self._metadata_wrapper(paged_response, self._page_number)
 
     def _get_initial_page_offset(self, request_builder):
+        """
+        Determines the initial page offset for pagination by extracting the value from the request builder
+        based on the configured JSON pointer. Returns 1 if the value is missing or invalid.
+
+        Args:
+            request_builder: The request builder containing path, query, and header parameters.
+
+        Returns:
+            int: The initial page offset value.
+        """
         path_prefix, field_path = ApiHelper.split_into_parts(self._input)
 
         try:

apimatic_core/pagination/paginated_data.py

@@ -3,24 +3,49 @@
 import copy
 
 class PaginatedData(Iterator):
+    """
+    Iterator class for handling paginated API responses.
+
+    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.
+    """
 
     @property
     def last_response(self):
+        """
+        Returns the most recent HTTP response received during pagination.
+        """
         return self._http_call_context.response
 
     @property
     def request_builder(self):
+        """
+        Returns the appropriate request builder for the current pagination state.
+        """
         if self.last_response is None:
             return self._initial_request_builder
 
         return self._api_call.request_builder
 
     @property
     def page_size(self):
+        """
+        Returns the number of items in the current page of paginated results.
+        """
         return self._page_size
 
     def __init__(self, api_call, paginated_items_converter):
+        """
+        Initializes a PaginatedData instance with the given API call and item converter.
+
+        Deep copies the API call, sets up pagination strategies, HTTP call context, and global configuration.
+        Raises:
+            ValueError: If paginated_items_converter is None.
 
+        Args:
+            api_call: The API call object to paginate.
+            paginated_items_converter: Function to convert paginated response bodies into items.
+        """
         if paginated_items_converter is None:
             raise ValueError('paginated_items_converter cannot be None')
 
@@ -40,9 +65,17 @@ def __init__(self, api_call, paginated_items_converter):
         self._current_index = 0
 
     def __iter__(self):
+        """
+        Returns a new independent iterator instance for paginated data traversal.
+        """
         return self._get_new_self_instance()
 
     def __next__(self):
+        """
+        Returns the next item in the paginated data sequence.
+
+        Fetches the next page if the current page is exhausted. Raises StopIteration when no more items are available.
+        """
         if self._current_index < self.page_size:
             item = self._items[self._current_index]
             self._current_index += 1
@@ -59,7 +92,10 @@ def __next__(self):
 
     def pages(self):
         """
-        Generator to iterate over pages instead of items.
+        Yields each page of the paginated response as an independent generator.
+
+        Returns:
+            Generator yielding HTTP response objects for each page.
         """
         # Create a new instance so the page iteration is independent
         paginated_data = self._get_new_self_instance()
@@ -73,6 +109,19 @@ def pages(self):
             yield paginated_data._paged_response
 
     def _fetch_next_page(self):
+        """
+        Fetches the next page of paginated data using available pagination strategies.
+
+        Attempts each strategy to build the next request, executes the API call,
+         and applies any response metadata wrappers.
+        Returns an empty list if no further pages are available.
+
+        Returns:
+            The processed response object for the next page, or an empty list if pagination is complete.
+
+        Raises:
+            Exception: Propagates any exceptions encountered during the API call execution.
+        """
         for pagination_strategy in self._pagination_strategies:
             request_builder = pagination_strategy.apply(self)
             if request_builder is None:
@@ -87,6 +136,13 @@ def _fetch_next_page(self):
         return []
 
     def _get_new_self_instance(self):
+        """
+        Creates and returns a new independent PaginatedData instance with the initial
+         request builder and item converter.
+
+        Returns:
+            PaginatedData: A fresh iterator instance for independent pagination traversal.
+        """
         return PaginatedData(
             self._api_call.clone(request_builder=self._initial_request_builder),
             self._paginated_items_converter