Document using connect as an async context manager.

docs/changelog.rst

@@ -39,6 +39,9 @@ Changelog
 
 Also:
 
+* :func:`~websockets.client.connect` can be used as an asynchronous context
+  manager on Python ≥ 3.5.
+
 * :meth:`~websockets.protocol.WebSocketCommonProtocol.ping` and
   :meth:`~websockets.protocol.WebSocketCommonProtocol.pong` supports
   data passed as :class:`str` in addition to :class:`bytes`.

docs/cheatsheet.rst

@@ -31,6 +31,8 @@ Client
 * Create a client with :func:`~websockets.client.connect` which is similar to
   asyncio's :meth:`~asyncio.BaseEventLoop.create_connection`.
 
+  * On Python ≥ 3.5, you can also use it as an asynchronous context manager.
+
   * You may subclass :class:`~websockets.server.WebSocketClientProtocol` and
     pass it in the ``klass`` keyword argument for advanced customization.
 
@@ -42,7 +44,8 @@ Client
   :meth:`~websockets.protocol.WebSocketCommonProtocol.pong` if you wish but it
   isn't needed in general.
 
-* Call :meth:`~websockets.protocol.WebSocketCommonProtocol.close` to terminate
+* If you aren't using :func:`~websockets.client.connect` as a context manager,
+  call :meth:`~websockets.protocol.WebSocketCommonProtocol.close` to terminate
   the connection.
 
 Debugging

docs/intro.rst

@@ -4,6 +4,8 @@ Getting started
 Basic example
 -------------
 
+*This section assumes Python ≥ 3.5. For older versions, read below.*
+
 .. _server-example:
 
 Here's a WebSocket server example. It reads a name from the client, sends a
@@ -21,6 +23,11 @@ On the server side, the handler coroutine ``hello`` is executed once for
 each WebSocket connection. The connection is automatically closed when the
 handler returns.
 
+``async`` and ``await`` aren't available in Python < 3.5. Here's how to adapt
+the client example for older Python versions.
+
+.. literalinclude:: ../example/oldclient.py
+
 Browser-based example
 ---------------------
 

example/client.py

@@ -3,17 +3,14 @@
 import asyncio
 import websockets
 
-@asyncio.coroutine
-def hello():
-    websocket = yield from websockets.connect('ws://localhost:8765/')
+async def hello():
+    async with websockets.connect('ws://localhost:8765') as websocket:
 
-    name = input("What's your name? ")
-    yield from websocket.send(name)
-    print("> {}".format(name))
+        name = input("What's your name? ")
+        await websocket.send(name)
+        print("> {}".format(name))
 
-    greeting = yield from websocket.recv()
-    print("< {}".format(greeting))
-
-    yield from websocket.close()
+        greeting = await websocket.recv()
+        print("< {}".format(greeting))
 
 asyncio.get_event_loop().run_until_complete(hello())

example/oldclient.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+
+import asyncio
+import websockets
+
+@asyncio.coroutine
+def hello():
+    websocket = yield from websockets.connect('ws://localhost:8765/')
+
+    try:
+        name = input("What's your name? ")
+        yield from websocket.send(name)
+        print("> {}".format(name))
+
+        greeting = yield from websocket.recv()
+        print("< {}".format(greeting))
+
+    finally:
+        yield from websocket.close()
+
+asyncio.get_event_loop().run_until_complete(hello())

websockets/client.py

@@ -128,6 +128,9 @@ def connect(uri, *,
     It raises :exc:`~websockets.uri.InvalidURI` if ``uri`` is invalid and
     :exc:`~websockets.handshake.InvalidHandshake` if the handshake fails.
 
+    On Python 3.5, it can be used as a asynchronous context manager. In that
+    case, the connection is closed when exiting the context.
+
     """
     if loop is None:
         loop = asyncio.get_event_loop()