Rename create_transport() to create_connection(). Remove type argument.

pep-3156.txt

@@ -295,49 +295,57 @@ Some methods in the standard conforming interface return Futures:
   on success will be a tuple ``(host, port)``.  Same implementation
   remarks as for ``getaddrinfo()``.
 
-- ``create_transport(protocol_factory, host, port, **kwargs)``.
-  Creates a transport and a protocol and ties them together.  Returns
-  a Future whose result on success is a (transport, protocol) pair.
-  The protocol is created by calling ``protocol_factory()`` without
-  arguments(*).  Note that when the Future completes, the protocol's
-  ``connection_made()`` method has not yet been called; that will
-  happen when the connection handshake is complete.  When it is
-  impossible to connect to the given host and port, the Future will
-  raise an exception instead.
+- ``create_connection(protocol_factory, host, port, **kwargs)``.
+  Creates a stream connection to a given host and port.  This creates
+  an implementation-dependent Transport to represent the connection,
+  then calls ``protocol_factory()`` to instantiate (or retrieve) the
+  user's Protocol implementation, and finally ties the two together.
+  (See below for the definitions of Transport and Protocol.)  The
+  user's Protocol implementation is created or retrieved by calling
+  ``protocol_factory()`` without arguments(*).  The return value is a
+  Future whose result on success is the ``(transport, protocol)``
+  pair; if a failure prevents the creation of a successful connection,
+  the Future will have an appropriate exception set.  Note that when
+  the Future completes, the protocol's ``connection_made()`` method
+  has not yet been called; that will happen when the connection
+  handshake is complete.
 
   (*) There is no requirement that ``protocol_factory`` is a class.
   If your protocol class needs to have specific arguments passed to
   its constructor, you can use ``lambda`` or ``functools.partial()``.
+  You can also pass a trivial ``lambda`` that returns a previously
+  constructed Protocol instance.
 
   Optional keyword arguments:
 
-  - ``family``, ``type``, ``proto``, ``flags``: Address familty,
-    socket type, protcol, and miscellaneous flags to be passed through
-    to ``getaddrinfo()``.  These all default to ``0`` except ``type``
-    which defaults to ``socket.SOCK_STREAM``.
+  - ``family``, ``proto``, ``flags``: Address familty,
+    protcol, and miscellaneous flags to be passed through
+    to ``getaddrinfo()``.  These all default to ``0``.
+    (The socket type is always ``SOCK_STREAM``.)
 
   - ``ssl``: Pass ``True`` to create an SSL transport (by default a
     plain TCP is created).  Or pass an ``ssl.SSLContext`` object to
     override the default SSL context object to be used.
 
-  TBD: Should this be called create_connection()?
-
 - ``start_serving(protocol_factory, host, port, **kwds)``.  Enters a
   loop that accepts connections.  Returns a Future that completes once
   the loop is set up to serve; its return value is None.  Each time a
   connection is accepted, ``protocol_factory`` is called without
-  arguments(*) to create a protocol, a transport is created to represent
+  arguments(*) to create a Protocol, a Transport is created to represent
   the network side of the connection, and the two are tied together by
   calling ``protocol.connection_made(transport)``.
 
-  (*) See footnote above for ``create_transport()``.
+  (*) See footnote above for ``create_connection()``.  However, since
+  ``protocol_factory()`` is called once for each new incoming
+  connection, it is recommended that it return a new Protocol object
+  each time it is called.
 
   Optional keyword arguments:
 
-  - ``family``, ``type``, ``proto``, ``flags``: Address familty,
-    socket type, protcol, and miscellaneous flags to be passed through
-    to ``getaddrinfo()``.  These all default to ``0`` except ``type``
-    which defaults to ``socket.SOCK_STREAM``.
+  - ``family``, ``proto``, ``flags``: Address familty,
+    protcol, and miscellaneous flags to be passed through
+    to ``getaddrinfo()``.  These all default to ``0``.
+    (The socket type is always ``SOCK_STREAM``.)
 
   TBD: Support SSL?  I don't even know how to do that synchronously,
   and I suppose it needs a certificate.