feat(api_core): provide a 'raw_page' field for page_iterator.Page

api_core/.coveragerc

@@ -11,3 +11,5 @@ exclude_lines =
     def __repr__
     # Ignore abstract methods
     raise NotImplementedError
+    # Ignore assert False, meant to prevent false positive tests
+    assert False

api_core/google/api_core/page_iterator.py

@@ -96,14 +96,22 @@ class Page(object):
             Callable to convert an item from the type in the raw API response
             into the native object. Will be called with the iterator and a
             single item.
+        raw_page Optional[google.protobuf.message.Message]:
+            The raw page response.
     """
 
-    def __init__(self, parent, items, item_to_value):
+    def __init__(self, parent, items, item_to_value, raw_page):
         self._parent = parent
         self._num_items = len(items)
         self._remaining = self._num_items
         self._item_iter = iter(items)
         self._item_to_value = item_to_value
+        self._raw_page = raw_page
+
+    @property
+    def raw_page(self):
+        """google.protobuf.message.Message"""
+        return self._raw_page
 
     @property
     def num_items(self):
@@ -360,7 +368,7 @@ def _next_page(self):
         if self._has_next_page():
             response = self._get_next_page_response()
             items = response.get(self._items_key, ())
-            page = Page(self, items, self.item_to_value)
+            page = Page(self, items, self.item_to_value, response)
             self._page_start(self, page, response)
             self.next_page_token = response.get(self._next_token)
             return page
@@ -454,7 +462,7 @@ def _next_page(self):
         """
         try:
             items = six.next(self._gax_page_iter)
-            page = Page(self, items, self.item_to_value)
+            page = Page(self, items, self.item_to_value, None)
             self.next_page_token = self._gax_page_iter.page_token or None
             return page
         except StopIteration:
@@ -527,7 +535,7 @@ def _next_page(self):
 
         self.next_page_token = getattr(response, self._response_token_field)
         items = getattr(response, self._items_field)
-        page = Page(self, items, self.item_to_value)
+        page = Page(self, items, self.item_to_value, response)
 
         return page
 

api_core/tests/unit/test_page_iterator.py

@@ -30,15 +30,15 @@ def test_constructor(self):
         parent = mock.sentinel.parent
         item_to_value = mock.sentinel.item_to_value
 
-        page = page_iterator.Page(parent, (1, 2, 3), item_to_value)
+        page = page_iterator.Page(parent, (1, 2, 3), item_to_value, None)
 
         assert page.num_items == 3
         assert page.remaining == 3
         assert page._parent is parent
         assert page._item_to_value is item_to_value
 
     def test___iter__(self):
-        page = page_iterator.Page(None, (), None)
+        page = page_iterator.Page(None, (), None, None)
         assert iter(page) is page
 
     def test_iterator_calls_parent_item_to_value(self):
@@ -48,7 +48,7 @@ def test_iterator_calls_parent_item_to_value(self):
             side_effect=lambda iterator, value: value, spec=["__call__"]
         )
 
-        page = page_iterator.Page(parent, (10, 11, 12), item_to_value)
+        page = page_iterator.Page(parent, (10, 11, 12), item_to_value, None)
         page._remaining = 100
 
         assert item_to_value.call_count == 0
@@ -69,6 +69,22 @@ def test_iterator_calls_parent_item_to_value(self):
         item_to_value.assert_called_with(parent, 12)
         assert page.remaining == 97
 
+    def test_raw_page(self):
+        parent = mock.sentinel.parent
+        item_to_value = mock.sentinel.item_to_value
+
+        raw_page = mock.sentinel.raw_page
+
+        page = page_iterator.Page(parent, (1, 2, 3), item_to_value, raw_page)
+        assert page.raw_page is raw_page
+
+        try:
+            page.raw_page = None
+        except AttributeError:
+            pass
+        else:
+            assert False, "The raw_page attribute should be a read-only property"
+
 
 class PageIteratorImpl(page_iterator.Iterator):
     def _next_page(self):
@@ -116,7 +132,7 @@ def test_pages_property_restart(self):
     def test__page_iter_increment(self):
         iterator = PageIteratorImpl(None, None)
         page = page_iterator.Page(
-            iterator, ("item",), page_iterator._item_to_value_identity
+            iterator, ("item",), page_iterator._item_to_value_identity, None
         )
         iterator._next_page = mock.Mock(side_effect=[page, None])
 
@@ -147,10 +163,10 @@ def test__items_iter(self):
         # Make pages from mock responses
         parent = mock.sentinel.parent
         page1 = page_iterator.Page(
-            parent, (item1, item2), page_iterator._item_to_value_identity
+            parent, (item1, item2), page_iterator._item_to_value_identity, None
         )
         page2 = page_iterator.Page(
-            parent, (item3,), page_iterator._item_to_value_identity
+            parent, (item3,), page_iterator._item_to_value_identity, None
         )
 
         iterator = PageIteratorImpl(None, None)