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