base.py 2.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119
  1. """
  2. :mod:`websockets.extensions.base` defines abstract classes for implementing
  3. extensions.
  4. See `section 9 of RFC 6455`_.
  5. .. _section 9 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-9
  6. """
  7. from typing import List, Optional, Sequence, Tuple
  8. from ..frames import Frame
  9. from ..typing import ExtensionName, ExtensionParameter
  10. __all__ = ["Extension", "ClientExtensionFactory", "ServerExtensionFactory"]
  11. class Extension:
  12. """
  13. Abstract class for extensions.
  14. """
  15. @property
  16. def name(self) -> ExtensionName:
  17. """
  18. Extension identifier.
  19. """
  20. def decode(self, frame: Frame, *, max_size: Optional[int] = None) -> Frame:
  21. """
  22. Decode an incoming frame.
  23. :param frame: incoming frame
  24. :param max_size: maximum payload size in bytes
  25. """
  26. def encode(self, frame: Frame) -> Frame:
  27. """
  28. Encode an outgoing frame.
  29. :param frame: outgoing frame
  30. """
  31. class ClientExtensionFactory:
  32. """
  33. Abstract class for client-side extension factories.
  34. """
  35. @property
  36. def name(self) -> ExtensionName:
  37. """
  38. Extension identifier.
  39. """
  40. def get_request_params(self) -> List[ExtensionParameter]:
  41. """
  42. Build request parameters.
  43. Return a list of ``(name, value)`` pairs.
  44. """
  45. def process_response_params(
  46. self,
  47. params: Sequence[ExtensionParameter],
  48. accepted_extensions: Sequence[Extension],
  49. ) -> Extension:
  50. """
  51. Process response parameters received from the server.
  52. :param params: list of ``(name, value)`` pairs.
  53. :param accepted_extensions: list of previously accepted extensions.
  54. :raises ~websockets.exceptions.NegotiationError: if parameters aren't
  55. acceptable
  56. """
  57. class ServerExtensionFactory:
  58. """
  59. Abstract class for server-side extension factories.
  60. """
  61. @property
  62. def name(self) -> ExtensionName:
  63. """
  64. Extension identifier.
  65. """
  66. def process_request_params(
  67. self,
  68. params: Sequence[ExtensionParameter],
  69. accepted_extensions: Sequence[Extension],
  70. ) -> Tuple[List[ExtensionParameter], Extension]:
  71. """
  72. Process request parameters received from the client.
  73. To accept the offer, return a 2-uple containing:
  74. - response parameters: a list of ``(name, value)`` pairs
  75. - an extension: an instance of a subclass of :class:`Extension`
  76. :param params: list of ``(name, value)`` pairs.
  77. :param accepted_extensions: list of previously accepted extensions.
  78. :raises ~websockets.exceptions.NegotiationError: to reject the offer,
  79. if parameters aren't acceptable
  80. """