codekingpro/portable-devtools

1# Copyright 2015 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"""Interfaces defining the Face layer of RPC Framework."""
15
16import abc
17import collections
18import enum
19
20# cardinality, style, abandonment, future, and stream are
21# referenced from specification in this module.
22from grpc.framework.common import cardinality  # pylint: disable=unused-import
23from grpc.framework.common import style  # pylint: disable=unused-import
24from grpc.framework.foundation import future  # pylint: disable=unused-import
25from grpc.framework.foundation import stream  # pylint: disable=unused-import
26
27# pylint: disable=too-many-arguments
28
29
30class NoSuchMethodError(Exception):
31    """Raised by customer code to indicate an unrecognized method.
32
33    Attributes:
34      group: The group of the unrecognized method.
35      name: The name of the unrecognized method.
36    """
37
38    def __init__(self, group, method):
39        """Constructor.
40
41        Args:
42          group: The group identifier of the unrecognized RPC name.
43          method: The method identifier of the unrecognized RPC name.
44        """
45        super(NoSuchMethodError, self).__init__()
46        self.group = group
47        self.method = method
48
49    def __repr__(self):
50        return "face.NoSuchMethodError(%s, %s)" % (
51            self.group,
52            self.method,
53        )
54
55
56class Abortion(
57    collections.namedtuple(
58        "Abortion",
59        (
60            "kind",
61            "initial_metadata",
62            "terminal_metadata",
63            "code",
64            "details",
65        ),
66    )
67):
68    """A value describing RPC abortion.
69
70    Attributes:
71      kind: A Kind value identifying how the RPC failed.
72      initial_metadata: The initial metadata from the other side of the RPC or
73        None if no initial metadata value was received.
74      terminal_metadata: The terminal metadata from the other side of the RPC or
75        None if no terminal metadata value was received.
76      code: The code value from the other side of the RPC or None if no code value
77        was received.
78      details: The details value from the other side of the RPC or None if no
79        details value was received.
80    """
81
82    @enum.unique
83    class Kind(enum.Enum):
84        """Types of RPC abortion."""
85
86        CANCELLED = "cancelled"
87        EXPIRED = "expired"
88        LOCAL_SHUTDOWN = "local shutdown"
89        REMOTE_SHUTDOWN = "remote shutdown"
90        NETWORK_FAILURE = "network failure"
91        LOCAL_FAILURE = "local failure"
92        REMOTE_FAILURE = "remote failure"
93
94
95class AbortionError(Exception, metaclass=abc.ABCMeta):
96    """Common super type for exceptions indicating RPC abortion.
97
98    initial_metadata: The initial metadata from the other side of the RPC or
99      None if no initial metadata value was received.
100    terminal_metadata: The terminal metadata from the other side of the RPC or
101      None if no terminal metadata value was received.
102    code: The code value from the other side of the RPC or None if no code value
103      was received.
104    details: The details value from the other side of the RPC or None if no
105      details value was received.
106    """
107
108    def __init__(self, initial_metadata, terminal_metadata, code, details):
109        super(AbortionError, self).__init__()
110        self.initial_metadata = initial_metadata
111        self.terminal_metadata = terminal_metadata
112        self.code = code
113        self.details = details
114
115    def __str__(self):
116        return '%s(code=%s, details="%s")' % (
117            self.__class__.__name__,
118            self.code,
119            self.details,
120        )
121
122
123class CancellationError(AbortionError):
124    """Indicates that an RPC has been cancelled."""
125
126
127class ExpirationError(AbortionError):
128    """Indicates that an RPC has expired ("timed out")."""
129
130
131class LocalShutdownError(AbortionError):
132    """Indicates that an RPC has terminated due to local shutdown of RPCs."""
133
134
135class RemoteShutdownError(AbortionError):
136    """Indicates that an RPC has terminated due to remote shutdown of RPCs."""
137
138
139class NetworkError(AbortionError):
140    """Indicates that some error occurred on the network."""
141
142
143class LocalError(AbortionError):
144    """Indicates that an RPC has terminated due to a local defect."""
145
146
147class RemoteError(AbortionError):
148    """Indicates that an RPC has terminated due to a remote defect."""
149
150
151class RpcContext(abc.ABC):
152    """Provides RPC-related information and action."""
153
154    @abc.abstractmethod
155    def is_active(self):
156        """Describes whether the RPC is active or has terminated."""
157        raise NotImplementedError()
158
159    @abc.abstractmethod
160    def time_remaining(self):
161        """Describes the length of allowed time remaining for the RPC.
162
163        Returns:
164          A nonnegative float indicating the length of allowed time in seconds
165          remaining for the RPC to complete before it is considered to have timed
166          out.
167        """
168        raise NotImplementedError()
169
170    @abc.abstractmethod
171    def add_abortion_callback(self, abortion_callback):
172        """Registers a callback to be called if the RPC is aborted.
173
174        Args:
175          abortion_callback: A callable to be called and passed an Abortion value
176            in the event of RPC abortion.
177        """
178        raise NotImplementedError()
179
180    @abc.abstractmethod
181    def cancel(self):
182        """Cancels the RPC.
183
184        Idempotent and has no effect if the RPC has already terminated.
185        """
186        raise NotImplementedError()
187
188    @abc.abstractmethod
189    def protocol_context(self):
190        """Accesses a custom object specified by an implementation provider.
191
192        Returns:
193          A value specified by the provider of a Face interface implementation
194            affording custom state and behavior.
195        """
196        raise NotImplementedError()
197
198
199class Call(RpcContext, metaclass=abc.ABCMeta):
200    """Invocation-side utility object for an RPC."""
201
202    @abc.abstractmethod
203    def initial_metadata(self):
204        """Accesses the initial metadata from the service-side of the RPC.
205
206        This method blocks until the value is available or is known not to have been
207        emitted from the service-side of the RPC.
208
209        Returns:
210          The initial metadata object emitted by the service-side of the RPC, or
211            None if there was no such value.
212        """
213        raise NotImplementedError()
214
215    @abc.abstractmethod
216    def terminal_metadata(self):
217        """Accesses the terminal metadata from the service-side of the RPC.
218
219        This method blocks until the value is available or is known not to have been
220        emitted from the service-side of the RPC.
221
222        Returns:
223          The terminal metadata object emitted by the service-side of the RPC, or
224            None if there was no such value.
225        """
226        raise NotImplementedError()
227
228    @abc.abstractmethod
229    def code(self):
230        """Accesses the code emitted by the service-side of the RPC.
231
232        This method blocks until the value is available or is known not to have been
233        emitted from the service-side of the RPC.
234
235        Returns:
236          The code object emitted by the service-side of the RPC, or None if there
237            was no such value.
238        """
239        raise NotImplementedError()
240
241    @abc.abstractmethod
242    def details(self):
243        """Accesses the details value emitted by the service-side of the RPC.
244
245        This method blocks until the value is available or is known not to have been
246        emitted from the service-side of the RPC.
247
248        Returns:
249          The details value emitted by the service-side of the RPC, or None if there
250            was no such value.
251        """
252        raise NotImplementedError()
253
254
255class ServicerContext(RpcContext, metaclass=abc.ABCMeta):
256    """A context object passed to method implementations."""
257
258    @abc.abstractmethod
259    def invocation_metadata(self):
260        """Accesses the metadata from the invocation-side of the RPC.
261
262        This method blocks until the value is available or is known not to have been
263        emitted from the invocation-side of the RPC.
264
265        Returns:
266          The metadata object emitted by the invocation-side of the RPC, or None if
267            there was no such value.
268        """
269        raise NotImplementedError()
270
271    @abc.abstractmethod
272    def initial_metadata(self, initial_metadata):
273        """Accepts the service-side initial metadata value of the RPC.
274
275        This method need not be called by method implementations if they have no
276        service-side initial metadata to transmit.
277
278        Args:
279          initial_metadata: The service-side initial metadata value of the RPC to
280            be transmitted to the invocation side of the RPC.
281        """
282        raise NotImplementedError()
283
284    @abc.abstractmethod
285    def terminal_metadata(self, terminal_metadata):
286        """Accepts the service-side terminal metadata value of the RPC.
287
288        This method need not be called by method implementations if they have no
289        service-side terminal metadata to transmit.
290
291        Args:
292          terminal_metadata: The service-side terminal metadata value of the RPC to
293            be transmitted to the invocation side of the RPC.
294        """
295        raise NotImplementedError()
296
297    @abc.abstractmethod
298    def code(self, code):
299        """Accepts the service-side code of the RPC.
300
301        This method need not be called by method implementations if they have no
302        code to transmit.
303
304        Args:
305          code: The code of the RPC to be transmitted to the invocation side of the
306            RPC.
307        """
308        raise NotImplementedError()
309
310    @abc.abstractmethod
311    def details(self, details):
312        """Accepts the service-side details of the RPC.
313
314        This method need not be called by method implementations if they have no
315        service-side details to transmit.
316
317        Args:
318          details: The service-side details value of the RPC to be transmitted to
319            the invocation side of the RPC.
320        """
321        raise NotImplementedError()
322
323
324class ResponseReceiver(abc.ABC):
325    """Invocation-side object used to accept the output of an RPC."""
326
327    @abc.abstractmethod
328    def initial_metadata(self, initial_metadata):
329        """Receives the initial metadata from the service-side of the RPC.
330
331        Args:
332          initial_metadata: The initial metadata object emitted from the
333            service-side of the RPC.
334        """
335        raise NotImplementedError()
336
337    @abc.abstractmethod
338    def response(self, response):
339        """Receives a response from the service-side of the RPC.
340
341        Args:
342          response: A response object emitted from the service-side of the RPC.
343        """
344        raise NotImplementedError()
345
346    @abc.abstractmethod
347    def complete(self, terminal_metadata, code, details):
348        """Receives the completion values emitted from the service-side of the RPC.
349
350        Args:
351          terminal_metadata: The terminal metadata object emitted from the
352            service-side of the RPC.
353          code: The code object emitted from the service-side of the RPC.
354          details: The details object emitted from the service-side of the RPC.
355        """
356        raise NotImplementedError()
357
358
359class UnaryUnaryMultiCallable(abc.ABC):
360    """Affords invoking a unary-unary RPC in any call style."""
361
362    @abc.abstractmethod
363    def __call__(
364        self,
365        request,
366        timeout,
367        metadata=None,
368        with_call=False,
369        protocol_options=None,
370    ):
371        """Synchronously invokes the underlying RPC.
372
373        Args:
374          request: The request value for the RPC.
375          timeout: A duration of time in seconds to allow for the RPC.
376          metadata: A metadata value to be passed to the service-side of
377            the RPC.
378          with_call: Whether or not to include return a Call for the RPC in addition
379            to the response.
380          protocol_options: A value specified by the provider of a Face interface
381            implementation affording custom state and behavior.
382
383        Returns:
384          The response value for the RPC, and a Call for the RPC if with_call was
385            set to True at invocation.
386
387        Raises:
388          AbortionError: Indicating that the RPC was aborted.
389        """
390        raise NotImplementedError()
391
392    @abc.abstractmethod
393    def future(self, request, timeout, metadata=None, protocol_options=None):
394        """Asynchronously invokes the underlying RPC.
395
396        Args:
397          request: The request value for the RPC.
398          timeout: A duration of time in seconds to allow for the RPC.
399          metadata: A metadata value to be passed to the service-side of
400            the RPC.
401          protocol_options: A value specified by the provider of a Face interface
402            implementation affording custom state and behavior.
403
404        Returns:
405          An object that is both a Call for the RPC and a future.Future. In the
406            event of RPC completion, the return Future's result value will be the
407            response value of the RPC. In the event of RPC abortion, the returned
408            Future's exception value will be an AbortionError.
409        """
410        raise NotImplementedError()
411
412    @abc.abstractmethod
413    def event(
414        self,
415        request,
416        receiver,
417        abortion_callback,
418        timeout,
419        metadata=None,
420        protocol_options=None,
421    ):
422        """Asynchronously invokes the underlying RPC.
423
424        Args:
425          request: The request value for the RPC.
426          receiver: A ResponseReceiver to be passed the response data of the RPC.
427          abortion_callback: A callback to be called and passed an Abortion value
428            in the event of RPC abortion.
429          timeout: A duration of time in seconds to allow for the RPC.
430          metadata: A metadata value to be passed to the service-side of
431            the RPC.
432          protocol_options: A value specified by the provider of a Face interface
433            implementation affording custom state and behavior.
434
435        Returns:
436          A Call for the RPC.
437        """
438        raise NotImplementedError()
439
440
441class UnaryStreamMultiCallable(abc.ABC):
442    """Affords invoking a unary-stream RPC in any call style."""
443
444    @abc.abstractmethod
445    def __call__(self, request, timeout, metadata=None, protocol_options=None):
446        """Invokes the underlying RPC.
447
448        Args:
449          request: The request value for the RPC.
450          timeout: A duration of time in seconds to allow for the RPC.
451          metadata: A metadata value to be passed to the service-side of
452            the RPC.
453          protocol_options: A value specified by the provider of a Face interface
454            implementation affording custom state and behavior.
455
456        Returns:
457          An object that is both a Call for the RPC and an iterator of response
458            values. Drawing response values from the returned iterator may raise
459            AbortionError indicating abortion of the RPC.
460        """
461        raise NotImplementedError()
462
463    @abc.abstractmethod
464    def event(
465        self,
466        request,
467        receiver,
468        abortion_callback,
469        timeout,
470        metadata=None,
471        protocol_options=None,
472    ):
473        """Asynchronously invokes the underlying RPC.
474
475        Args:
476          request: The request value for the RPC.
477          receiver: A ResponseReceiver to be passed the response data of the RPC.
478          abortion_callback: A callback to be called and passed an Abortion value
479            in the event of RPC abortion.
480          timeout: A duration of time in seconds to allow for the RPC.
481          metadata: A metadata value to be passed to the service-side of
482            the RPC.
483          protocol_options: A value specified by the provider of a Face interface
484            implementation affording custom state and behavior.
485
486        Returns:
487          A Call object for the RPC.
488        """
489        raise NotImplementedError()
490
491
492class StreamUnaryMultiCallable(abc.ABC):
493    """Affords invoking a stream-unary RPC in any call style."""
494
495    @abc.abstractmethod
496    def __call__(
497        self,
498        request_iterator,
499        timeout,
500        metadata=None,
501        with_call=False,
502        protocol_options=None,
503    ):
504        """Synchronously invokes the underlying RPC.
505
506        Args:
507          request_iterator: An iterator that yields request values for the RPC.
508          timeout: A duration of time in seconds to allow for the RPC.
509          metadata: A metadata value to be passed to the service-side of
510            the RPC.
511          with_call: Whether or not to include return a Call for the RPC in addition
512            to the response.
513          protocol_options: A value specified by the provider of a Face interface
514            implementation affording custom state and behavior.
515
516        Returns:
517          The response value for the RPC, and a Call for the RPC if with_call was
518            set to True at invocation.
519
520        Raises:
521          AbortionError: Indicating that the RPC was aborted.
522        """
523        raise NotImplementedError()
524
525    @abc.abstractmethod
526    def future(
527        self, request_iterator, timeout, metadata=None, protocol_options=None
528    ):
529        """Asynchronously invokes the underlying RPC.
530
531        Args:
532          request_iterator: An iterator that yields request values for the RPC.
533          timeout: A duration of time in seconds to allow for the RPC.
534          metadata: A metadata value to be passed to the service-side of
535            the RPC.
536          protocol_options: A value specified by the provider of a Face interface
537            implementation affording custom state and behavior.
538
539        Returns:
540          An object that is both a Call for the RPC and a future.Future. In the
541            event of RPC completion, the return Future's result value will be the
542            response value of the RPC. In the event of RPC abortion, the returned
543            Future's exception value will be an AbortionError.
544        """
545        raise NotImplementedError()
546
547    @abc.abstractmethod
548    def event(
549        self,
550        receiver,
551        abortion_callback,
552        timeout,
553        metadata=None,
554        protocol_options=None,
555    ):
556        """Asynchronously invokes the underlying RPC.
557
558        Args:
559          receiver: A ResponseReceiver to be passed the response data of the RPC.
560          abortion_callback: A callback to be called and passed an Abortion value
561            in the event of RPC abortion.
562          timeout: A duration of time in seconds to allow for the RPC.
563          metadata: A metadata value to be passed to the service-side of
564            the RPC.
565          protocol_options: A value specified by the provider of a Face interface
566            implementation affording custom state and behavior.
567
568        Returns:
569          A single object that is both a Call object for the RPC and a
570            stream.Consumer to which the request values of the RPC should be passed.
571        """
572        raise NotImplementedError()
573
574
575class StreamStreamMultiCallable(abc.ABC):
576    """Affords invoking a stream-stream RPC in any call style."""
577
578    @abc.abstractmethod
579    def __call__(
580        self, request_iterator, timeout, metadata=None, protocol_options=None
581    ):
582        """Invokes the underlying RPC.
583
584        Args:
585          request_iterator: An iterator that yields request values for the RPC.
586          timeout: A duration of time in seconds to allow for the RPC.
587          metadata: A metadata value to be passed to the service-side of
588            the RPC.
589          protocol_options: A value specified by the provider of a Face interface
590            implementation affording custom state and behavior.
591
592        Returns:
593          An object that is both a Call for the RPC and an iterator of response
594            values. Drawing response values from the returned iterator may raise
595            AbortionError indicating abortion of the RPC.
596        """
597        raise NotImplementedError()
598
599    @abc.abstractmethod
600    def event(
601        self,
602        receiver,
603        abortion_callback,
604        timeout,
605        metadata=None,
606        protocol_options=None,
607    ):
608        """Asynchronously invokes the underlying RPC.
609
610        Args:
611          receiver: A ResponseReceiver to be passed the response data of the RPC.
612          abortion_callback: A callback to be called and passed an Abortion value
613            in the event of RPC abortion.
614          timeout: A duration of time in seconds to allow for the RPC.
615          metadata: A metadata value to be passed to the service-side of
616            the RPC.
617          protocol_options: A value specified by the provider of a Face interface
618            implementation affording custom state and behavior.
619
620        Returns:
621          A single object that is both a Call object for the RPC and a
622            stream.Consumer to which the request values of the RPC should be passed.
623        """
624        raise NotImplementedError()
625
626
627class MethodImplementation(abc.ABC):
628    """A sum type that describes a method implementation.
629
630    Attributes:
631      cardinality: A cardinality.Cardinality value.
632      style: A style.Service value.
633      unary_unary_inline: The implementation of the method as a callable value
634        that takes a request value and a ServicerContext object and returns a
635        response value. Only non-None if cardinality is
636        cardinality.Cardinality.UNARY_UNARY and style is style.Service.INLINE.
637      unary_stream_inline: The implementation of the method as a callable value
638        that takes a request value and a ServicerContext object and returns an
639        iterator of response values. Only non-None if cardinality is
640        cardinality.Cardinality.UNARY_STREAM and style is style.Service.INLINE.
641      stream_unary_inline: The implementation of the method as a callable value
642        that takes an iterator of request values and a ServicerContext object and
643        returns a response value. Only non-None if cardinality is
644        cardinality.Cardinality.STREAM_UNARY and style is style.Service.INLINE.
645      stream_stream_inline: The implementation of the method as a callable value
646        that takes an iterator of request values and a ServicerContext object and
647        returns an iterator of response values. Only non-None if cardinality is
648        cardinality.Cardinality.STREAM_STREAM and style is style.Service.INLINE.
649      unary_unary_event: The implementation of the method as a callable value that
650        takes a request value, a response callback to which to pass the response
651        value of the RPC, and a ServicerContext. Only non-None if cardinality is
652        cardinality.Cardinality.UNARY_UNARY and style is style.Service.EVENT.
653      unary_stream_event: The implementation of the method as a callable value
654        that takes a request value, a stream.Consumer to which to pass the
655        response values of the RPC, and a ServicerContext. Only non-None if
656        cardinality is cardinality.Cardinality.UNARY_STREAM and style is
657        style.Service.EVENT.
658      stream_unary_event: The implementation of the method as a callable value
659        that takes a response callback to which to pass the response value of the
660        RPC and a ServicerContext and returns a stream.Consumer to which the
661        request values of the RPC should be passed. Only non-None if cardinality
662        is cardinality.Cardinality.STREAM_UNARY and style is style.Service.EVENT.
663      stream_stream_event: The implementation of the method as a callable value
664        that takes a stream.Consumer to which to pass the response values of the
665        RPC and a ServicerContext and returns a stream.Consumer to which the
666        request values of the RPC should be passed. Only non-None if cardinality
667        is cardinality.Cardinality.STREAM_STREAM and style is
668        style.Service.EVENT.
669    """
670
671
672class MultiMethodImplementation(abc.ABC):
673    """A general type able to service many methods."""
674
675    @abc.abstractmethod
676    def service(self, group, method, response_consumer, context):
677        """Services an RPC.
678
679        Args:
680          group: The group identifier of the RPC.
681          method: The method identifier of the RPC.
682          response_consumer: A stream.Consumer to be called to accept the response
683            values of the RPC.
684          context: a ServicerContext object.
685
686        Returns:
687          A stream.Consumer with which to accept the request values of the RPC. The
688            consumer returned from this method may or may not be invoked to
689            completion: in the case of RPC abortion, RPC Framework will simply stop
690            passing values to this object. Implementations must not assume that this
691            object will be called to completion of the request stream or even called
692            at all.
693
694        Raises:
695          abandonment.Abandoned: May or may not be raised when the RPC has been
696            aborted.
697          NoSuchMethodError: If this MultiMethod does not recognize the given group
698            and name for the RPC and is not able to service the RPC.
699        """
700        raise NotImplementedError()
701
702
703class GenericStub(abc.ABC):
704    """Affords RPC invocation via generic methods."""
705
706    @abc.abstractmethod
707    def blocking_unary_unary(
708        self,
709        group,
710        method,
711        request,
712        timeout,
713        metadata=None,
714        with_call=False,
715        protocol_options=None,
716    ):
717        """Invokes a unary-request-unary-response method.
718
719        This method blocks until either returning the response value of the RPC
720        (in the event of RPC completion) or raising an exception (in the event of
721        RPC abortion).
722
723        Args:
724          group: The group identifier of the RPC.
725          method: The method identifier of the RPC.
726          request: The request value for the RPC.
727          timeout: A duration of time in seconds to allow for the RPC.
728          metadata: A metadata value to be passed to the service-side of the RPC.
729          with_call: Whether or not to include return a Call for the RPC in addition
730            to the response.
731          protocol_options: A value specified by the provider of a Face interface
732            implementation affording custom state and behavior.
733
734        Returns:
735          The response value for the RPC, and a Call for the RPC if with_call was
736            set to True at invocation.
737
738        Raises:
739          AbortionError: Indicating that the RPC was aborted.
740        """
741        raise NotImplementedError()
742
743    @abc.abstractmethod
744    def future_unary_unary(
745        self,
746        group,
747        method,
748        request,
749        timeout,
750        metadata=None,
751        protocol_options=None,
752    ):
753        """Invokes a unary-request-unary-response method.
754
755        Args:
756          group: The group identifier of the RPC.
757          method: The method identifier of the RPC.
758          request: The request value for the RPC.
759          timeout: A duration of time in seconds to allow for the RPC.
760          metadata: A metadata value to be passed to the service-side of the RPC.
761          protocol_options: A value specified by the provider of a Face interface
762            implementation affording custom state and behavior.
763
764        Returns:
765          An object that is both a Call for the RPC and a future.Future. In the
766            event of RPC completion, the return Future's result value will be the
767            response value of the RPC. In the event of RPC abortion, the returned
768            Future's exception value will be an AbortionError.
769        """
770        raise NotImplementedError()
771
772    @abc.abstractmethod
773    def inline_unary_stream(
774        self,
775        group,
776        method,
777        request,
778        timeout,
779        metadata=None,
780        protocol_options=None,
781    ):
782        """Invokes a unary-request-stream-response method.
783
784        Args:
785          group: The group identifier of the RPC.
786          method: The method identifier of the RPC.
787          request: The request value for the RPC.
788          timeout: A duration of time in seconds to allow for the RPC.
789          metadata: A metadata value to be passed to the service-side of the RPC.
790          protocol_options: A value specified by the provider of a Face interface
791            implementation affording custom state and behavior.
792
793        Returns:
794          An object that is both a Call for the RPC and an iterator of response
795            values. Drawing response values from the returned iterator may raise
796            AbortionError indicating abortion of the RPC.
797        """
798        raise NotImplementedError()
799
800    @abc.abstractmethod
801    def blocking_stream_unary(
802        self,
803        group,
804        method,
805        request_iterator,
806        timeout,
807        metadata=None,
808        with_call=False,
809        protocol_options=None,
810    ):
811        """Invokes a stream-request-unary-response method.
812
813        This method blocks until either returning the response value of the RPC
814        (in the event of RPC completion) or raising an exception (in the event of
815        RPC abortion).
816
817        Args:
818          group: The group identifier of the RPC.
819          method: The method identifier of the RPC.
820          request_iterator: An iterator that yields request values for the RPC.
821          timeout: A duration of time in seconds to allow for the RPC.
822          metadata: A metadata value to be passed to the service-side of the RPC.
823          with_call: Whether or not to include return a Call for the RPC in addition
824            to the response.
825          protocol_options: A value specified by the provider of a Face interface
826            implementation affording custom state and behavior.
827
828        Returns:
829          The response value for the RPC, and a Call for the RPC if with_call was
830            set to True at invocation.
831
832        Raises:
833          AbortionError: Indicating that the RPC was aborted.
834        """
835        raise NotImplementedError()
836
837    @abc.abstractmethod
838    def future_stream_unary(
839        self,
840        group,
841        method,
842        request_iterator,
843        timeout,
844        metadata=None,
845        protocol_options=None,
846    ):
847        """Invokes a stream-request-unary-response method.
848
849        Args:
850          group: The group identifier of the RPC.
851          method: The method identifier of the RPC.
852          request_iterator: An iterator that yields request values for the RPC.
853          timeout: A duration of time in seconds to allow for the RPC.
854          metadata: A metadata value to be passed to the service-side of the RPC.
855          protocol_options: A value specified by the provider of a Face interface
856            implementation affording custom state and behavior.
857
858        Returns:
859          An object that is both a Call for the RPC and a future.Future. In the
860            event of RPC completion, the return Future's result value will be the
861            response value of the RPC. In the event of RPC abortion, the returned
862            Future's exception value will be an AbortionError.
863        """
864        raise NotImplementedError()
865
866    @abc.abstractmethod
867    def inline_stream_stream(
868        self,
869        group,
870        method,
871        request_iterator,
872        timeout,
873        metadata=None,
874        protocol_options=None,
875    ):
876        """Invokes a stream-request-stream-response method.
877
878        Args:
879          group: The group identifier of the RPC.
880          method: The method identifier of the RPC.
881          request_iterator: An iterator that yields request values for the RPC.
882          timeout: A duration of time in seconds to allow for the RPC.
883          metadata: A metadata value to be passed to the service-side of the RPC.
884          protocol_options: A value specified by the provider of a Face interface
885            implementation affording custom state and behavior.
886
887        Returns:
888          An object that is both a Call for the RPC and an iterator of response
889            values. Drawing response values from the returned iterator may raise
890            AbortionError indicating abortion of the RPC.
891        """
892        raise NotImplementedError()
893
894    @abc.abstractmethod
895    def event_unary_unary(
896        self,
897        group,
898        method,
899        request,
900        receiver,
901        abortion_callback,
902        timeout,
903        metadata=None,
904        protocol_options=None,
905    ):
906        """Event-driven invocation of a unary-request-unary-response method.
907
908        Args:
909          group: The group identifier of the RPC.
910          method: The method identifier of the RPC.
911          request: The request value for the RPC.
912          receiver: A ResponseReceiver to be passed the response data of the RPC.
913          abortion_callback: A callback to be called and passed an Abortion value
914            in the event of RPC abortion.
915          timeout: A duration of time in seconds to allow for the RPC.
916          metadata: A metadata value to be passed to the service-side of the RPC.
917          protocol_options: A value specified by the provider of a Face interface
918            implementation affording custom state and behavior.
919
920        Returns:
921          A Call for the RPC.
922        """
923        raise NotImplementedError()
924
925    @abc.abstractmethod
926    def event_unary_stream(
927        self,
928        group,
929        method,
930        request,
931        receiver,
932        abortion_callback,
933        timeout,
934        metadata=None,
935        protocol_options=None,
936    ):
937        """Event-driven invocation of a unary-request-stream-response method.
938
939        Args:
940          group: The group identifier of the RPC.
941          method: The method identifier of the RPC.
942          request: The request value for the RPC.
943          receiver: A ResponseReceiver to be passed the response data of the RPC.
944          abortion_callback: A callback to be called and passed an Abortion value
945            in the event of RPC abortion.
946          timeout: A duration of time in seconds to allow for the RPC.
947          metadata: A metadata value to be passed to the service-side of the RPC.
948          protocol_options: A value specified by the provider of a Face interface
949            implementation affording custom state and behavior.
950
951        Returns:
952          A Call for the RPC.
953        """
954        raise NotImplementedError()
955
956    @abc.abstractmethod
957    def event_stream_unary(
958        self,
959        group,
960        method,
961        receiver,
962        abortion_callback,
963        timeout,
964        metadata=None,
965        protocol_options=None,
966    ):
967        """Event-driven invocation of a unary-request-unary-response method.
968
969        Args:
970          group: The group identifier of the RPC.
971          method: The method identifier of the RPC.
972          receiver: A ResponseReceiver to be passed the response data of the RPC.
973          abortion_callback: A callback to be called and passed an Abortion value
974            in the event of RPC abortion.
975          timeout: A duration of time in seconds to allow for the RPC.
976          metadata: A metadata value to be passed to the service-side of the RPC.
977          protocol_options: A value specified by the provider of a Face interface
978            implementation affording custom state and behavior.
979
980        Returns:
981          A pair of a Call object for the RPC and a stream.Consumer to which the
982            request values of the RPC should be passed.
983        """
984        raise NotImplementedError()
985
986    @abc.abstractmethod
987    def event_stream_stream(
988        self,
989        group,
990        method,
991        receiver,
992        abortion_callback,
993        timeout,
994        metadata=None,
995        protocol_options=None,
996    ):
997        """Event-driven invocation of a unary-request-stream-response method.
998
999        Args:
1000          group: The group identifier of the RPC.
1001          method: The method identifier of the RPC.
1002          receiver: A ResponseReceiver to be passed the response data of the RPC.
1003          abortion_callback: A callback to be called and passed an Abortion value
1004            in the event of RPC abortion.
1005          timeout: A duration of time in seconds to allow for the RPC.
1006          metadata: A metadata value to be passed to the service-side of the RPC.
1007          protocol_options: A value specified by the provider of a Face interface
1008            implementation affording custom state and behavior.
1009
1010        Returns:
1011          A pair of a Call object for the RPC and a stream.Consumer to which the
1012            request values of the RPC should be passed.
1013        """
1014        raise NotImplementedError()
1015
1016    @abc.abstractmethod
1017    def unary_unary(self, group, method):
1018        """Creates a UnaryUnaryMultiCallable for a unary-unary method.
1019
1020        Args:
1021          group: The group identifier of the RPC.
1022          method: The method identifier of the RPC.
1023
1024        Returns:
1025          A UnaryUnaryMultiCallable value for the named unary-unary method.
1026        """
1027        raise NotImplementedError()
1028
1029    @abc.abstractmethod
1030    def unary_stream(self, group, method):
1031        """Creates a UnaryStreamMultiCallable for a unary-stream method.
1032
1033        Args:
1034          group: The group identifier of the RPC.
1035          method: The method identifier of the RPC.
1036
1037        Returns:
1038          A UnaryStreamMultiCallable value for the name unary-stream method.
1039        """
1040        raise NotImplementedError()
1041
1042    @abc.abstractmethod
1043    def stream_unary(self, group, method):
1044        """Creates a StreamUnaryMultiCallable for a stream-unary method.
1045
1046        Args:
1047          group: The group identifier of the RPC.
1048          method: The method identifier of the RPC.
1049
1050        Returns:
1051          A StreamUnaryMultiCallable value for the named stream-unary method.
1052        """
1053        raise NotImplementedError()
1054
1055    @abc.abstractmethod
1056    def stream_stream(self, group, method):
1057        """Creates a StreamStreamMultiCallable for a stream-stream method.
1058
1059        Args:
1060          group: The group identifier of the RPC.
1061          method: The method identifier of the RPC.
1062
1063        Returns:
1064          A StreamStreamMultiCallable value for the named stream-stream method.
1065        """
1066        raise NotImplementedError()
1067
1068
1069class DynamicStub(abc.ABC):
1070    """Affords RPC invocation via attributes corresponding to afforded methods.
1071
1072    Instances of this type may be scoped to a single group so that attribute
1073    access is unambiguous.
1074
1075    Instances of this type respond to attribute access as follows: if the
1076    requested attribute is the name of a unary-unary method, the value of the
1077    attribute will be a UnaryUnaryMultiCallable with which to invoke an RPC; if
1078    the requested attribute is the name of a unary-stream method, the value of the
1079    attribute will be a UnaryStreamMultiCallable with which to invoke an RPC; if
1080    the requested attribute is the name of a stream-unary method, the value of the
1081    attribute will be a StreamUnaryMultiCallable with which to invoke an RPC; and
1082    if the requested attribute is the name of a stream-stream method, the value of
1083    the attribute will be a StreamStreamMultiCallable with which to invoke an RPC.
1084    """
1085