made build_retry_error public

Author: daniel-sanche

google/api_core/retry/__init__.py

@@ -1,4 +1,5 @@
 # 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.
@@ -17,7 +18,7 @@
 from .retry_base import exponential_sleep_generator
 from .retry_base import if_exception_type
 from .retry_base import if_transient_error
-from .retry_base import _build_retry_error
+from .retry_base import build_retry_error
 from .retry_base import RetryFailureReason
 from .retry_unary import Retry
 from .retry_unary import retry_target
@@ -32,7 +33,7 @@
     "exponential_sleep_generator",
     "if_exception_type",
     "if_transient_error",
-    "_build_retry_error",
+    "build_retry_error",
     "RetryFailureReason",
     "Retry",
     "AsyncRetry",

google/api_core/retry/retry_base.py

@@ -131,14 +131,17 @@ class RetryFailureReason(Enum):
     NON_RETRYABLE_ERROR = 1
 
 
-def _build_retry_error(
+def build_retry_error(
     exc_list: list[Exception],
     reason: RetryFailureReason,
     timeout_val: float | None,
     **kwargs: Any,
 ) -> tuple[Exception, Exception | None]:
     """
-    Default exception_factory implementation. Builds an exception after the retry fails.
+    Default exception_factory implementation.
+
+    Returns a RetryError if the failure is due to a timeout, otherwise
+    returns the last exception encountered.
 
     Args:
       - exc_list: list of exceptions that occurred during the retry

google/api_core/retry/retry_streaming.py

@@ -36,7 +36,7 @@
 from google.api_core.retry.retry_base import _BaseRetry
 from google.api_core.retry.retry_base import _retry_error_helper
 from google.api_core.retry import exponential_sleep_generator
-from google.api_core.retry import _build_retry_error
+from google.api_core.retry import build_retry_error
 from google.api_core.retry import RetryFailureReason
 
 if TYPE_CHECKING:
@@ -58,7 +58,7 @@ def retry_target_stream(
     exception_factory: Callable[
         [List[Exception], RetryFailureReason, Optional[float]],
         Tuple[Exception, Optional[Exception]],
-    ] = _build_retry_error,
+    ] = build_retry_error,
     init_args: _P.args = (),
     init_kwargs: _P.kwargs = {},
     **kwargs,

google/api_core/retry/retry_streaming_async.py

@@ -38,7 +38,7 @@
 from google.api_core.retry.retry_base import _BaseRetry
 from google.api_core.retry.retry_base import _retry_error_helper
 from google.api_core.retry import exponential_sleep_generator
-from google.api_core.retry import _build_retry_error
+from google.api_core.retry import build_retry_error
 from google.api_core.retry import RetryFailureReason
 
 
@@ -61,7 +61,7 @@ async def retry_target_stream(
     exception_factory: Callable[
         [list[Exception], RetryFailureReason, float | None],
         tuple[Exception, Exception | None],
-    ] = _build_retry_error,
+    ] = build_retry_error,
     init_args: _P.args = (),
     init_kwargs: _P.kwargs = {},
     **kwargs,

google/api_core/retry/retry_unary.py

@@ -66,7 +66,7 @@ def check_if_exists():
 from google.api_core.retry.retry_base import _BaseRetry
 from google.api_core.retry.retry_base import _retry_error_helper
 from google.api_core.retry.retry_base import exponential_sleep_generator
-from google.api_core.retry.retry_base import _build_retry_error
+from google.api_core.retry.retry_base import build_retry_error
 from google.api_core.retry.retry_base import RetryFailureReason
 
 
@@ -91,7 +91,7 @@ def retry_target(
     exception_factory: Callable[
         [list[Exception], RetryFailureReason, float | None],
         tuple[Exception, Exception | None],
-    ] = _build_retry_error,
+    ] = build_retry_error,
     **kwargs,
 ):
     """Call a function and retry if it fails.

google/api_core/retry/retry_unary_async.py

@@ -68,7 +68,7 @@ async def check_if_exists():
 from google.api_core.retry.retry_base import _BaseRetry
 from google.api_core.retry.retry_base import _retry_error_helper
 from google.api_core.retry.retry_base import exponential_sleep_generator
-from google.api_core.retry.retry_base import _build_retry_error
+from google.api_core.retry.retry_base import build_retry_error
 from google.api_core.retry.retry_base import RetryFailureReason
 
 # for backwards compatibility, expose helpers in this module
@@ -101,7 +101,7 @@ async def retry_target(
     exception_factory: Callable[
         [list[Exception], RetryFailureReason, float | None],
         tuple[Exception, Exception | None],
-    ] = _build_retry_error,
+    ] = build_retry_error,
     **kwargs,
 ):
     """Await a coroutine and retry if it fails.

tests/unit/retry/test_retry_base.py

@@ -58,47 +58,47 @@ def test_exponential_sleep_generator_base_2(uniform):
     assert result == [1, 2, 4, 8, 16, 32, 60, 60]
 
 
-def test__build_retry_error_empty_list():
+def test_build_retry_error_empty_list():
     """
     attempt to build a retry error with no errors encountered
     should return a generic RetryError
     """
-    from google.api_core.retry import _build_retry_error
+    from google.api_core.retry import build_retry_error
     from google.api_core.retry import RetryFailureReason
 
     reason = RetryFailureReason.NON_RETRYABLE_ERROR
-    src, cause = _build_retry_error([], reason, 10)
+    src, cause = build_retry_error([], reason, 10)
     assert isinstance(src, exceptions.RetryError)
     assert cause is None
     assert src.message == "Unknown error"
 
 
-def test__build_retry_error_timeout_message():
+def test_build_retry_error_timeout_message():
     """
     should provide helpful error message when timeout is reached
     """
-    from google.api_core.retry import _build_retry_error
+    from google.api_core.retry import build_retry_error
     from google.api_core.retry import RetryFailureReason
 
     reason = RetryFailureReason.TIMEOUT
     cause = RuntimeError("timeout")
-    src, found_cause = _build_retry_error([ValueError(), cause], reason, 10)
+    src, found_cause = build_retry_error([ValueError(), cause], reason, 10)
     assert isinstance(src, exceptions.RetryError)
     assert src.message == "Timeout of 10.0s exceeded"
     # should attach appropriate cause
     assert found_cause is cause
 
 
-def test__build_retry_error_empty_timeout():
+def test_build_retry_error_empty_timeout():
     """
     attempt to build a retry error when timeout is None
     should return a generic timeout error message
     """
-    from google.api_core.retry import _build_retry_error
+    from google.api_core.retry import build_retry_error
     from google.api_core.retry import RetryFailureReason
 
     reason = RetryFailureReason.TIMEOUT
-    src, _ = _build_retry_error([], reason, None)
+    src, _ = build_retry_error([], reason, None)
     assert isinstance(src, exceptions.RetryError)
     assert src.message == "Timeout exceeded"