• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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