API
***


Design
======

"websockets" provides complete client and server implementations, as
shown in the getting started guide. These functions are built on top
of low-level APIs reflecting the two phases of the WebSocket protocol:

1. An opening handshake, in the form of an HTTP Upgrade request;

2. Data transfer, as framed messages, ending with a closing
   handshake.

The first phase is designed to integrate with existing HTTP software.
"websockets" provides functions to build and validate the request and
response headers.

The second phase is the core of the WebSocket protocol. "websockets"
provides a standalone implementation on top of "asyncio" with a very
simple API.

For convenience, public APIs can be imported directly from the
"websockets" package, unless noted otherwise. Anything that isn't
listed in this document is a private API.


High-level
==========


Server
------

The "websockets.server" module defines a simple WebSocket server API.

websockets.server.serve(ws_handler, host=None, port=None, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)

   Create, start, and return a "WebSocketServer".

   "serve()" returns an awaitable. Awaiting it yields an instance of
   "WebSocketServer" which provides "close()" and "wait_closed()"
   methods for terminating the server and cleaning up its resources.

   On Python ≥ 3.5, "serve()" can also be used as an asynchronous
   context manager. In this case, the server is shut down when exiting
   the context.

   "serve()" is a wrapper around the event loop's "create_server()"
   method. Internally, it creates and starts a "Server" object by
   calling "create_server()". The "WebSocketServer" it returns keeps a
   reference to this object.

   The "ws_handler" argument is the WebSocket handler. It must be a
   coroutine accepting two arguments: a "WebSocketServerProtocol" and
   the request URI.

   The "host" and "port" arguments, as well as unrecognized keyword
   arguments, are passed along to "create_server()". For example, you
   can set the "ssl" keyword argument to a "SSLContext" to enable TLS.

   The "create_protocol" parameter allows customizing the asyncio
   protocol that manages the connection. It should be a callable or
   class accepting the same arguments as "WebSocketServerProtocol" and
   returning a "WebSocketServerProtocol" instance. It defaults to
   "WebSocketServerProtocol".

   The behavior of the "ping_interval", "ping_timeout",
   "close_timeout", "max_size", "max_queue", "read_limit", and
   "write_limit" optional arguments is described in the documentation
   of "WebSocketCommonProtocol".

   "serve()" also accepts the following optional arguments:

   * "compression" is a shortcut to configure compression
     extensions; by default it enables the "permessage-deflate"
     extension; set it to "None" to disable compression

   * "origins" defines acceptable Origin HTTP headers — include
     "None" if the lack of an origin is acceptable

   * "extensions" is a list of supported extensions in order of
     decreasing preference

   * "subprotocols" is a list of supported subprotocols in order of
     decreasing preference

   * "extra_headers" sets additional HTTP response headers — it can
     be a "Headers" instance, a "Mapping", an iterable of "(name,
     value)" pairs, or a callable taking the request path and headers
     in arguments and returning one of the above

   * "process_request" is a callable or a coroutine taking the
     request path and headers in argument, see "process_request()" for
     details

   * "select_subprotocol" is a callable taking the subprotocols
     offered by the client and available on the server in argument,
     see "select_subprotocol()" for details

   Whenever a client connects, the server accepts the connection,
   creates a "WebSocketServerProtocol", performs the opening
   handshake, and delegates to the WebSocket handler. Once the handler
   completes, the server performs the closing handshake and closes the
   connection.

   When a server is closed with "close()", it closes all connections
   with close code 1001 (going away). WebSocket handlers — which are
   running the coroutine passed in the "ws_handler" — will receive a
   "ConnectionClosed" exception on their current or next interaction
   with the WebSocket connection.

   Since there's no useful way to propagate exceptions triggered in
   handlers, they're sent to the "'websockets.server'" logger instead.
   Debugging is much easier if you configure logging to print them:

      import logging
      logger = logging.getLogger('websockets.server')
      logger.setLevel(logging.ERROR)
      logger.addHandler(logging.StreamHandler())

websockets.server.unix_serve(ws_handler, path, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)

   Similar to "serve()", but for listening on Unix sockets.

   This function calls the event loop's "create_unix_server()" method.

   It is only available on Unix.

   It's useful for deploying a server behind a reverse proxy such as
   nginx.

