api_core: Make PageIterator.item_to_value public. (#4702)

2 files changed, 22 insertions, 9 deletions

diff --git a/google/api_core/page_iterator.py b/google/api_core/page_iterator.py
index 3d2a55b..0cf03a6 100644
--- a/google/api_core/page_iterator.py
+++ b/google/api_core/page_iterator.py
@@ -158,12 +158,25 @@ class Iterator(object):
                  page_token=None, max_results=None):
         self._started = False
         self.client = client
-        self._item_to_value = item_to_value
+        """Optional[Any]: The client that created this iterator."""
+        self.item_to_value = item_to_value
+        """Callable[Iterator, Any]: 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.
+        """
         self.max_results = max_results
+        """int: The maximum number of results to fetch."""
+
         # The attributes below will change over the life of the iterator.
         self.page_number = 0
+        """int: The current page of results."""
         self.next_page_token = page_token
+        """str: The token for the next page of results. If this is set before
+            the iterator starts, it effectively offsets the iterator to a
+            specific starting point."""
         self.num_results = 0
+        """int: The total number of results fetched so far."""
 
     @property
     def pages(self):
@@ -335,7 +348,7 @@ class HTTPIterator(Iterator):
         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)
             self._page_start(self, page, response)
             self.next_page_token = response.get(self._next_token)
             return page
@@ -428,7 +441,7 @@ class _GAXIterator(Iterator):
         """
         try:
             items = six.next(self._gax_page_iter)
-            page = Page(self, items, self._item_to_value)
+            page = Page(self, items, self.item_to_value)
             self.next_page_token = self._gax_page_iter.page_token or None
             return page
         except StopIteration:
@@ -500,7 +513,7 @@ class GRPCIterator(Iterator):
 
         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)
 
         return page
 
diff --git a/tests/unit/test_page_iterator.py b/tests/unit/test_page_iterator.py
index 5defb76..172be03 100644
--- a/tests/unit/test_page_iterator.py
+++ b/tests/unit/test_page_iterator.py
@@ -88,7 +88,7 @@ class TestIterator(object):
 
         assert not iterator._started
         assert iterator.client is client
-        assert iterator._item_to_value == item_to_value
+        assert iterator.item_to_value == item_to_value
         assert iterator.max_results == max_results
         # Changing attributes.
         assert iterator.page_number == 0
@@ -214,7 +214,7 @@ class TestHTTPIterator(object):
         assert not iterator._started
         assert iterator.client is client
         assert iterator.path == path
-        assert iterator._item_to_value is mock.sentinel.item_to_value
+        assert iterator.item_to_value is mock.sentinel.item_to_value
         assert iterator._items_key == 'items'
         assert iterator.max_results is None
         assert iterator.extra_params == {}
@@ -419,10 +419,10 @@ class TestGRPCIterator(object):
         assert not iterator._started
         assert iterator.client is client
         assert iterator.max_results is None
+        assert iterator.item_to_value is page_iterator._item_to_value_identity
         assert iterator._method == mock.sentinel.method
         assert iterator._request == mock.sentinel.request
         assert iterator._items_field == items_field
-        assert iterator._item_to_value is page_iterator._item_to_value_identity
         assert (iterator._request_token_field ==
                 page_iterator.GRPCIterator._DEFAULT_REQUEST_TOKEN_FIELD)
         assert (iterator._response_token_field ==
@@ -446,10 +446,10 @@ class TestGRPCIterator(object):
 
         assert iterator.client is client
         assert iterator.max_results == 42
+        assert iterator.item_to_value is mock.sentinel.item_to_value
         assert iterator._method == mock.sentinel.method
         assert iterator._request == mock.sentinel.request
         assert iterator._items_field == items_field
-        assert iterator._item_to_value is mock.sentinel.item_to_value
         assert iterator._request_token_field == request_field
         assert iterator._response_token_field == response_field
 
@@ -517,7 +517,7 @@ class TestGAXIterator(object):
 
         assert not iterator._started
         assert iterator.client is client
-        assert iterator._item_to_value is item_to_value
+        assert iterator.item_to_value is item_to_value
         assert iterator.max_results == max_results
         assert iterator._gax_page_iter is page_iter
         # Changing attributes.