Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2017 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""Helpers for loading gapic configuration data.
17The Google API generator creates supplementary configuration for each RPC
18method to tell the client library how to deal with retries and timeouts.
19"""
21import collections
23import grpc
25from google.api_core import exceptions
26from google.api_core import retry
27from google.api_core import timeout
30_MILLIS_PER_SECOND = 1000.0
33def _exception_class_for_grpc_status_name(name):
34 """Returns the Google API exception class for a gRPC error code name.
36 DEPRECATED: use ``exceptions.exception_class_for_grpc_status`` method
37 directly instead.
39 Args:
40 name (str): The name of the gRPC status code, for example,
41 ``UNAVAILABLE``.
43 Returns:
44 :func:`type`: The appropriate subclass of
45 :class:`google.api_core.exceptions.GoogleAPICallError`.
46 """
47 return exceptions.exception_class_for_grpc_status(getattr(grpc.StatusCode, name))
50def _retry_from_retry_config(retry_params, retry_codes, retry_impl=retry.Retry):
51 """Creates a Retry object given a gapic retry configuration.
53 DEPRECATED: instantiate retry and timeout classes directly instead.
55 Args:
56 retry_params (dict): The retry parameter values, for example::
58 {
59 "initial_retry_delay_millis": 1000,
60 "retry_delay_multiplier": 2.5,
61 "max_retry_delay_millis": 120000,
62 "initial_rpc_timeout_millis": 120000,
63 "rpc_timeout_multiplier": 1.0,
64 "max_rpc_timeout_millis": 120000,
65 "total_timeout_millis": 600000
66 }
68 retry_codes (sequence[str]): The list of retryable gRPC error code
69 names.
71 Returns:
72 google.api_core.retry.Retry: The default retry object for the method.
73 """
74 exception_classes = [
75 _exception_class_for_grpc_status_name(code) for code in retry_codes
76 ]
77 return retry_impl(
78 retry.if_exception_type(*exception_classes),
79 initial=(retry_params["initial_retry_delay_millis"] / _MILLIS_PER_SECOND),
80 maximum=(retry_params["max_retry_delay_millis"] / _MILLIS_PER_SECOND),
81 multiplier=retry_params["retry_delay_multiplier"],
82 deadline=retry_params["total_timeout_millis"] / _MILLIS_PER_SECOND,
83 )
86def _timeout_from_retry_config(retry_params):
87 """Creates a ExponentialTimeout object given a gapic retry configuration.
89 DEPRECATED: instantiate retry and timeout classes directly instead.
91 Args:
92 retry_params (dict): The retry parameter values, for example::
94 {
95 "initial_retry_delay_millis": 1000,
96 "retry_delay_multiplier": 2.5,
97 "max_retry_delay_millis": 120000,
98 "initial_rpc_timeout_millis": 120000,
99 "rpc_timeout_multiplier": 1.0,
100 "max_rpc_timeout_millis": 120000,
101 "total_timeout_millis": 600000
102 }
104 Returns:
105 google.api_core.retry.ExponentialTimeout: The default time object for
106 the method.
107 """
108 return timeout.ExponentialTimeout(
109 initial=(retry_params["initial_rpc_timeout_millis"] / _MILLIS_PER_SECOND),
110 maximum=(retry_params["max_rpc_timeout_millis"] / _MILLIS_PER_SECOND),
111 multiplier=retry_params["rpc_timeout_multiplier"],
112 deadline=(retry_params["total_timeout_millis"] / _MILLIS_PER_SECOND),
113 )
116MethodConfig = collections.namedtuple("MethodConfig", ["retry", "timeout"])
119def parse_method_configs(interface_config, retry_impl=retry.Retry):
120 """Creates default retry and timeout objects for each method in a gapic
121 interface config.
123 DEPRECATED: instantiate retry and timeout classes directly instead.
125 Args:
126 interface_config (Mapping): The interface config section of the full
127 gapic library config. For example, If the full configuration has
128 an interface named ``google.example.v1.ExampleService`` you would
129 pass in just that interface's configuration, for example
130 ``gapic_config['interfaces']['google.example.v1.ExampleService']``.
131 retry_impl (Callable): The constructor that creates a retry decorator
132 that will be applied to the method based on method configs.
134 Returns:
135 Mapping[str, MethodConfig]: A mapping of RPC method names to their
136 configuration.
137 """
138 # Grab all the retry codes
139 retry_codes_map = {
140 name: retry_codes
141 for name, retry_codes in interface_config.get("retry_codes", {}).items()
142 }
144 # Grab all of the retry params
145 retry_params_map = {
146 name: retry_params
147 for name, retry_params in interface_config.get("retry_params", {}).items()
148 }
150 # Iterate through all the API methods and create a flat MethodConfig
151 # instance for each one.
152 method_configs = {}
154 for method_name, method_params in interface_config.get("methods", {}).items():
155 retry_params_name = method_params.get("retry_params_name")
157 if retry_params_name is not None:
158 retry_params = retry_params_map[retry_params_name]
159 retry_ = _retry_from_retry_config(
160 retry_params,
161 retry_codes_map[method_params["retry_codes_name"]],
162 retry_impl,
163 )
164 timeout_ = _timeout_from_retry_config(retry_params)
166 # No retry config, so this is a non-retryable method.
167 else:
168 retry_ = None
169 timeout_ = timeout.ConstantTimeout(
170 method_params["timeout_millis"] / _MILLIS_PER_SECOND
171 )
173 method_configs[method_name] = MethodConfig(retry=retry_, timeout=timeout_)
175 return method_configs