class websockets.server.WebSocketServer(loop)

   Wrapper for "Server" that closes connections on exit.

   This class provides the return type of "serve()".

   It mimics the interface of "AbstractServer", namely its "close()"
   and "wait_closed()" methods, to close WebSocket connections
   properly on exit, in addition to closing the underlying "Server".

   Instances of this class store a reference to the "Server" object
   returned by "create_server()" rather than inherit from "Server" in
   part because "create_server()" doesn't support passing a custom
   "Server" class.

   close()

      Close the server and terminate connections with close code 1001.

      This method is idempotent.

   wait_closed()

      Wait until the server is closed and all connections are
      terminated.

      When "wait_closed()" returns, all TCP connections are closed and
      there are no pending tasks left.

   sockets

      List of "socket" objects the server is listening to.

      "None" if the server is closed.

class websockets.server.WebSocketServerProtocol(ws_handler, ws_server, *, host=None, port=None, secure=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None)

   Complete WebSocket server implementation as an "asyncio.Protocol".

   This class inherits most of its methods from
   "WebSocketCommonProtocol".

   For the sake of simplicity, it doesn't rely on a full HTTP
   implementation. Its support for HTTP responses is very limited.

   handshake(origins=None, available_extensions=None, available_subprotocols=None, extra_headers=None)

      Perform the server side of the opening handshake.

      If provided, "origins" is a list of acceptable HTTP Origin
      values. Include "None" if the lack of an origin is acceptable.

      If provided, "available_extensions" is a list of supported
      extensions in the order in which they should be used.

      If provided, "available_subprotocols" is a list of supported
      subprotocols in order of decreasing preference.

      If provided, "extra_headers" sets additional HTTP response
      headers. It can be a "Headers" instance, a "Mapping", an
      iterable of "(name, value)" pairs, or a callable taking the
      request path and headers in arguments and returning one of the
      above.

      Raise "InvalidHandshake" if the handshake fails.

      Return the path of the URI of the request.

   process_request(path, request_headers)

      Intercept the HTTP request and return an HTTP response if
      needed.

      "request_headers" is a "Headers" instance.

      If this coroutine returns "None", the WebSocket handshake
      continues. If it returns a status code, headers and a response
      body, that HTTP response is sent and the connection is closed.

      The HTTP status must be a "HTTPStatus". ("HTTPStatus" was added
      in Python 3.5. Use a compatible object on earlier versions. Look
      at "SWITCHING_PROTOCOLS" in "websockets.compatibility" for an
      example.)

      HTTP headers must be a "Headers" instance, a "Mapping", or an
      iterable of "(name, value)" pairs.

      The HTTP response body must be "bytes". It may be empty.

      This method may be overridden to check the request headers and
      set a different status, for example to authenticate the request
      and return "HTTPStatus.UNAUTHORIZED" or "HTTPStatus.FORBIDDEN".

      It is declared as a coroutine because such authentication checks
      are likely to require network requests.

      This coroutine may be overridden by passing a "process_request"
      argument to the "WebSocketServerProtocol" constructor or the
      "serve()" function.

   static select_subprotocol(client_subprotocols, server_subprotocols)

      Pick a subprotocol among those offered by the client.

      If several subprotocols are supported by the client and the
      server, the default implementation selects the preferred
      subprotocols by giving equal value to the priorities of the
      client and the server.

      If no subprotocols are supported by the client and the server,
      it proceeds without a subprotocol.

      This is unlikely to be the most useful implementation in
      practice, as many servers providing a subprotocol will require
      that the client uses that subprotocol. Such rules can be
      implemented in a subclass.

      This method may be overridden by passing a "select_subprotocol"
      argument to the "WebSocketServerProtocol" constructor or the
      "serve()" function.


Client
------

The "websockets.client" module defines a simple WebSocket client API.

