Update docs for 0.14 tag (python-hyper#118)

Flesh out some missing pydocs, clean up the introduction, and make
the examples more common wsproto idioms.

Author: mehaase

Diff for: docs/source/api.rst

@@ -16,6 +16,13 @@ Connection
 ----------
 
 .. autoclass:: wsproto.WSConnection
+   :special-members: __init__
+   :members:
+
+.. autoclass:: wsproto.ConnectionType
+   :members:
+
+.. autoclass:: wsproto.connection.ConnectionState
    :members:
 
 Handshake
@@ -31,6 +38,9 @@ Handshake
 Events
 ------
 
+Event constructors accept any field as a keyword argument. Some fields are
+required, while others have default values.
+
 .. autoclass:: wsproto.events.Event
    :members:
 

Diff for: docs/source/basic-usage.rst

@@ -1,6 +1,8 @@
 Getting Started
 ===============
 
+.. currentmodule:: wsproto
+
 This document explains how to get started using wsproto to connect to
 WebSocket servers as well as how to write your own.
 
@@ -13,93 +15,82 @@ behind writing a network protocol library that doesn't do any network I/O.
 Connections
 -----------
 
-The main class you'll be working with is the
-:class:`WSConnection <wsproto.WSConnection>` object. This object
-represents a connection to a WebSocket client or server and contains all the
-state needed to communicate with the entity at the other end. Whether you're
-connecting to a server or receiving a connection from a client, this is the
-object you'll use.
+The main class you'll be working with is the :class:`WSConnection` object. This
+object represents a connection to a WebSocket peer. This class can handle both
+WebSocket clients and WebSocket servers.
 
-`wsproto` provides two layers of abstractions. You need to write code that
+``wsproto`` provides two layers of abstractions. You need to write code that
 interfaces with both of these layers. The following diagram illustrates how your
-code is like a sandwich around `wsproto`.
-
-+--------------------+
-| Application        |
-+--------------------+
-| <APPLICATION GLUE> |
-+--------------------+
-| wsproto            |
-+--------------------+
-| <NETWORK GLUE>     |
-+--------------------+
-| Network Layer      |
-+--------------------+
-
-`wsproto` does not do perform any network I/O, so ``<NETWORK GLUE>``
-represents the code you need to write to glue `wsproto` to the actual
-network layer, i.e.  code that can send and receive data over the
-network. The :class:`WSConnection <wsproto.WSConnection>`
-class provides two methods for this purpose. When data has been
-received on a network socket, you feed this data into `wsproto` by
-calling :meth:`receive_data
-<wsproto.WSConnection.receive_data>`. When `wsproto` sends
-events the :meth:`send <wsproto.WSConnection.send>` will
-return the bytes that need to be sent over the network. Your code is
-responsible for actually sending that data over the network.
+code is like a sandwich around ``wsproto``.
+
++----------------------+
+| Application          |
++----------------------+
+| **APPLICATION GLUE** |
++----------------------+
+| wsproto              |
++----------------------+
+| **NETWORK GLUE**     |
++----------------------+
+| Network Layer        |
++----------------------+
+
+``wsproto`` does not do perform any network I/O, so **NETWORK GLUE** represents
+the code you need to write to glue ``wsproto`` to an actual network, for example
+using Python's `socket <https://docs.python.org/3/library/socket.html>`_ module.
+The :class:`WSConnection` class provides two methods for this purpose. When data
+has been received on a network socket, you should feed this data into a
+connection instance by calling :meth:`WSConnection.receive_data`. When you want
+to communicate with the remote peer, e.g. send a message, ping, or close the
+connection, you should create an instance of one of the
+:class:`wsproto.events.Event` subclasses and pass it to
+:meth:`WSConnection.send` to get the corresponding bytes that need to be sent.
+Your code is responsible for actually sending that data over the network.
 
 .. note::
 
     If the connection drops, a standard Python ``socket.recv()`` will return
-    zero. You should call ``receive_data(None)`` to update the internal
-    `wsproto` state to indicate that the connection has been closed.
-
-Internally, `wsproto` process the raw network data you feed into it and turns it
-into higher level representations of WebSocket events. In ``<APPLICATION
-GLUE>``, you need to write code to process these events. The
-:class:`WSConnection <wsproto.WSConnection>` class contains a
-generator method :meth:`events <wsproto.WSConnection.events>` that
-yields WebSocket events. To send a message, you call the :meth:`send
-<wsproto.WSConnection.send>` method.
-
-Connecting to a WebSocket server
---------------------------------
-
-Begin by instantiating a connection object in the client mode and then
-create a :class:`Request <wsproto.events.Request>` instance to
-send. The Request must specify ``host`` and ``target`` arguments. If
-the WebSocket server is located at ``http://example.com/foo``, then you
-would instantiate the connection as follows::
+    zero bytes. You should call ``receive_data(None)`` to update the internal
+    ``wsproto`` state to indicate that the connection has been closed.
+
+Internally, ``wsproto`` processes the raw network data you feed into it and
+turns it into higher level representations of WebSocket events. In **APPLICATION
+GLUE**, you need to write code to process these events. Incoming data is exposed
+though the generator method :meth:`WSConnection.events`, which yields WebSocket
+events. Each event is an instance of an :class:`.events.Event` subclass.
+
+WebSocket Clients
+-----------------
 
+Begin by instantiating a connection object in client mode and then create a
+:class:`wsproto.events.Request` instance. The Request must specify ``host`` and
+``target`` arguments. If the WebSocket server is located at
+``http://example.com/foo``, then you would instantiate the connection as
+follows::
+
+    from wsproto import ConnectionType, WSConnection
+    from wsproto.events import Request
     ws = WSConnection(ConnectionType.CLIENT)
-    ws.send(Request(host="example.com", target='foo'))
+    request = Request(host="example.com", target='foo')
+    data = ws.send(request)
 
-Now you need to provide the network glue. For the sake of example, we will use
-standard Python sockets here, but `wsproto` can be integrated with any network
-layer::
+Keep in mind that ``wsproto`` does not do any network I/O. Instead,
+:meth:`WSConnection.send` returns data that you must send to the remote peer.
+Here is an example using a standard Python socket::
 
     sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     sock.connect(("example.com", 80))
+    sock.send(data)
 
-To read from the network::
+To receive communications from the peer, you must pass the data received from
+the peer into the connection instance::
 
     data = sock.recv(4096)
     ws.receive_data(data)
 
-You also need to send data returned by the send method::
-
-    data = ws.send(Message(data=b"Hello"))
-    sock.send(data)
-
-A standard Python socket will block on the call to ``sock.recv()``, so you
-will probably need to use a non-blocking socket or some form of concurrency like
-threading, greenlets, asyncio, etc.
-
-You also need to provide the application glue. To send a WebSocket message::
-
-    ws.send(Message(data="Hello world!"))
-
-And to receive WebSocket events::
+The connection instance parses the received data and determines if any high-level
+events have occurred, such as receiving a ping or a message. To retrieve these
+events, use the generator function :meth:`WSConnection.events`::
 
     for event in ws.events():
         if isinstance(event, AcceptConnection):
@@ -126,7 +117,7 @@ And to receive WebSocket events::
             print('Unknown event: {!r}'.format(event))
 
 The method ``events()`` returns a generator which will yield events for all of
-the data currently in the `wsproto` internal buffer and then exit. Therefore,
+the data currently in the ``wsproto`` internal buffer and then exit. Therefore,
 you should iterate over this generator after receiving new network data.
 
 For a more complete example, see `synchronous_client.py
@@ -135,9 +126,13 @@ For a more complete example, see `synchronous_client.py
 WebSocket Servers
 -----------------
 
-A WebSocket server is similar to a client except that it uses a different
-constant::
+A WebSocket server is similar to a client, but it uses a different
+:class:`wsproto.ConnectionType` constant.
 
+::
+
+    from wsproto import ConnectionType, WSConnection
+    from wsproto.events import Request
     ws = WSConnection(ConnectionType.SERVER)
 
 A server also needs to explicitly send an :class:`AcceptConnection
@@ -148,24 +143,7 @@ A server also needs to explicitly send an :class:`AcceptConnection
         if isinstance(event, Request):
             print('Accepting connection request')
             sock.send(ws.send(AcceptConnection()))
-        elif isinstance(event, CloseConnection):
-            print('Connection closed: code={} reason={}'.format(
-                event.code, event.reason
-            ))
-            sock.send(ws.send(event.response()))
-        elif isinstance(event, Ping):
-            print('Received Ping frame with payload {}'.format(event.payload))
-            sock.send(ws.send(event.response()))
-        elif isinstance(event, TextMessage):
-            print('Received TEXT data: {}'.format(event.data))
-            if event.message_finished:
-                print('TEXT Message finished.')
-        elif isinstance(event, BinaryMessage):
-            print('Received BINARY data: {}'.format(event.data))
-            if event.message_finished:
-                print('BINARY Message finished.')
-        else:
-            print('Unknown event: {!r}'.format(event))
+        elif...
 
 Alternatively a server can explicitly reject the connection by sending
 :class:`RejectConnection <wsproto.events.RejectConnection>` after
@@ -193,9 +171,9 @@ send one frame and receive one frame. Sending a
 :class:`CloseConnection <wsproto.events.CloseConnection>` instance
 sets the state to ``LOCAL_CLOSING``. When a close frame is received,
 it yields a ``CloseConnection`` event, sets the state to
-``REMOTE_CLOSING`` **and requires a reply to be sent**, this reply
+``REMOTE_CLOSING`` **and requires a reply to be sent**. This reply
 should be a ``CloseConnection`` event. To aid with this the
-``CloseConnection`` class has a :func:`response()
+``CloseConnection`` class has a :meth:`response()
 <wsproto.events.CloseConnection.response>` method to create the
 appropriate reply. For example,
 
@@ -207,11 +185,10 @@ appropriate reply. For example,
 When the reply has been received by the initiator, it will also yield
 a ``CloseConnection`` event.
 
-Regardless of which endpoint initiates the closing handshake, the
-server is responsible for tearing down the underlying connection. When
-the server receives a ``CloseConnection`` event, it should send
-pending `wsproto` data (if any) and then it can start tearing down the
-underlying connection.
+Regardless of which endpoint initiates the closing handshake, the server is
+responsible for tearing down the underlying connection. When a
+``CloseConnection`` event is generated, it should send pending any ``wsproto``
+data and then tear down the underlying connection.
 
 .. note::
 
@@ -226,7 +203,7 @@ sending WebSocket ping and pong frames via sending :class:`Ping
 <wsproto.events.Ping>` and :class:`Pong <wsproto.events.Pong>`. When a
 ``Ping`` frame is received it **requires a reply**, this reply should be
 a ``Pong`` event. To aid with this the ``Ping`` class has a
-:func:`response() <wsproto.events.Ping.response>` method to create the
+:meth:`response() <wsproto.events.Ping.response>` method to create the
 appropriate reply. For example,
 
 .. code-block:: python

Diff for: example/synchronous_client.py

@@ -51,46 +51,25 @@ def wsproto_demo(host, port):
     # 1) Negotiate WebSocket opening handshake
     print('Opening WebSocket')
     ws = WSConnection(ConnectionType.CLIENT)
+    # Because this is a client WebSocket, we need to initiate the connection
+    # handshake by sending a Request event.
     net_send(ws.send(Request(host=host, target='server')), conn)
     net_recv(ws, conn)
-
-    # events is a generator that yields websocket event objects. Usually you
-    # would say `for event in ws.events()`, but the synchronous nature of this
-    # client requires us to use next(event) instead so that we can interleave
-    # the network I/O. It will raise StopIteration when it runs out of events
-    # (i.e. needs more network data), but since this script is synchronous, we
-    # will explicitly resume the generator whenever we have new network data.
-    events = ws.events()
-
-    # Because this is a client WebSocket, wsproto has automatically queued up
-    # a handshake, and we need to send it and wait for a response.
-    event = next(events)
-    if isinstance(event, AcceptConnection):
-        print('WebSocket negotiation complete')
-    else:
-        raise Exception('Expected AcceptConnection event!')
+    handle_events(ws)
 
     # 2) Send a message and display response
     message = "wsproto is great"
     print('Sending message: {}'.format(message))
     net_send(ws.send(Message(data=message)), conn)
     net_recv(ws, conn)
-    event = next(events)
-    if isinstance(event, TextMessage):
-        print('Received message: {}'.format(event.data))
-    else:
-        raise Exception('Expected TextMessage event!')
+    handle_events(ws)
 
     # 3) Send ping and display pong
     payload = b"table tennis"
     print('Sending ping: {}'.format(payload))
     net_send(ws.send(Ping(payload=payload)), conn)
     net_recv(ws, conn)
-    event = next(events)
-    if isinstance(event, Pong):
-        print('Received pong: {}'.format(event.payload))
-    else:
-        raise Exception('Expected Pong event!')
+    handle_events(ws)
 
     # 4) Negotiate WebSocket closing handshake
     print('Closing WebSocket')
@@ -122,5 +101,17 @@ def net_recv(ws, conn):
         ws.receive_data(in_data)
 
 
+def handle_events(ws):
+    for event in ws.events():
+        if isinstance(event, AcceptConnection):
+            print('WebSocket negotiation complete')
+        elif isinstance(event, TextMessage):
+            print('Received message: {}'.format(event.data))
+        elif isinstance(event, Pong):
+            print('Received pong: {}'.format(event.payload))
+        else:
+            raise Exception('Do not know how to handle event: ' + str(event))
+
+
 if __name__ == '__main__':
     main()