Add example of client shutdown.

Fix #933.

docs/api/index.rst

@@ -0,0 +1,52 @@
+API
+===
+
+``websockets`` provides complete client and server implementations, as shown
+in the :doc:`getting started guide <intro>`.
+
+The process for opening and closing a WebSocket connection depends on which
+side you're implementing.
+
+* On the client side, connecting to a server with :class:`~websockets.connect`
+  yields a connection object that provides methods for interacting with the
+  connection. Your code can open a connection, then send or receive messages.
+
+  If you use :class:`~websockets.connect` as an asynchronous context manager,
+  then websockets closes the connection on exit. If not, then your code is
+  responsible for closing the connection.
+
+* On the server side, :class:`~websockets.serve` starts listening for client
+  connections and yields an server object that supports closing the server.
+
+  Then, when clients connects, the server initializes a connection object and
+  passes it to a handler coroutine, which is where your code can send or
+  receive messages. This pattern is called `inversion of control`_. It's
+  common in frameworks implementing servers.
+
+  When the handler coroutine terminates, websockets closes the connection. You
+  may also close it in the handler coroutine if you'd like.
+
+.. _inversion of control: https://en.wikipedia.org/wiki/Inversion_of_control
+
+Once the connection is open, the WebSocket protocol is symmetrical, except for
+low-level details that websockets manages under the hood. At this point,
+websockets provides the same API — and uses the same implementation — for
+client and server connections.
+
+.. toctree::
+   :maxdepth: 2
+
+   client
+   server
+   extensions
+   utilities
+   types
+
+For convenience, public APIs can be imported from the :mod:`websockets`
+package, unless noted otherwise. Anything that isn't listed in this document
+is a private API.
+
+
+
+
+

docs/deployment.rst

@@ -34,7 +34,7 @@ On Unix systems, shutdown is usually triggered by sending a signal.
 
 Here's a full example for handling SIGTERM on Unix:
 
-.. literalinclude:: ../example/shutdown.py
+.. literalinclude:: ../example/shutdown_server.py
     :emphasize-lines: 13,17-19
 
 This example is easily adapted to handle other signals. If you override the

docs/faq.rst

@@ -142,6 +142,17 @@ See `issue 414`_.
 
 .. _issue 414: https://github.com/aaugustin/websockets/issues/414
 
+How do I stop a client that is continuously processing messages?
+................................................................
+
+You can close the connection.
+
+Here's an example that terminates cleanly when it receives SIGTERM on Unix:
+
+.. literalinclude:: ../example/shutdown_client.py
+    :emphasize-lines: 10-13
+
+
 How do I disable TLS/SSL certificate verification?
 ..................................................
 

example/shutdown_client.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+
+import asyncio
+import signal
+import websockets
+
+async def client():
+    uri = "ws://localhost:8765"
+    async with websockets.connect(uri) as websocket:
+        # Close the connection when receiving SIGTERM.
+        loop = asyncio.get_event_loop()
+        loop.add_signal_handler(
+            signal.SIGTERM, loop.create_task, websocket.close())
+
+        # Process messages received on the connection.
+        async for message in websocket:
+            ...
+
+asyncio.get_event_loop().run_until_complete(client())