Add google.api.core.gapic_v1.method

core/google/api/core/gapic_v1/method.py

@@ -29,6 +29,7 @@
 _GRPC_VERSION = pkg_resources.get_distribution('grpcio').version
 _API_CORE_VERSION = pkg_resources.get_distribution('google-cloud-core').version
 METRICS_METADATA_KEY = 'x-goog-api-client'
+USE_DEFAULT_METADATA = object()
 
 
 def _is_not_none_or_false(value):
@@ -87,10 +88,7 @@ def _determine_timeout(default_timeout, specified_timeout, retry):
  Returns:
  Optional[Timeout]: The timeout to apply to the method or ``None``.
  """
- if specified_timeout is False:
- return None
-
- if specified_timeout is None:
+ if specified_timeout is default_timeout:
  # If timeout is the default and the default timeout is exponential and
  # a non-default retry is specified, make sure the timeout's deadline
  # matches the retry's. This handles the case where the user leaves
@@ -116,13 +114,13 @@ class _GapicCallable(object):
  False, should accept a timeout argument. If metadata is not
  False, it should accept a metadata argument.
  retry (google.api.core.retry.Retry): The default retry for the
- callable. If falsy, this callable will not retry.
+ callable. If ``None``, this callable will not retry by default
  timeout (google.api.core.timeout.Timeout): The default timeout
- for the callable. If falsy, this callable will not specify
- a timeout argument to the low-level RPC method.
- metadata (Sequence[Tuple[str, str]]): gRPC call metadata that's
- passed to the low-level RPC method. If ``False``, this callable
- will not specify a metadata argument to the method.
+ for the callable. If ``None``, this callable will not specify
+ a timeout argument to the low-level RPC method by default.
+ metadata (Optional[Sequence[Tuple[str, str]]]): gRPC call metadata
+ that's passed to the low-level RPC method. If falsy, no metadata
+ will be passed to the low-level RPC method.
  """
 
  def __init__(self, target, retry, timeout, metadata):
@@ -133,32 +131,32 @@ def __init__(self, target, retry, timeout, metadata):
 
  def __call__(self, *args, **kwargs):
  """Invoke the low-level RPC with retry, timeout, and metadata."""
- # Note: Due to Python 2 lacking keyword-only arguments we kwargs to
+ # Note: Due to Python 2 lacking keyword-only arguments we use kwargs to
  # to extract the retry and timeout params.
  timeout_ = _determine_timeout(
  self._timeout,
- kwargs.pop('timeout', None),
- # Use the invocation-specified retry only for this, as we only
+ kwargs.pop('timeout', self._timeout),
+ # Use only the invocation-specified retry only for this, as we only
  # want to adjust the timeout deadline if the *user* specified
  # a different retry.
  kwargs.get('retry', None))
 
- retry = kwargs.pop('retry', None)
- if retry is None:
- retry = self._retry
+ retry = kwargs.pop('retry', self._retry)
 
  # Apply all applicable decorators.
  wrapped_func = _apply_decorators(self._target, [retry, timeout_])
 
  # Set the metadata for the call using the metadata calculated by
  # _prepare_metadata.
- if self._metadata is not False:
+ if self._metadata:
  kwargs['metadata'] = self._metadata
 
  return wrapped_func(*args, **kwargs)
 
 
-def wrap_method(func, default_retry=None, default_timeout=None, metadata=None):
+def wrap_method(
+ func, default_retry=None, default_timeout=None,
+ metadata=USE_DEFAULT_METADATA):
  """Wrap an RPC method with common behavior.
 
  This applies common error wrapping, retry, and timeout behavior a function.
@@ -186,7 +184,7 @@ def get_topic(name, timeout=None):
 
  # Execute get_topic without doing any retying but with the default
  # timeout:
- response = wrapped_get_topic(retry=False)
+ response = wrapped_get_topic(retry=None)
 
  # Execute get_topic but only retry on 5xx errors:
  my_retry = retry.Retry(retry.if_exception_type(
@@ -222,14 +220,15 @@ def get_topic(name, timeout=None):
  optional ``timeout`` argument. If ``metadata`` is not ``False``, it
  should accept a ``metadata`` argument.
  default_retry (Optional[google.api.core.Retry]): The default retry
- strategy. If falsy, the method will not retry by default.
+ strategy. If ``None``, the method will not retry by default.
  default_timeout (Optional[google.api.core.Timeout]): The default
- timeout strategy. If an int or float is specified, the timeout will
- always be set to that value.
- metadata (Union(Mapping[str, str], False)): A dict of metadata keys and
+ timeout strategy. Can also be specified as an int or float. If
+ ``None``, the method will not have timeout specified by default.
+ metadata (Optional(Mapping[str, str])): A dict of metadata keys and
  values. This will be augmented with common ``x-google-api-client``
- metadata. If ``False``, metadata will not be passed to the function
- at all.
+ metadata. If ``None``, metadata will not be passed to the function
+ at all, if ``USE_DEFAULT_METADATA`` (the default) then only the
+ common metadata will be provided.
 
  Returns:
  Callable: A new callable that takes optional ``retry`` and ``timeout``
@@ -238,7 +237,10 @@ def get_topic(name, timeout=None):
  """
  func = grpc_helpers.wrap_errors(func)
 
- if metadata is not False:
+ if metadata is USE_DEFAULT_METADATA:
+ metadata = {}
+
+ if metadata is not None:
  metadata = _prepare_metadata(metadata)
 
  return _GapicCallable(func, default_retry, default_timeout, metadata)

core/tests/unit/api_core/gapic/test_method.py

@@ -24,7 +24,7 @@ def test_wrap_method_basic():
  method = mock.Mock(spec=['__call__'], return_value=42)
 
  wrapped_method = google.api.core.gapic_v1.method.wrap_method(
- method, metadata=False)
+ method, metadata=None)
 
  result = wrapped_method(1, 2, meep='moop')