improved test docs

Author: daniel-sanche

google/api_core/retry_async.py

@@ -240,7 +240,7 @@ async def retry_wrapped_func(*args, **kwargs):
             )
 
         @functools.wraps(func)
-        def retry_wrapped_stream(*args, deadline_dt=None, **kwargs):
+        def retry_wrapped_stream(*args, **kwargs):
             """A wrapper that iterates over target stream with retry."""
             target = functools.partial(func, *args, **kwargs)
             sleep_generator = exponential_sleep_generator(

tests/asyncio/test_retry_async.py

@@ -428,6 +428,10 @@ async def _generator_mock(
         sleep_time=0,
         ignore_sent=False,
     ):
+        """
+        Helper to create a mock generator that yields a number of values
+        Generator can optionally raise an exception on a specific iteration
+        """
         try:
             sent_in = None
             for i in range(num):
@@ -447,6 +451,10 @@ async def _generator_mock(
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___generator_success(self, sleep):
+        """
+        Test that a retry-decorated generator yields values as expected
+        This test checks a generator with no issues
+        """
         from collections.abc import AsyncGenerator
 
         retry_ = retry_async.AsyncRetry(is_stream=True)
@@ -469,6 +477,9 @@ async def test___call___generator_success(self, sleep):
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___generator_retry(self, sleep):
+        """
+        Tests that a retry-decorated generator will retry on errors
+        """
         on_error = mock.Mock(return_value=None)
         retry_ = retry_async.AsyncRetry(
             on_error=on_error,
@@ -487,6 +498,10 @@ async def test___call___generator_retry(self, sleep):
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___generator_retry_hitting_deadline(self, sleep, uniform):
+        """
+        Tests that a retry-decorated generator will throw a RetryError
+        after using the time budget
+        """
         on_error = mock.Mock()
         retry_ = retry_async.AsyncRetry(
             predicate=retry_async.if_exception_type(ValueError),
@@ -527,6 +542,10 @@ def increase_time(sleep_delay):
 
     @pytest.mark.asyncio
     async def test___call___generator_timeout_cancellations(self):
+        """
+        Tests that a retry-decorated generator will throw a RetryError
+        after using its time budget
+        """
         on_error = mock.Mock(return_value=None)
         retry_ = retry_async.AsyncRetry(
             predicate=retry_async.if_exception_type(ValueError),
@@ -617,6 +636,9 @@ async def test___call___with_generator_send(self, sleep):
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___generator_send_retry(self, sleep):
+        """
+        Send should be retried if target generator raises an error
+        """
         on_error = mock.Mock(return_value=None)
         retry_ = retry_async.AsyncRetry(
             on_error=on_error,
@@ -639,6 +661,9 @@ async def test___call___generator_send_retry(self, sleep):
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___with_generator_close(self, sleep):
+        """
+        Close should be passed through retry into target generator
+        """
         retry_ = retry_async.AsyncRetry(is_stream=True)
         decorated = retry_(self._generator_mock)
         exception_list = []
@@ -655,6 +680,9 @@ async def test___call___with_generator_close(self, sleep):
     @mock.patch("asyncio.sleep", autospec=True)
     @pytest.mark.asyncio
     async def test___call___with_generator_throw(self, sleep):
+        """
+        Throw should be passed through retry into target generator
+        """
         retry_ = retry_async.AsyncRetry(
             predicate=retry_async.if_exception_type(ValueError),
             is_stream=True,
@@ -691,18 +719,21 @@ async def test___call___with_iterable_coroutine_send_close_throw(self, sleep):
         retry_ = retry_async.AsyncRetry(is_stream=True)
 
         async def iterable_fn(n):
-            class CustomIterator:
+            class CustomIterable:
                 def __init__(self, n):
                     self.n = n
                     self.i = 0
 
+                def __aiter__(self):
+                    return self
+
                 async def __anext__(self):
                     if self.i == self.n:
                         raise StopAsyncIteration
                     self.i += 1
                     return self.i - 1
 
-            return CustomIterator(n)
+            return CustomIterable(n)
 
         decorated = retry_(iterable_fn)
 
@@ -731,18 +762,21 @@ async def test___call___with_iterable_send_close_throw(self, sleep):
         retry_ = retry_async.AsyncRetry(is_stream=True)
 
         def iterable_fn(n):
-            class CustomIterator:
+            class CustomIterable:
                 def __init__(self, n):
                     self.n = n
                     self.i = 0
 
+                def __aiter__(self):
+                    return self
+
                 async def __anext__(self):
                     if self.i == self.n:
                         raise StopAsyncIteration
                     self.i += 1
                     return self.i - 1
 
-            return CustomIterator(n)
+            return CustomIterable(n)
 
         decorated = retry_(iterable_fn)
 

tests/unit/test_retry.py

@@ -1,3 +1,4 @@
+# Copyright 2017 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -493,6 +494,10 @@ def _generator_mock(
         exceptions_seen=None,
         ignore_sent=False,
     ):
+        """
+        Helper to create a mock generator that yields a number of values
+        Generator can optionally raise an exception on a specific iteration
+        """
         try:
             sent_in = None
             for i in range(num):
@@ -510,6 +515,10 @@ def _generator_mock(
 
     @mock.patch("time.sleep", autospec=True)
     def test___call___generator_success(self, sleep):
+        """
+        Test that a retry-decorated generator yields values as expected
+        This test checks a generator with no issues
+        """
         import types
         import collections
 
@@ -533,6 +542,9 @@ def test___call___generator_success(self, sleep):
 
     @mock.patch("time.sleep", autospec=True)
     def test___call___generator_retry(self, sleep):
+        """
+        Tests that a retry-decorated generator will retry on errors
+        """
         on_error = mock.Mock(return_value=None)
         retry_ = retry.Retry(
             on_error=on_error,
@@ -550,6 +562,10 @@ def test___call___generator_retry(self, sleep):
     @mock.patch("random.uniform", autospec=True, side_effect=lambda m, n: n)
     @mock.patch("time.sleep", autospec=True)
     def test___call___generator_retry_hitting_deadline(self, sleep, uniform):
+        """
+        Tests that a retry-decorated generator will throw a RetryError
+        after using the time budget
+        """
         on_error = mock.Mock(return_value=None)
         retry_ = retry.Retry(
             predicate=retry.if_exception_type(ValueError),
@@ -677,6 +693,9 @@ def test___call___with_generator_return(self, sleep):
 
     @mock.patch("time.sleep", autospec=True)
     def test___call___with_generator_close(self, sleep):
+        """
+        Close should be passed through retry into target generator
+        """
         retry_ = retry.Retry(is_stream=True)
 
         decorated = retry_(self._generator_mock)
@@ -693,6 +712,9 @@ def test___call___with_generator_close(self, sleep):
 
     @mock.patch("time.sleep", autospec=True)
     def test___call___with_generator_throw(self, sleep):
+        """
+        Throw should be passed through retry into target generator
+        """
         retry_ = retry.Retry(
             predicate=retry.if_exception_type(ValueError), is_stream=True
         )
@@ -721,6 +743,10 @@ def test___call___with_generator_throw(self, sleep):
 
     @mock.patch("time.sleep", autospec=True)
     def test___call___with_is_stream(self, sleep):
+        """
+        is_stream should determine if the target is wrapped as a
+        generator or as a callable
+        """
         gen_retry_ = retry.Retry(
             is_stream=True, predicate=retry.if_exception_type(ValueError)
         )