websockets.client.connect(uri, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, **kwds)

   Connect to the WebSocket server at the given "uri".

   "connect()" returns an awaitable. Awaiting it yields an instance of
   "WebSocketClientProtocol" which can then be used to send and
   receive messages.

   On Python ≥ 3.5.1, "connect()" can be used as a asynchronous
   context manager. In that case, the connection is closed when
   exiting the context.

   "connect()" is a wrapper around the event loop's
   "create_connection()" method. Unknown keyword arguments are passed
   to "create_connection()".

   For example, you can set the "ssl" keyword argument to a
   "SSLContext" to enforce some TLS settings. When connecting to a
   "wss://" URI, if this argument isn't provided explicitly, it's set
   to "True", which means Python's default "SSLContext" is used.

   The behavior of the "ping_interval", "ping_timeout",
   "close_timeout", "max_size", "max_queue", "read_limit", and
   "write_limit" optional arguments is described in the documentation
   of "WebSocketCommonProtocol".

   The "create_protocol" parameter allows customizing the asyncio
   protocol that manages the connection. It should be a callable or
   class accepting the same arguments as "WebSocketClientProtocol" and
   returning a "WebSocketClientProtocol" instance. It defaults to
   "WebSocketClientProtocol".

   "connect()" also accepts the following optional arguments:

   * "compression" is a shortcut to configure compression
     extensions; by default it enables the "permessage-deflate"
     extension; set it to "None" to disable compression

   * "origin" sets the Origin HTTP header

   * "extensions" is a list of supported extensions in order of
     decreasing preference

   * "subprotocols" is a list of supported subprotocols in order of
     decreasing preference

   * "extra_headers" sets additional HTTP request headers – it can
     be a "Headers" instance, a "Mapping", or an iterable of "(name,
     value)" pairs

   "connect()" raises "InvalidURI" if "uri" is invalid and
   "InvalidHandshake" if the opening handshake fails.

class websockets.client.WebSocketClientProtocol(*, host=None, port=None, secure=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origin=None, extensions=None, subprotocols=None, extra_headers=None)

   Complete WebSocket client implementation as an "asyncio.Protocol".

   This class inherits most of its methods from
   "WebSocketCommonProtocol".

   handshake(wsuri, origin=None, available_extensions=None, available_subprotocols=None, extra_headers=None)

      Perform the client side of the opening handshake.

      If provided, "origin" sets the Origin HTTP header.

      If provided, "available_extensions" is a list of supported
      extensions in the order in which they should be used.

      If provided, "available_subprotocols" is a list of supported
      subprotocols in order of decreasing preference.

      If provided, "extra_headers" sets additional HTTP request
      headers. It must be a "Headers" instance, a "Mapping", or an
      iterable of "(name, value)" pairs.

      Raise "InvalidHandshake" if the handshake fails.


Shared
------

The "websockets.protocol" module handles WebSocket control and data
frames as specified in sections 4 to 8 of RFC 6455.

