WebSocket class
===============

.. _websocket-reference:

The :class:`~micropie.WebSocket` class encapsulates a WebSocket
connection.  MicroPie constructs an instance for each WebSocket
request and passes it as the first argument to your WebSocket handler.

Constructor
-----------

.. class:: WebSocket(receive, send)

   Create a new WebSocket wrapper around the ASGI ``receive`` and
   ``send`` callables.  You do not instantiate this class yourself;
   MicroPie does so internally.

Methods
-------

.. method:: accept(subprotocol=None, session_id=None)

   Accept the WebSocket connection.  You must call this method before
   sending or receiving messages.  If you provide a *session_id*,
   MicroPie sets a ``session_id`` cookie during the handshake.  The
   optional *subprotocol* argument specifies a negotiated subprotocol.

.. method:: receive_text()

   Await a text message from the client.  Returns a string.  Raises
   :class:`~micropie.ConnectionClosed` if the client has disconnected.
   If the client sends bytes, MicroPie decodes them as UTF-8 (ignoring
   invalid sequences) and returns the decoded string.

.. method:: receive_bytes()

   Await a binary message from the client.  Returns bytes.  Raises
   :class:`~micropie.ConnectionClosed` if the client has disconnected.
   If the client sends text, MicroPie returns the UTF-8 encoded bytes.

.. method:: send_text(data)

   Send a text message to the client.  Raises ``RuntimeError`` if you
   have not called :meth:`accept`.

.. method:: send_bytes(data)

   Send a binary message to the client.  Raises ``RuntimeError`` if
   the connection has not been accepted.

.. method:: close(code=1000, reason=None)

   Close the WebSocket connection.  By default uses code 1000
   (normal closure).  The optional *reason* is sent to the client.

Attributes
----------

.. attribute:: accepted

   ``True`` if the WebSocket has been accepted.

.. attribute:: session_id

   The session ID set during the handshake, or ``None`` if not set.

Exceptions
----------

MicroPie raises :class:`~micropie.ConnectionClosed` from
:meth:`receive_text` and :meth:`receive_bytes` when the client
disconnects.  See :doc:`exceptions` for exception details.