Review fix for issue #216.

* Clarify documentation wording a bit.
* Make the backwards-compatibility logic more explicit (and removable).
* Move klass with legacy_recv, the other backwards-compatibility shim.

docs/cheatsheet.rst

@@ -22,9 +22,9 @@ Server
     execute the application logic, and finally closes the connection after
     the handler exits normally or with an exception.
 
-  * You may subclass :class:`~websockets.server.WebSocketServerProtocol` and
-    pass it or a factory function as the ``create_protocol`` argument for
-    advanced customization.
+  * For advanced customization, you may subclass
+    :class:`~websockets.server.WebSocketServerProtocol` and pass either this
+    subclass or a factory function as the ``create_protocol`` argument.
 
 Client
 ------
@@ -34,9 +34,9 @@ Client
 
   * On Python ≥ 3.5, you can also use it as an asynchronous context manager.
 
-  * You may subclass :class:`~websockets.server.WebSocketClientProtocol` and
-    pass it or a factory function as the ``create_protocol`` argument for
-    advanced customization.
+  * For advanced customization, you may subclass
+    :class:`~websockets.server.WebSocketClientProtocol` and pass either this
+    subclass or a factory function as the ``create_protocol`` argument.
 
 * Call :meth:`~websockets.protocol.WebSocketCommonProtocol.recv` and
   :meth:`~websockets.protocol.WebSocketCommonProtocol.send` to receive and

websockets/client.py

@@ -130,10 +130,11 @@ def handshake(self, wsuri,
 
 
 @asyncio.coroutine
-def connect(uri, *, create_protocol=None, klass=None,
+def connect(uri, *,
+            create_protocol=None,
             timeout=10, max_size=2 ** 20, max_queue=2 ** 5,
             read_limit=2 ** 16, write_limit=2 ** 16,
-            loop=None, legacy_recv=False,
+            loop=None, legacy_recv=False, klass=None,
             origin=None, subprotocols=None, extra_headers=None,
             **kwds):
     """
@@ -155,10 +156,9 @@ def connect(uri, *, create_protocol=None, klass=None,
     ``read_limit``, and ``write_limit`` optional arguments is described in the
     documentation of :class:`~websockets.protocol.WebSocketCommonProtocol`.
 
-    The ``create_protocol`` parameter allows customizing the
-    :class:`WebSocketClientProtocol` class used. The argument should be a
-    callable or class accepting the same arguments as
-    :class:`WebSocketClientProtocol` and that returns a
+    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 :class:`WebSocketClientProtocol` and returning a
     :class:`WebSocketClientProtocol` instance. It defaults to
     :class:`WebSocketClientProtocol`.
 
@@ -181,7 +181,13 @@ def connect(uri, *, create_protocol=None, klass=None,
     if loop is None:
         loop = asyncio.get_event_loop()
 
-    create_protocol = create_protocol or klass or WebSocketClientProtocol
+    # Backwards-compatibility: create_protocol used to be called klass.
+    # In the unlikely event that both are specified, klass is ignored.
+    if create_protocol is None:
+        create_protocol = klass
+
+    if create_protocol is None:
+        create_protocol = WebSocketClientProtocol
 
     wsuri = parse_uri(uri)
     if wsuri.secure:

websockets/server.py

@@ -407,10 +407,10 @@ def wait_closed(self):
 
 @asyncio.coroutine
 def serve(ws_handler, host=None, port=None, *,
-          create_protocol=None, klass=None,
+          create_protocol=None,
           timeout=10, max_size=2 ** 20, max_queue=2 ** 5,
           read_limit=2 ** 16, write_limit=2 ** 16,
-          loop=None, legacy_recv=False,
+          loop=None, legacy_recv=False, klass=None,
           origins=None, subprotocols=None, extra_headers=None,
           **kwds):
     """
@@ -440,10 +440,9 @@ def serve(ws_handler, host=None, port=None, *,
     set the ``ssl`` keyword argument to a :class:`~ssl.SSLContext` to enable
     TLS.
 
-    The ``create_protocol`` parameter allows customizing the
-    :class:`WebSocketServerProtocol` class used. The argument should be a
-    callable or class accepting the same arguments as
-    :class:`WebSocketServerProtocol` and that returns a
+    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 :class:`WebSocketServerProtocol` and returning a
     :class:`WebSocketServerProtocol` instance. It defaults to
     :class:`WebSocketServerProtocol`.
 
@@ -479,7 +478,13 @@ def serve(ws_handler, host=None, port=None, *,
     if loop is None:
         loop = asyncio.get_event_loop()
 
-    create_protocol = create_protocol or klass or WebSocketServerProtocol
+    # Backwards-compatibility: create_protocol used to be called klass.
+    # In the unlikely event that both are specified, klass is ignored.
+    if create_protocol is None:
+        create_protocol = klass
+
+    if create_protocol is None:
+        create_protocol = WebSocketServerProtocol
 
     ws_server = WebSocketServer(loop)