class websockets.protocol.WebSocketCommonProtocol(*, host=None, port=None, secure=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None)

   This class implements common parts of the WebSocket protocol.

   It assumes that the WebSocket connection is established. The
   handshake is managed in subclasses such as
   "WebSocketServerProtocol" and "WebSocketClientProtocol".

   It runs a task that stores incoming data frames in a queue and
   deals with control frames automatically. It sends outgoing data
   frames and performs the closing handshake.

   On Python ≥ 3.6, "WebSocketCommonProtocol" instances support
   asynchronous iteration:

      async for message in websocket:
          await process(message)

   The iterator yields incoming messages. It exits normally when the
   connection is closed with the close code 1000 (OK) or 1001 (going
   away). It raises a "ConnectionClosed" exception when the connection
   is closed with any other status code.

   The "host", "port" and "secure" parameters are simply stored as
   attributes for handlers that need them.

   Once the connection is open, a Ping frame is sent every
   "ping_interval" seconds. This serves as a keepalive. It helps
   keeping the connection open, especially in the presence of proxies
   with short timeouts. Set "ping_interval" to "None" to disable this
   behavior.

   If the corresponding Pong frame isn't received within
   "ping_timeout" seconds, the connection is considered unusable and
   is closed with status code 1011. This ensures that the remote
   endpoint remains responsive. Set "ping_timeout" to "None" to
   disable this behavior.

   The "close_timeout" parameter defines a maximum wait time in
   seconds for completing the closing handshake and terminating the
   TCP connection. "close()" completes in at most "4 * close_timeout"
   on the server side and "5 * close_timeout" on the client side.

   "close_timeout" needs to be a parameter of the protocol because
   websockets usually calls "close()" implicitly:

   * on the server side, when the connection handler terminates,

   * on the client side, when exiting the context manager for the
     connection.

   To apply a timeout to any other API, wrap it in "wait_for()".

   The "max_size" parameter enforces the maximum size for incoming
   messages in bytes. The default value is 1MB. "None" disables the
   limit. If a message larger than the maximum size is received,
   "recv()" will raise "ConnectionClosed" and the connection will be
   closed with status code 1009.

   The "max_queue" parameter sets the maximum length of the queue that
   holds incoming messages. The default value is 32. 0 disables the
   limit. Messages are added to an in-memory queue when they're
   received; then "recv()" pops from that queue. In order to prevent
   excessive memory consumption when messages are received faster than
   they can be processed, the queue must be bounded. If the queue
   fills up, the protocol stops processing incoming data until
   "recv()" is called. In this situation, various receive buffers (at
   least in "asyncio" and in the OS) will fill up, then the TCP
   receive window will shrink, slowing down transmission to avoid
   packet loss.

   Since Python can use up to 4 bytes of memory to represent a single
   character, each websocket connection may use up to "4 * max_size *
   max_queue" bytes of memory to store incoming messages. By default,
   this is 128MB. You may want to lower the limits, depending on your
   application's requirements.

   The "read_limit" argument sets the high-water limit of the buffer
   for incoming bytes. The low-water limit is half the high-water
   limit. The default value is 64kB, half of asyncio's default (based
   on the current implementation of "StreamReader").

   The "write_limit" argument sets the high-water limit of the buffer
   for outgoing bytes. The low-water limit is a quarter of the high-
   water limit. The default value is 64kB, equal to asyncio's default
   (based on the current implementation of "FlowControlMixin").

   As soon as the HTTP request and response in the opening handshake
   are processed:

   * the request path is available in the "path" attribute;

   * the request and response HTTP headers are available in the
     "request_headers" and "response_headers" attributes, which are
     "Headers" instances.

   These attributes must be treated as immutable.

   If a subprotocol was negotiated, it's available in the
   "subprotocol" attribute.

   Once the connection is closed, the status code is available in the
   "close_code" attribute and the reason in "close_reason".

   close(code=1000, reason='')

      This coroutine performs the closing handshake.

      It waits for the other end to complete the handshake and for the
      TCP connection to terminate. As a consequence, there's no need
      to await "wait_closed()"; "close()" already does it.

      "close()" is idempotent: it doesn't do anything once the
      connection is closed.

      It's safe to wrap this coroutine in "ensure_future()" since
      errors during connection termination aren't particularly useful.

      "code" must be an "int" and "reason" a "str".

   wait_closed(code=1000, reason='')

      Wait until the connection is closed.

      This is identical to "closed", except it can be awaited.

      This can make it easier to handle connection termination,
      regardless of its cause, in tasks that interact with the
      WebSocket connection.

   recv()

      This coroutine receives the next message.

      It returns a "str" for a text frame and "bytes" for a binary
      frame.

      When the end of the message stream is reached, "recv()" raises
      "ConnectionClosed". This can happen after a normal connection
      closure, a protocol error or a network failure.

      Changed in version 3.0: "recv()" used to return "None" instead.
      Refer to the changelog for details.

      Canceling "recv()" is safe. There's no risk of losing the next
      message. The next invocation of "recv()" will return it. This
      makes it possible to enforce a timeout by wrapping "recv()" in
      "wait_for()".

      Changed in version 7.0: Calling "recv()" concurrently raises
      "RuntimeError".

   send(data)

      This coroutine sends a message.

      It sends "str" as a text frame and "bytes" as a binary frame.

      It also accepts an iterable of "str" or "bytes". Each item is
      treated as a message fragment and sent in its own frame. All
      items must be of the same type, or else "send()" will raise a
      "TypeError" and the connection will be closed.

      It raises a "TypeError" for other inputs.

   ping(data=None)

      This coroutine sends a ping.

      It returns a "Future" which will be completed when the
      corresponding pong is received and which you may ignore if you
      don't want to wait.

      A ping may serve as a keepalive or as a check that the remote
      endpoint received all messages up to this point:

         pong_waiter = await ws.ping()
         await pong_waiter   # only if you want to wait for the pong

      By default, the ping contains four random bytes. The content may
      be overridden with the optional "data" argument which must be of
      type "str" (which will be encoded to UTF-8) or "bytes".

   pong(data=b'')

      This coroutine sends a pong.

      An unsolicited pong may serve as a unidirectional heartbeat.

      The content may be overridden with the optional "data" argument
      which must be of type "str" (which will be encoded to UTF-8) or
      "bytes".

   local_address

      Local address of the connection.

      This is a "(host, port)" tuple or "None" if the connection
      hasn't been established yet.

   remote_address

      Remote address of the connection.

      This is a "(host, port)" tuple or "None" if the connection
      hasn't been established yet.

   open

      This property is "True" when the connection is usable.

      It may be used to detect disconnections but this is discouraged
      per the EAFP principle. When "open" is "False", using the
      connection raises a "ConnectionClosed" exception.

   closed

      This property is "True" once the connection is closed.

      Be aware that both "open" and :attr`closed` are "False" during
      the opening and closing sequences.


