codekingpro/portable-devtools

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