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, retry, timeout
27_MILLIS_PER_SECOND = 1000.0
30def _exception_class_for_grpc_status_name(name):
31 """Returns the Google API exception class for a gRPC error code name.
33 DEPRECATED: use ``exceptions.exception_class_for_grpc_status`` method
34 directly instead.
36 Args:
37 name (str): The name of the gRPC status code, for example,
38 ``UNAVAILABLE``.
40 Returns:
41 :func:`type`: The appropriate subclass of
42 :class:`google.api_core.exceptions.GoogleAPICallError`.
43 """
44 return exceptions.exception_class_for_grpc_status(getattr(grpc.StatusCode, name))
47def _retry_from_retry_config(retry_params, retry_codes, retry_impl=retry.Retry):
48 """Creates a Retry object given a gapic retry configuration.
50 DEPRECATED: instantiate retry and timeout classes directly instead.
52 Args:
53 retry_params (dict): The retry parameter values, for example::
55 {
56 "initial_retry_delay_millis": 1000,
57 "retry_delay_multiplier": 2.5,
58 "max_retry_delay_millis": 120000,
59 "initial_rpc_timeout_millis": 120000,
60 "rpc_timeout_multiplier": 1.0,
61 "max_rpc_timeout_millis": 120000,
62 "total_timeout_millis": 600000
63 }
65 retry_codes (sequence[str]): The list of retryable gRPC error code
66 names.
68 Returns:
69 google.api_core.retry.Retry: The default retry object for the method.
70 """
71 exception_classes = [
72 _exception_class_for_grpc_status_name(code) for code in retry_codes
73 ]
74 return retry_impl(
75 retry.if_exception_type(*exception_classes),
76 initial=(retry_params["initial_retry_delay_millis"] / _MILLIS_PER_SECOND),
77 maximum=(retry_params["max_retry_delay_millis"] / _MILLIS_PER_SECOND),
78 multiplier=retry_params["retry_delay_multiplier"],
79 deadline=retry_params["total_timeout_millis"] / _MILLIS_PER_SECOND,
80 )
83def _timeout_from_retry_config(retry_params):
84 """Creates a ExponentialTimeout object given a gapic retry configuration.
86 DEPRECATED: instantiate retry and timeout classes directly instead.
88 Args:
89 retry_params (dict): The retry parameter values, for example::
91 {
92 "initial_retry_delay_millis": 1000,
93 "retry_delay_multiplier": 2.5,
94 "max_retry_delay_millis": 120000,
95 "initial_rpc_timeout_millis": 120000,
96 "rpc_timeout_multiplier": 1.0,
97 "max_rpc_timeout_millis": 120000,
98 "total_timeout_millis": 600000
99 }
101 Returns:
102 google.api_core.retry.ExponentialTimeout: The default time object for
103 the method.
104 """
105 return timeout.ExponentialTimeout(
106 initial=(retry_params["initial_rpc_timeout_millis"] / _MILLIS_PER_SECOND),
107 maximum=(retry_params["max_rpc_timeout_millis"] / _MILLIS_PER_SECOND),
108 multiplier=retry_params["rpc_timeout_multiplier"],
109 deadline=(retry_params["total_timeout_millis"] / _MILLIS_PER_SECOND),
110 )
113MethodConfig = collections.namedtuple("MethodConfig", ["retry", "timeout"])
116def parse_method_configs(interface_config, retry_impl=retry.Retry):
117 """Creates default retry and timeout objects for each method in a gapic
118 interface config.
120 DEPRECATED: instantiate retry and timeout classes directly instead.
122 Args:
123 interface_config (Mapping): The interface config section of the full
124 gapic library config. For example, If the full configuration has
125 an interface named ``google.example.v1.ExampleService`` you would
126 pass in just that interface's configuration, for example
127 ``gapic_config['interfaces']['google.example.v1.ExampleService']``.
128 retry_impl (Callable): The constructor that creates a retry decorator
129 that will be applied to the method based on method configs.
131 Returns:
132 Mapping[str, MethodConfig]: A mapping of RPC method names to their
133 configuration.
134 """
135 # Grab all the retry codes
136 retry_codes_map = {
137 name: retry_codes
138 for name, retry_codes in interface_config.get("retry_codes", {}).items()
139 }
141 # Grab all of the retry params
142 retry_params_map = {
143 name: retry_params
144 for name, retry_params in interface_config.get("retry_params", {}).items()
145 }
147 # Iterate through all the API methods and create a flat MethodConfig
148 # instance for each one.
149 method_configs = {}
151 for method_name, method_params in interface_config.get("methods", {}).items():
152 retry_params_name = method_params.get("retry_params_name")
154 if retry_params_name is not None:
155 retry_params = retry_params_map[retry_params_name]
156 retry_ = _retry_from_retry_config(
157 retry_params,
158 retry_codes_map[method_params["retry_codes_name"]],
159 retry_impl,
160 )
161 timeout_ = _timeout_from_retry_config(retry_params)
163 # No retry config, so this is a non-retryable method.
164 else:
165 retry_ = None
166 timeout_ = timeout.ConstantTimeout(
167 method_params["timeout_millis"] / _MILLIS_PER_SECOND
168 )
170 method_configs[method_name] = MethodConfig(retry=retry_, timeout=timeout_)
172 return method_configs