Exceptions
----------

exception websockets.exceptions.AbortHandshake(status, headers, body=b'')

   Exception raised to abort a handshake and return a HTTP response.

exception websockets.exceptions.CancelHandshake

   Exception raised to cancel a handshake when the connection is
   closed.

exception websockets.exceptions.ConnectionClosed(code, reason)

   Exception raised when trying to read or write on a closed
   connection.

   Provides the connection close code and reason in its "code" and
   "reason" attributes respectively.

exception websockets.exceptions.DuplicateParameter(name)

   Exception raised when a parameter name is repeated in an extension
   header.

exception websockets.exceptions.InvalidHandshake

   Exception raised when a handshake request or response is invalid.

exception websockets.exceptions.InvalidHeader(name, value=None)

   Exception raised when a HTTP header doesn't have a valid format or
   value.

exception websockets.exceptions.InvalidHeaderFormat(name, error, string, pos)

   Exception raised when a Sec-WebSocket-* HTTP header cannot be
   parsed.

exception websockets.exceptions.InvalidHeaderValue(name, value=None)

   Exception raised when a Sec-WebSocket-* HTTP header has a wrong
   value.

exception websockets.exceptions.InvalidMessage

   Exception raised when the HTTP message in a handshake request is
   malformed.

exception websockets.exceptions.InvalidOrigin(origin)

   Exception raised when the Origin header in a request isn't allowed.

exception websockets.exceptions.InvalidParameterName(name)

   Exception raised when a parameter name in an extension header is
   invalid.

exception websockets.exceptions.InvalidParameterValue(name, value)

   Exception raised when a parameter value in an extension header is
   invalid.

exception websockets.exceptions.InvalidState

   Exception raised when an operation is forbidden in the current
   state.

exception websockets.exceptions.InvalidStatusCode(status_code)

   Exception raised when a handshake response status code is invalid.

   Provides the integer status code in its "status_code" attribute.

exception websockets.exceptions.InvalidUpgrade(name, value=None)

   Exception raised when a Upgrade or Connection header isn't correct.

exception websockets.exceptions.InvalidURI

   Exception raised when an URI isn't a valid websocket URI.

exception websockets.exceptions.NegotiationError

   Exception raised when negotiating an extension fails.

exception websockets.exceptions.PayloadTooBig

   Exception raised when a frame's payload exceeds the maximum size.

exception websockets.exceptions.WebSocketProtocolError

   Internal exception raised when the remote side breaks the protocol.


Low-level
=========


Opening handshake
-----------------

The "websockets.handshake" module deals with the WebSocket opening
handshake according to section 4 of RFC 6455.

Functions defined in this module manipulate HTTP headers. The
"headers" argument must implement "get" and "__setitem__" and "get" —
a small subset of the "MutableMapping" abstract base class.

Headers names and values are "str" objects containing only ASCII
characters.

Some checks cannot be performed because they depend too much on the
context; instead, they're documented below.

To accept a connection, a server must:

* Read the request, check that the method is GET, and check the
  headers with "check_request()",

* Send a 101 response to the client with the headers created by
  "build_response()" if the request is valid; otherwise, send an
  appropriate HTTP error code.

To open a connection, a client must:

* Send a GET request to the server with the headers created by
  "build_request()",

* Read the response, check that the status code is 101, and check
  the headers with "check_response()".

