Add a container class and function descriptor to wrap generator functions

Create a generator container and  descriptor function to wrap the
generator functions in the API package.

Containerizing the generator functions makes the generators safe for
reuse.  A fresh iterator is returned every time a new iterator is
requested from the container.

Author: cmlccie

ciscosparkapi/api/rooms.py

@@ -9,7 +9,7 @@
 
 
 from ciscosparkapi.exceptions import ciscosparkapiException
-from ciscosparkapi.helperfunc import utf8
+from ciscosparkapi.helper import utf8, generator_container
 from ciscosparkapi.restsession import RestSession
 from ciscosparkapi.sparkdata import SparkData
 
@@ -92,16 +92,20 @@ def __init__(self, session):
         super(RoomsAPI, self).__init__()
         self.session = session
 
+    @generator_container
     def list(self, max=None, **query_params):
         """List rooms.
 
         By default, lists rooms to which the authenticated user belongs.
 
         This method supports Cisco Spark's implmentation of RFC5988 Web Linking
-        to provide pagination support.  It returns an iterator that
-        incrementally yield all rooms returned by the query.  It will
-        automatically request additional 'pages' of responses from Spark as
-        needed until all responses have been returned.
+        to provide pagination support.  It returns a generator container that
+        incrementally yield all rooms returned by the query.  The generator
+        will automatically request additional 'pages' of responses from Spark
+        as needed until all responses have been returned.  The container makes
+        the generator safe for reuse.  A new API call will be made, using the
+        same parameters that were specified when the generator was created,
+        every time a new iterator is requested from the container.
 
         Args:
             max(int): Limits the maximum number of rooms returned from the

ciscosparkapi/helper.py

@@ -1,10 +1,96 @@
-"""Package helper functions."""
+"""Package helper functions and classes.
+
+Functions:
+    utf8: Returns the input string as a UTF-8 unicode encoded string.
+    generator_container: Function decorator that containerizes calls to
+        generator functions.
+
+Classes:
+    GeneratorContainer: Container for storing a function call to a generator
+        function.
+
+"""
+
+
+import functools
 
 
 def utf8(string):
-    """Return the 'string' as a UTF-8 unicode encoded string."""
+    """Return the 'string' as a UTF-8 unicode encoded string.
+
+    Ensure that 'string' is a unicode encoded string; converting if necessary.
+
+    Args:
+        string(unicode, str): The input string.
+
+    Returns:
+        unicode: The input string encoded as a unicode string.
+
+    Raises:
+        AssertionError: If the parameter types are incorrect.
+
+    """
     assert isinstance(string, basestring)
     if isinstance(string, unicode):
         return string
     elif isinstance(string, str):
         return unicode(string, encoding='utf-8')
+
+
+class GeneratorContainer(object):
+    """Container for storing a function call to a generator function.
+
+    Return a fresh iterator every time __iter__() is called on the container
+    object.
+
+    Attributes:
+        generator(func): The generator function.
+        args(list): The arguments passed to the generator function.
+        kwargs(dict): The keyword arguments passed to the generator function.
+
+    """
+
+    def __init__(self, generator, *args, **kwargs):
+        """Inits a new GeneratorContainer.
+
+        Args:
+            generator(func): The generator function.
+            *args: The arguments passed to the generator function.
+            **kwargs: The keyword arguments passed to the generator function.
+
+        """
+        self.generator = generator
+        self.args = args
+        self.kwargs = kwargs
+
+    def __iter__(self):
+        """Return a fresh iterator."""
+        return self.generator(*self.args, **self.kwargs)
+
+
+def generator_container(generator):
+    """Function Decorator: Containerize calls to a generator function.
+
+    Args:
+        generator(func): The generator function being containerized.
+
+    Returns:
+        func: A wrapper function that containerizes the calls to the generator.
+
+    """
+
+    @functools.wraps(generator)
+    def generator_container_wrapper(*args, **kwargs):
+        """Store a generator call in a container and return the container.
+
+        Args:
+            *args: The arguments passed to the generator function.
+            **kwargs: The keyword arguments passed to the generator function.
+
+        Returns:
+            GeneratorContainer: A container wrapping the call to the generator.
+
+        """
+        return GeneratorContainer(generator, *args, **kwargs)
+
+    return generator_container_wrapper