diff --git a/pep-3156.txt b/pep-3156.txt index 8a78a4999..bfffe5038 100644 --- a/pep-3156.txt +++ b/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.