websockets.handshake.build_request(headers)

   Build a handshake request to send to the server.

   Return the "key" which must be passed to "check_response()".

websockets.handshake.check_request(headers)

   Check a handshake request received from the client.

   If the handshake is valid, this function returns the "key" which
   must be passed to "build_response()".

   Otherwise it raises an "InvalidHandshake" exception and the server
   must return an error like 400 Bad Request.

   This function doesn't verify that the request is an HTTP/1.1 or
   higher GET request and doesn't perform Host and Origin checks.
   These controls are usually performed earlier in the HTTP request
   handling code. They're the responsibility of the caller.

websockets.handshake.build_response(headers, key)

   Build a handshake response to send to the client.

   "key" comes from "check_request()".

websockets.handshake.check_response(headers, key)

   Check a handshake response received from the server.

   "key" comes from "build_request()".

   If the handshake is valid, this function returns "None".

   Otherwise it raises an "InvalidHandshake" exception.

   This function doesn't verify that the response is an HTTP/1.1 or
   higher response with a 101 status code. These controls are the
   responsibility of the caller.


Data transfer
-------------

The "websockets.framing" module implements data framing as specified
in section 5 of RFC 6455.

It deals with a single frame at a time. Anything that depends on the
sequence of frames is implemented in "websockets.protocol".

class websockets.framing.Frame

   WebSocket frame.

   * "fin" is the FIN bit

   * "rsv1" is the RSV1 bit

   * "rsv2" is the RSV2 bit

   * "rsv3" is the RSV3 bit

   * "opcode" is the opcode

   * "data" is the payload data

   Only these fields are needed by higher level code. The MASK bit,
   payload length and masking-key are handled on the fly by "read()"
   and "write()".

   check()

      Check that this frame contains acceptable values.

      Raise "WebSocketProtocolError" if this frame contains incorrect
      values.

   classmethod read(reader, *, mask, max_size=None, extensions=None)

      Read a WebSocket frame and return a "Frame" object.

      "reader" is a coroutine taking an integer argument and reading
      exactly this number of bytes, unless the end of file is reached.

      "mask" is a "bool" telling whether the frame should be masked
      i.e. whether the read happens on the server side.

      If "max_size" is set and the payload exceeds this size in bytes,
      "PayloadTooBig" is raised.

      If "extensions" is provided, it's a list of classes with an
      "decode()" method that transform the frame and return a new
      frame. They are applied in reverse order.

      This function validates the frame before returning it and raises
      "WebSocketProtocolError" if it contains incorrect values.

   write(writer, *, mask, extensions=None)

      Write a WebSocket frame.

      "frame" is the "Frame" object to write.

      "writer" is a function accepting bytes.

      "mask" is a "bool" telling whether the frame should be masked
      i.e. whether the write happens on the client side.

      If "extensions" is provided, it's a list of classes with an
      "encode()" method that transform the frame and return a new
      frame. They are applied in order.

      This function validates the frame before sending it and raises
      "WebSocketProtocolError" if it contains incorrect values.

websockets.framing.encode_data(data)

   Helper that converts "str" or "bytes" to "bytes".

   "str" are encoded with UTF-8.

websockets.framing.parse_close(data)

   Parse the data in a close frame.

   Return "(code, reason)" when "code" is an "int" and "reason" a
   "str".

   Raise "WebSocketProtocolError" or "UnicodeDecodeError" if the data
   is invalid.

websockets.framing.serialize_close(code, reason)

   Serialize the data for a close frame.

   This is the reverse of "parse_close()".


URI parser
----------

The "websockets.uri" module implements parsing of WebSocket URIs
according to section 3 of RFC 6455.

websockets.uri.parse_uri(uri)

   This function parses and validates a WebSocket URI.

   If the URI is valid, it returns a "WebSocketURI".

   Otherwise it raises an "InvalidURI" exception.

class websockets.uri.WebSocketURI

   WebSocket URI.

   * "secure" is the secure flag

   * "host" is the lower-case host

   * "port" if the integer port, it's always provided even if it's
     the default

   * "resource_name" is the resource name, that is, the path and
     optional query

   * "user_info" is an "(username, password)" tuple when the URI
     contains User Information, else "None".

   host

      Alias for field number 1

   port

      Alias for field number 2

   resource_name

      Alias for field number 3

   secure

      Alias for field number 0

   user_info

      Alias for field number 4


