OKTA-672843 Add optional parameter to api_response.next() to include …

…response object as a third tuple value. (#379)

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

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

okta/__init__.py

@@ -1 +1 @@
-__version__ = '2.9.3'
+__version__ = '2.9.4'

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,17 +134,23 @@ 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:
             result = []
             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,19 +168,19 @@ 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
                 next_response = OktaAPIResponse(
                     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)