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