Utilities
---------

The "websockets.headers" module provides parsers and serializers for
HTTP headers used in WebSocket handshake messages.

Its functions cannot be imported from "websockets". They must be
imported from "websockets.headers".

websockets.headers.parse_connection(string)

   Parse a "Connection" header.

   Return a list of connection options.

   Raise "InvalidHeaderFormat" on invalid inputs.

websockets.headers.parse_upgrade(string)

   Parse an "Upgrade" header.

   Return a list of connection options.

   Raise "InvalidHeaderFormat" on invalid inputs.

websockets.headers.parse_extension_list(string)

   Parse a "Sec-WebSocket-Extensions" header.

   Return a value with the following format:

      [
          (
              'extension name',
              [
                  ('parameter name', 'parameter value'),
                  ....
              ]
          ),
          ...
      ]

   Parameter values are "None" when no value is provided.

   Raise "InvalidHeaderFormat" on invalid inputs.

websockets.headers.build_extension_list(extensions)

   Unparse a "Sec-WebSocket-Extensions" header.

   This is the reverse of "parse_extension_list()".

websockets.headers.parse_subprotocol_list(string)

   Parse a "Sec-WebSocket-Protocol" header.

   Raise "InvalidHeaderFormat" on invalid inputs.

websockets.headers.build_subprotocol_list(protocols)

   Unparse a "Sec-WebSocket-Protocol" header.

   This is the reverse of "parse_subprotocol_list()".

The "websockets.http" module provides basic HTTP parsing and
serialization. It is merely adequate for WebSocket handshake messages.

Its functions cannot be imported from "websockets". They must be
imported from "websockets.http".

class websockets.http.Headers(*args, **kwargs)

   Data structure for working with HTTP headers efficiently.

   A "list" of "(name, values)" is inefficient for lookups.

   A "dict" doesn't suffice because header names are case-insensitive
   and multiple occurrences of headers with the same name are
   possible.

   "Headers" stores HTTP headers in a hybrid data structure to provide
   efficient insertions and lookups while preserving the original
   data.

   In order to account for multiple values with minimal hassle,
   "Headers" follows this logic:

   * When getting a header with "headers[name]":

        * if there's no value, "KeyError" is raised;

        * if there's exactly one value, it's returned;

        * if there's more than one value, "MultipleValuesError" is
          raised.

   * When setting a header with "headers[name] = value", the value
     is appended to the list of values for that header.

   * When deleting a header with "del headers[name]", all values for
     that header are removed (this is slow).

   Other methods for manipulating headers are consistent with this
   logic.

   As long as no header occurs multiple times, "Headers" behaves like
   "dict", except keys are lower-cased to provide case-insensitivity.

   "get_all()" returns a list of all values for a header and
   "raw_items()" returns an iterator of "(name, values)" pairs,
   similar to "http.client.HTTPMessage()".

   clear()

      Remove all headers.

   get_all(key)

      Return the (possibly empty) list of all values for a header.

   raw_items()

      Return an iterator of (header name, header value).

exception websockets.http.MultipleValuesError

   Exception raised when "Headers" has more than one value for a key.

websockets.http.read_request(stream)

   Read an HTTP/1.1 GET request from "stream".

   "stream" is an "StreamReader".

   Return "(path, headers)" where "path" is a "str" and "headers" is a
   "Headers" instance.

   "path" isn't URL-decoded or validated in any way.

   Non-ASCII characters are represented with surrogate escapes.

   Raise an exception if the request isn't well formatted.

   Don't attempt to read the request body because WebSocket handshake
   requests don't have one. If the request contains a body, it may be
   read from "stream" after this coroutine returns.

websockets.http.read_response(stream)

   Read an HTTP/1.1 response from "stream".

   "stream" is an "StreamReader".

   Return "(status_code, headers)" where "status_code" is a "int" and
   "headers" is a "Headers" instance.

   Non-ASCII characters are represented with surrogate escapes.

   Raise an exception if the response isn't well formatted.

   Don't attempt to read the response body, because WebSocket
   handshake responses don't have one. If the response contains a
   body, it may be read from "stream" after this coroutine returns.
