From 700c5f11bc30f661ee945ce5d2c7a4c044e49288 Mon Sep 17 00:00:00 2001
From: Bryan Apellanes <63638027+bryanapellanes-okta@users.noreply.github.com>
Date: Wed, 13 Dec 2023 07:33:16 -0600
Subject: [PATCH] OKTA-672843 Add optional parameter to api_response.next() to
 include response object as a third tuple value.  (#379)

---
 CHANGELOG.md         |  3 +++
 README.md            | 21 +++++++++++++++++++++
 okta/__init__.py     |  2 +-
 okta/api_response.py | 20 +++++++++++++-------
 4 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 659f365b..22775864 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
 # Okta Python SDK Changelog
 
+## 2.9.4
+* Add optional parameter to api_response.next() to include response object as a third tuple value. 
+
 ## 2.9.3
 * Add missing properties to applicationsettingsapplication per the reference docs: https://developer.okta.com/docs/reference/api/apps/#settings-4
 * Add signed_nonce factor type per the reference docs: https://developer.okta.com/docs/reference/api/factors/#factor-type
diff --git a/README.md b/README.md
index 080086ce..65665a43 100644
--- a/README.md
+++ b/README.md
@@ -923,6 +923,27 @@ loop = asyncio.get_event_loop()
 loop.run_until_complete(main())
 ```
 
+If you require access to the response headers during a pagination operation, set the `includeResponse` parameter to `True` in the call to the `next` method; this returns the response as a third tuple value.  See the following example:
+
+```python
+from okta.client import Client as OktaClient
+import asyncio
+
+async def main():
+    client = OktaClient()
+    users, resp, err = await client.list_users()
+    while True:
+        for user in users:
+            print(user.profile.login) 
+        if resp.has_next():
+            users, err, response = await resp.next(True) # Specify True to receive the response object as the third part of the tuple for further analysis
+        else:
+            break
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(main())
+```
+
 ## Logging
 
 > Feature appears in version 1.5.0
diff --git a/okta/__init__.py b/okta/__init__.py
index 4ef1be1f..c3f8be5b 100644
--- a/okta/__init__.py
+++ b/okta/__init__.py
@@ -1 +1 @@
-__version__ = '2.9.3'
+__version__ = '2.9.4'
diff --git a/okta/api_response.py b/okta/api_response.py
index 387f6ed8..e441794b 100644
--- a/okta/api_response.py
+++ b/okta/api_response.py
@@ -123,7 +123,7 @@ def has_next(self):
         """
         return self._next is not None
 
-    async def next(self):
+    async def next(self, includeResponse=False):
         """
         Generator iterating function. Retrieves the next page of results
         from the API.
@@ -134,7 +134,7 @@ async def next(self):
         # if not self.has_next():
         #     return (None, None)  #This causes errors with our async testing
         MODELS_NOT_TO_CAMEL_CASE = [User, Group, UserSchema, GroupSchema]
-        next_page, error = await self.get_next().__anext__()
+        next_page, error, next_response = await self.get_next().__anext__()
         if error:
             return (None, error)
         if self._type is not None:
@@ -142,9 +142,15 @@ async def next(self):
             for item in next_page:
                 result.append(self._type(item) if self._type in MODELS_NOT_TO_CAMEL_CASE
                               else self._type(APIClient.form_response_body(item)))
-            return (result, None)
+            if includeResponse:
+                return (result, None, next_response)
+            else:
+                return (result, None)
 
-        return (next_page, error)
+        if includeResponse:
+            return (next_page, error, next_response)
+        else:
+            return (next_page, error)
 
     async def get_next(self):
         """
@@ -162,14 +168,14 @@ async def get_next(self):
             if error:
                 # Return None if error and set next to none
                 self._next = None
-                yield (None, error)
+                yield (None, error, None)
 
             req, res_details, resp_body, error = await \
                 self._request_executor.fire_request(next_request)
             if error:
                 # Return None if error and set next to none
                 self._next = None
-                yield (None, error)
+                yield (None, error, None)
 
             if next_request:
                 # create new response and update generator values
@@ -177,4 +183,4 @@ async def get_next(self):
                     self._request_executor, req, res_details, resp_body)
                 self._next = next_response._next
                 # yield next page
-                yield (next_response.get_body(), None)
+                yield (next_response.get_body(), None, next_response)