def test_wrap_method_with_custom_client_info():
client_info = google.api_core.gapic_v1.client_info.ClientInfo(
python_version=1, grpc_version=2, api_core_version=3, gapic_version=4,
client_library_version=5)
method = mock.Mock(spec=['__call__'])
wrapped_method = google.api_core.gapic_v1.method.wrap_method(
method, client_info=client_info)
wrapped_method(1, 2, meep='moop')
method.assert_called_once_with(1, 2, meep='moop', metadata=mock.ANY)
# Check that the custom client info was specified in the metadata.
metadata = method.call_args[1]['metadata']
assert client_info.to_grpc_metadata() in metadata
def test_wrap_method_basic():
method = mock.Mock(spec=["__call__"], return_value=42)
wrapped_method = google.api_core.gapic_v1.method.wrap_method(method)
result = wrapped_method(1, 2, meep="moop")
assert result == 42
method.assert_called_once_with(1, 2, meep="moop", metadata=mock.ANY)
# Check that the default client info was specified in the metadata.
metadata = method.call_args[1]["metadata"]
assert len(metadata) == 1
client_info = google.api_core.gapic_v1.client_info.DEFAULT_CLIENT_INFO
user_agent_metadata = client_info.to_grpc_metadata()
assert user_agent_metadata in metadata
def test_wrap_method_basic():
method = mock.Mock(spec=['__call__'], return_value=42)
wrapped_method = google.api_core.gapic_v1.method.wrap_method(method)
result = wrapped_method(1, 2, meep='moop')
assert result == 42
method.assert_called_once_with(1, 2, meep='moop', metadata=mock.ANY)
# Check that the default client info was specified in the metadata.
metadata = method.call_args[1]['metadata']
assert len(metadata) == 1
client_info = google.api_core.gapic_v1.client_info.DEFAULT_CLIENT_INFO
user_agent_metadata = client_info.to_grpc_metadata()
assert user_agent_metadata in metadata
def test_wrap_method_with_custom_client_info():
client_info = google.api_core.gapic_v1.client_info.ClientInfo(
python_version=1, grpc_version=2, api_core_version=3, gapic_version=4,
client_library_version=5)
method = mock.Mock(spec=['__call__'])
wrapped_method = google.api_core.gapic_v1.method.wrap_method(
method, client_info=client_info)
wrapped_method(1, 2, meep='moop')
method.assert_called_once_with(1, 2, meep='moop', metadata=mock.ANY)
# Check that the custom client info was specified in the metadata.
metadata = method.call_args[1]['metadata']
assert client_info.to_grpc_metadata() in metadata
def wrap_method(
func,
default_retry=None,
default_timeout=None,
client_info=client_info.DEFAULT_CLIENT_INFO,
):
"""Wrap an async RPC method with common behavior.
Returns:
Callable: A new callable that takes optional ``retry`` and ``timeout``
arguments and applies the common error mapping, retry, timeout,
and metadata behavior to the low-level RPC method.
"""
func = grpc_helpers_async.wrap_errors(func)
metadata = [client_info.to_grpc_metadata()] if client_info is not None else None
return functools.wraps(func)(
_GapicCallable(func, default_retry, default_timeout, metadata=metadata)
)
def wrap_method(
func, default_retry=None, default_timeout=None,
client_info=client_info.DEFAULT_CLIENT_INFO):
"""Wrap an RPC method with common behavior.
This applies common error wrapping, retry, and timeout behavior a function.
The wrapped function will take optional ``retry`` and ``timeout``
arguments.
For example::
import google.api_core.gapic_v1.method
from google.api_core import retry
from google.api_core import timeout
# The original RPC method.
def get_topic(name, timeout=None):
request = publisher_v2.GetTopicRequest(name=name)
return publisher_stub.GetTopic(request, timeout=timeout)
default_retry = retry.Retry(deadline=60)
default_timeout = timeout.Timeout(deadline=60)
wrapped_get_topic = google.api_core.gapic_v1.method.wrap_method(
get_topic, default_retry)
# Execute get_topic with default retry and timeout:
response = wrapped_get_topic()
# Execute get_topic without doing any retying but with the default
# timeout:
response = wrapped_get_topic(retry=None)
# Execute get_topic but only retry on 5xx errors:
my_retry = retry.Retry(retry.if_exception_type(
exceptions.InternalServerError))
response = wrapped_get_topic(retry=my_retry)
The way this works is by late-wrapping the given function with the retry
and timeout decorators. Essentially, when ``wrapped_get_topic()`` is
called:
* ``get_topic()`` is first wrapped with the ``timeout`` into
``get_topic_with_timeout``.
* ``get_topic_with_timeout`` is wrapped with the ``retry`` into
``get_topic_with_timeout_and_retry()``.
* The final ``get_topic_with_timeout_and_retry`` is called passing through
the ``args`` and ``kwargs``.
The callstack is therefore::
method.__call__() ->
Retry.__call__() ->
Timeout.__call__() ->
wrap_errors() ->
get_topic()
Note that if ``timeout`` or ``retry`` is ``None``, then they are not
applied to the function. For example,
``wrapped_get_topic(timeout=None, retry=None)`` is more or less
equivalent to just calling ``get_topic`` but with error re-mapping.
Args:
func (Callable[Any]): The function to wrap. It should accept an
optional ``timeout`` argument. If ``metadata`` is not ``None``, it
should accept a ``metadata`` argument.
default_retry (Optional[google.api_core.Retry]): The default retry
strategy. If ``None``, the method will not retry by default.
default_timeout (Optional[google.api_core.Timeout]): The default
timeout strategy. Can also be specified as an int or float. If
``None``, the method will not have timeout specified by default.
client_info
(Optional[google.api_core.gapic_v1.client_info.ClientInfo]):
Client information used to create a user-agent string that's
passed as gRPC metadata to the method. If unspecified, then
a sane default will be used. If ``None``, then no user agent
metadata will be provided to the RPC method.
Returns:
Callable: A new callable that takes optional ``retry`` and ``timeout``
arguments and applies the common error mapping, retry, timeout,
and metadata behavior to the low-level RPC method.
"""
func = grpc_helpers.wrap_errors(func)
if client_info is not None:
user_agent_metadata = [client_info.to_grpc_metadata()]
else:
user_agent_metadata = None
return general_helpers.wraps(func)(
_GapicCallable(
func, default_retry, default_timeout,
metadata=user_agent_metadata))
def wrap_method(
func,
default_retry=None,
default_timeout=None,
client_info=client_info.DEFAULT_CLIENT_INFO,
):
"""Wrap an RPC method with common behavior.
This applies common error wrapping, retry, and timeout behavior a function.
The wrapped function will take optional ``retry`` and ``timeout``
arguments.
For example::
import google.api_core.gapic_v1.method
from google.api_core import retry
from google.api_core import timeout
# The original RPC method.
def get_topic(name, timeout=None):
request = publisher_v2.GetTopicRequest(name=name)
return publisher_stub.GetTopic(request, timeout=timeout)
default_retry = retry.Retry(deadline=60)
default_timeout = timeout.Timeout(deadline=60)
wrapped_get_topic = google.api_core.gapic_v1.method.wrap_method(
get_topic, default_retry)
# Execute get_topic with default retry and timeout:
response = wrapped_get_topic()
# Execute get_topic without doing any retying but with the default
# timeout:
response = wrapped_get_topic(retry=None)
# Execute get_topic but only retry on 5xx errors:
my_retry = retry.Retry(retry.if_exception_type(
exceptions.InternalServerError))
response = wrapped_get_topic(retry=my_retry)
The way this works is by late-wrapping the given function with the retry
and timeout decorators. Essentially, when ``wrapped_get_topic()`` is
called:
* ``get_topic()`` is first wrapped with the ``timeout`` into
``get_topic_with_timeout``.
* ``get_topic_with_timeout`` is wrapped with the ``retry`` into
``get_topic_with_timeout_and_retry()``.
* The final ``get_topic_with_timeout_and_retry`` is called passing through
the ``args`` and ``kwargs``.
The callstack is therefore::
method.__call__() ->
Retry.__call__() ->
Timeout.__call__() ->
wrap_errors() ->
get_topic()
Note that if ``timeout`` or ``retry`` is ``None``, then they are not
applied to the function. For example,
``wrapped_get_topic(timeout=None, retry=None)`` is more or less
equivalent to just calling ``get_topic`` but with error re-mapping.
Args:
func (Callable[Any]): The function to wrap. It should accept an
optional ``timeout`` argument. If ``metadata`` is not ``None``, it
should accept a ``metadata`` argument.
default_retry (Optional[google.api_core.Retry]): The default retry
strategy. If ``None``, the method will not retry by default.
default_timeout (Optional[google.api_core.Timeout]): The default
timeout strategy. Can also be specified as an int or float. If
``None``, the method will not have timeout specified by default.
client_info
(Optional[google.api_core.gapic_v1.client_info.ClientInfo]):
Client information used to create a user-agent string that's
passed as gRPC metadata to the method. If unspecified, then
a sane default will be used. If ``None``, then no user agent
metadata will be provided to the RPC method.
Returns:
Callable: A new callable that takes optional ``retry`` and ``timeout``
arguments and applies the common error mapping, retry, timeout,
and metadata behavior to the low-level RPC method.
"""
func = grpc_helpers.wrap_errors(func)
if client_info is not None:
user_agent_metadata = [client_info.to_grpc_metadata()]
else:
user_agent_metadata = None
return functools.wraps(func)(_GapicCallable(func,
default_retry,
default_timeout,
metadata=user_agent_metadata))
