Implementing basic Page class to help with Iterator.

dhermes · dhermes · commit 663671469871 · 2016-10-12T01:05:41.000-07:00
Intended to hold and slice up state that has already been
retrieved from the server.
diff --git a/core/google/cloud/iterator.py b/core/google/cloud/iterator.py
@@ -39,15 +39,70 @@ def get_items_from_response(self, response):
 requests)::
 
     >>> for item in MyIterator(...):
-    >>>     print(item.name)
-    >>>     if not item.is_valid:
-    >>>         break
+    ...     print(item.name)
+    ...     if not item.is_valid:
+    ...         break
 """
 
 
 import six
 
 
+class Page(object):
+    """Single page of results in an iterator.
+
+    :type parent: :class:`Iterator`
+    :param parent: The iterator that owns the current page.
+    """
+
+    def __init__(self, parent):
+        self._parent = parent
+        self._num_items = 0
+        self._remaining = 0
+
+    @property
+    def num_items(self):
+        """Total items in the page.
+
+        :rtype: int
+        :returns: The number of items in this page of items.
+        """
+        return self._num_items
+
+    @property
+    def remaining(self):
+        """Remaining items in the page.
+
+        :rtype: int
+        :returns: The number of items remaining this page.
+        """
+        return self._remaining
+
+    def __iter__(self):
+        """The :class:`Page` is an iterator."""
+        return self
+
+    def _next_item(self):
+        """Get the next item in the page.
+
+        This method (along with the constructor) is the workhorse
+        of this class. Subclasses will need to implement this method.
+
+        It is separate from :meth:`next` since that method needs
+        to be aliased as ``__next__`` in Python 3.
+
+        :raises NotImplementedError: Always
+        """
+        raise NotImplementedError
+
+    def next(self):
+        """Get the next value in the iterator."""
+        return self._next_item()
+
+    # Alias needed for Python 2/3 support.
+    __next__ = next
+
+
 class Iterator(object):
     """A generic class for iterating through Cloud JSON APIs list responses.
 
diff --git a/core/unit_tests/test_iterator.py b/core/unit_tests/test_iterator.py
@@ -15,6 +15,69 @@
 import unittest
 
 
+class TestPage(unittest.TestCase):
+
+    def _getTargetClass(self):
+        from google.cloud.iterator import Page
+        return Page
+
+    def _makeOne(self, *args, **kw):
+        return self._getTargetClass()(*args, **kw)
+
+    def test_constructor(self):
+        parent = object()
+        page = self._makeOne(parent)
+        self.assertIs(page._parent, parent)
+        self.assertEqual(page._num_items, 0)
+        self.assertEqual(page._remaining, 0)
+
+    def test_num_items_property(self):
+        page = self._makeOne(None)
+        num_items = 42
+        page._num_items = num_items
+        self.assertEqual(page.num_items, num_items)
+
+    def test_remaining_property(self):
+        page = self._makeOne(None)
+        remaining = 1337
+        page._remaining = remaining
+        self.assertEqual(page.remaining, remaining)
+
+    def test___iter__(self):
+        page = self._makeOne(None)
+        self.assertIs(iter(page), page)
+
+    def test__next_item_virtual(self):
+        page = self._makeOne(None)
+        with self.assertRaises(NotImplementedError):
+            page._next_item()
+
+    def test_iterator_calls__next_item(self):
+        import six
+
+        klass = self._getTargetClass()
+
+        class CountItPage(klass):
+
+            calls = 0
+            values = None
+
+            def _next_item(self):
+                self.calls += 1
+                return self.values.pop(0)
+
+        page = CountItPage(None)
+        page.values = [10, 11, 12]
+
+        self.assertEqual(page.calls, 0)
+        self.assertEqual(six.next(page), 10)
+        self.assertEqual(page.calls, 1)
+        self.assertEqual(six.next(page), 11)
+        self.assertEqual(page.calls, 2)
+        self.assertEqual(six.next(page), 12)
+        self.assertEqual(page.calls, 3)
+
+
 class TestIterator(unittest.TestCase):
 
     def _getTargetClass(self):
diff --git a/docs/google-cloud-api.rst b/docs/google-cloud-api.rst
@@ -36,3 +36,10 @@ Environment Variables
 .. automodule:: google.cloud.environment_vars
   :members:
   :show-inheritance:
+
+Base Iterator Class
+~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.iterator
+  :members:
+  :show-inheritance:
diff --git a/scripts/verify_included_modules.py b/scripts/verify_included_modules.py
@@ -36,7 +36,6 @@
     'google.cloud.datastore.__init__',
     'google.cloud.dns.__init__',
     'google.cloud.error_reporting.__init__',
-    'google.cloud.iterator',
     'google.cloud.language.__init__',
     'google.cloud.logging.__init__',
     'google.cloud.logging.handlers.__init__',
