1# Copyright 2015-2016 gRPC authors. 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. 14"""Entry points into the Beta API of gRPC Python.""" 15 16# threading is referenced from specification in this module. 17import threading # pylint: disable=unused-import 18 19# interfaces, cardinality, and face are referenced from specification in this 20# module. 21import grpc 22from grpc import _auth 23from grpc.beta import _client_adaptations 24from grpc.beta import _metadata 25from grpc.beta import _server_adaptations 26from grpc.beta import interfaces # pylint: disable=unused-import 27from grpc.framework.common import cardinality # pylint: disable=unused-import 28from grpc.framework.interfaces.face import face # pylint: disable=unused-import 29 30# pylint: disable=too-many-arguments 31 32ChannelCredentials = grpc.ChannelCredentials 33ssl_channel_credentials = grpc.ssl_channel_credentials 34CallCredentials = grpc.CallCredentials 35 36 37def metadata_call_credentials(metadata_plugin, name=None): 38 def plugin(context, callback): 39 def wrapped_callback(beta_metadata, error): 40 callback(_metadata.unbeta(beta_metadata), error) 41 42 metadata_plugin(context, wrapped_callback) 43 44 return grpc.metadata_call_credentials(plugin, name=name) 45 46 47def google_call_credentials(credentials): 48 """Construct CallCredentials from GoogleCredentials. 49 50 Args: 51 credentials: A GoogleCredentials object from the oauth2client library. 52 53 Returns: 54 A CallCredentials object for use in a GRPCCallOptions object. 55 """ 56 return metadata_call_credentials(_auth.GoogleCallCredentials(credentials)) 57 58 59access_token_call_credentials = grpc.access_token_call_credentials 60composite_call_credentials = grpc.composite_call_credentials 61composite_channel_credentials = grpc.composite_channel_credentials 62 63 64class Channel(object): 65 """A channel to a remote host through which RPCs may be conducted. 66 67 Only the "subscribe" and "unsubscribe" methods are supported for application 68 use. This class' instance constructor and all other attributes are 69 unsupported. 70 """ 71 72 def __init__(self, channel): 73 self._channel = channel 74 75 def subscribe(self, callback, try_to_connect=None): 76 """Subscribes to this Channel's connectivity. 77 78 Args: 79 callback: A callable to be invoked and passed an 80 interfaces.ChannelConnectivity identifying this Channel's connectivity. 81 The callable will be invoked immediately upon subscription and again for 82 every change to this Channel's connectivity thereafter until it is 83 unsubscribed. 84 try_to_connect: A boolean indicating whether or not this Channel should 85 attempt to connect if it is not already connected and ready to conduct 86 RPCs. 87 """ 88 self._channel.subscribe(callback, try_to_connect=try_to_connect) 89 90 def unsubscribe(self, callback): 91 """Unsubscribes a callback from this Channel's connectivity. 92 93 Args: 94 callback: A callable previously registered with this Channel from having 95 been passed to its "subscribe" method. 96 """ 97 self._channel.unsubscribe(callback) 98 99 100def insecure_channel(host, port): 101 """Creates an insecure Channel to a remote host. 102 103 Args: 104 host: The name of the remote host to which to connect. 105 port: The port of the remote host to which to connect. 106 If None only the 'host' part will be used. 107 108 Returns: 109 A Channel to the remote host through which RPCs may be conducted. 110 """ 111 channel = grpc.insecure_channel( 112 host if port is None else "%s:%d" % (host, port) 113 ) 114 return Channel(channel) 115 116 117def secure_channel(host, port, channel_credentials): 118 """Creates a secure Channel to a remote host. 119 120 Args: 121 host: The name of the remote host to which to connect. 122 port: The port of the remote host to which to connect. 123 If None only the 'host' part will be used. 124 channel_credentials: A ChannelCredentials. 125 126 Returns: 127 A secure Channel to the remote host through which RPCs may be conducted. 128 """ 129 channel = grpc.secure_channel( 130 host if port is None else "%s:%d" % (host, port), channel_credentials 131 ) 132 return Channel(channel) 133 134 135class StubOptions(object): 136 """A value encapsulating the various options for creation of a Stub. 137 138 This class and its instances have no supported interface - it exists to define 139 the type of its instances and its instances exist to be passed to other 140 functions. 141 """ 142 143 def __init__( 144 self, 145 host, 146 request_serializers, 147 response_deserializers, 148 metadata_transformer, 149 thread_pool, 150 thread_pool_size, 151 ): 152 self.host = host 153 self.request_serializers = request_serializers 154 self.response_deserializers = response_deserializers 155 self.metadata_transformer = metadata_transformer 156 self.thread_pool = thread_pool 157 self.thread_pool_size = thread_pool_size 158 159 160_EMPTY_STUB_OPTIONS = StubOptions(None, None, None, None, None, None) 161 162 163def stub_options( 164 host=None, 165 request_serializers=None, 166 response_deserializers=None, 167 metadata_transformer=None, 168 thread_pool=None, 169 thread_pool_size=None, 170): 171 """Creates a StubOptions value to be passed at stub creation. 172 173 All parameters are optional and should always be passed by keyword. 174 175 Args: 176 host: A host string to set on RPC calls. 177 request_serializers: A dictionary from service name-method name pair to 178 request serialization behavior. 179 response_deserializers: A dictionary from service name-method name pair to 180 response deserialization behavior. 181 metadata_transformer: A callable that given a metadata object produces 182 another metadata object to be used in the underlying communication on the 183 wire. 184 thread_pool: A thread pool to use in stubs. 185 thread_pool_size: The size of thread pool to create for use in stubs; 186 ignored if thread_pool has been passed. 187 188 Returns: 189 A StubOptions value created from the passed parameters. 190 """ 191 return StubOptions( 192 host, 193 request_serializers, 194 response_deserializers, 195 metadata_transformer, 196 thread_pool, 197 thread_pool_size, 198 ) 199 200 201def generic_stub(channel, options=None): 202 """Creates a face.GenericStub on which RPCs can be made. 203 204 Args: 205 channel: A Channel for use by the created stub. 206 options: A StubOptions customizing the created stub. 207 208 Returns: 209 A face.GenericStub on which RPCs can be made. 210 """ 211 effective_options = _EMPTY_STUB_OPTIONS if options is None else options 212 return _client_adaptations.generic_stub( 213 channel._channel, # pylint: disable=protected-access 214 effective_options.host, 215 effective_options.metadata_transformer, 216 effective_options.request_serializers, 217 effective_options.response_deserializers, 218 ) 219 220 221def dynamic_stub(channel, service, cardinalities, options=None): 222 """Creates a face.DynamicStub with which RPCs can be invoked. 223 224 Args: 225 channel: A Channel for the returned face.DynamicStub to use. 226 service: The package-qualified full name of the service. 227 cardinalities: A dictionary from RPC method name to cardinality.Cardinality 228 value identifying the cardinality of the RPC method. 229 options: An optional StubOptions value further customizing the functionality 230 of the returned face.DynamicStub. 231 232 Returns: 233 A face.DynamicStub with which RPCs can be invoked. 234 """ 235 effective_options = _EMPTY_STUB_OPTIONS if options is None else options 236 return _client_adaptations.dynamic_stub( 237 channel._channel, # pylint: disable=protected-access 238 service, 239 cardinalities, 240 effective_options.host, 241 effective_options.metadata_transformer, 242 effective_options.request_serializers, 243 effective_options.response_deserializers, 244 ) 245 246 247ServerCredentials = grpc.ServerCredentials 248ssl_server_credentials = grpc.ssl_server_credentials 249 250 251class ServerOptions(object): 252 """A value encapsulating the various options for creation of a Server. 253 254 This class and its instances have no supported interface - it exists to define 255 the type of its instances and its instances exist to be passed to other 256 functions. 257 """ 258 259 def __init__( 260 self, 261 multi_method_implementation, 262 request_deserializers, 263 response_serializers, 264 thread_pool, 265 thread_pool_size, 266 default_timeout, 267 maximum_timeout, 268 ): 269 self.multi_method_implementation = multi_method_implementation 270 self.request_deserializers = request_deserializers 271 self.response_serializers = response_serializers 272 self.thread_pool = thread_pool 273 self.thread_pool_size = thread_pool_size 274 self.default_timeout = default_timeout 275 self.maximum_timeout = maximum_timeout 276 277 278_EMPTY_SERVER_OPTIONS = ServerOptions(None, None, None, None, None, None, None) 279 280 281def server_options( 282 multi_method_implementation=None, 283 request_deserializers=None, 284 response_serializers=None, 285 thread_pool=None, 286 thread_pool_size=None, 287 default_timeout=None, 288 maximum_timeout=None, 289): 290 """Creates a ServerOptions value to be passed at server creation. 291 292 All parameters are optional and should always be passed by keyword. 293 294 Args: 295 multi_method_implementation: A face.MultiMethodImplementation to be called 296 to service an RPC if the server has no specific method implementation for 297 the name of the RPC for which service was requested. 298 request_deserializers: A dictionary from service name-method name pair to 299 request deserialization behavior. 300 response_serializers: A dictionary from service name-method name pair to 301 response serialization behavior. 302 thread_pool: A thread pool to use in stubs. 303 thread_pool_size: The size of thread pool to create for use in stubs; 304 ignored if thread_pool has been passed. 305 default_timeout: A duration in seconds to allow for RPC service when 306 servicing RPCs that did not include a timeout value when invoked. 307 maximum_timeout: A duration in seconds to allow for RPC service when 308 servicing RPCs no matter what timeout value was passed when the RPC was 309 invoked. 310 311 Returns: 312 A StubOptions value created from the passed parameters. 313 """ 314 return ServerOptions( 315 multi_method_implementation, 316 request_deserializers, 317 response_serializers, 318 thread_pool, 319 thread_pool_size, 320 default_timeout, 321 maximum_timeout, 322 ) 323 324 325def server(service_implementations, options=None): 326 """Creates an interfaces.Server with which RPCs can be serviced. 327 328 Args: 329 service_implementations: A dictionary from service name-method name pair to 330 face.MethodImplementation. 331 options: An optional ServerOptions value further customizing the 332 functionality of the returned Server. 333 334 Returns: 335 An interfaces.Server with which RPCs can be serviced. 336 """ 337 effective_options = _EMPTY_SERVER_OPTIONS if options is None else options 338 return _server_adaptations.server( 339 service_implementations, 340 effective_options.multi_method_implementation, 341 effective_options.request_deserializers, 342 effective_options.response_serializers, 343 effective_options.thread_pool, 344 effective_options.thread_pool_size, 345 ) 346