Clarify that SSL could mean TLS. Allow duck typing SSLContext. Allow missing run/stop/close functionality.

pep-3156.txt

@@ -176,7 +176,7 @@ The most common type of transport is a bidirectional stream transport.
 It represents a pair of buffered streams (one in each direction) that
 each transmit a sequence of bytes.  The most common example of a
 bidirectional stream transport is probably a TCP connection.  Another
-common example is an SSL connection.  But there are some other things
+common example is an SSL/TLS connection.  But there are some other things
 that can be viewed this way, for example an SSH session or a pair of
 UNIX pipes.  Typically there aren't many different transport
 implementations, and most of them come with the event loop
@@ -302,7 +302,7 @@ concrete classes are defined:
   ``IocpProactor`` is created and used.  (The ``IocpProactor`` class
   is not specified by this PEP.  Its inclusion in the standard library
   is not currently under consideration; it is just an implementation
-  detail of the ``ProactorEventLoop`` class.
+  detail of the ``ProactorEventLoop`` class.)
 
 Event Loop Methods Overview
 ---------------------------
@@ -310,9 +310,11 @@ Event Loop Methods Overview
 The methods of a conforming event loop are grouped into several
 categories.  A brief overview of the categories.  The first set of
 categories must be supported by all conforming event loop
-implementations.   (However, in some cases a partially-conforming
+implementations.  (However, in some cases a partially-conforming
 implementation may choose not to implement the internet/socket
-methods, and still conform to the other methods.)
+methods, and still conform to the other methods.  Also, it is possible
+that a partially-conforming implementation has no way to create,
+close, start, or stop a loop.)
 
 - Miscellaneous: ``close()``, ``time()``.
 
@@ -564,21 +566,22 @@ use a different transport and protocol interface.
 
   The <options> are all specified using optional keyword arguments:
 
-  - ``ssl``: Pass ``True`` to create an SSL transport (by default a
+  - ``ssl``: Pass ``True`` to create an SSL/TLS transport (by default
-    plain TCP transport is created).  Or pass an ``ssl.SSLContext``
+    a plain TCP transport is created).  Or pass an ``ssl.SSLContext``
-    object to override the default SSL context object to be used.  If
+    object (or something else that implements the same interface) to
-    a default context is created it is up to the implementation to
+    override the default SSL context object to be used.  If a default
-    configure reasonable defaults.  The reference implementation
+    context is created it is up to the implementation to configure
-    currently uses ``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2``
+    reasonable defaults.  The reference implementation currently uses
-    option, calls ``set_default_verify_paths()`` and sets verify_mode
+    ``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2`` option, calls
-    to ``CERT_REQUIRED``.  In addition, whenever the context (default
+    ``set_default_verify_paths()`` and sets verify_mode to
-    or otherwise) specifies a verify_mode of ``CERT_REQUIRED``, if a
+    ``CERT_REQUIRED``.  In addition, whenever the context (default or
-    hostname is given, immediately after a successful handshake
+    otherwise) specifies a verify_mode of ``CERT_REQUIRED`` or
-    ``ss.ssl.match_hostname(peercert, hostname)`` is called, and if
+    ``CERT_OPTIONAL``, if a hostname is given, immediately after a
-    this raises an exception the conection is closed.  (To avoid this
+    successful handshake ``ssl.match_hostname(peercert, hostname)`` is
-    behavior, pass in an context that doesn't have verify_mode set to
+    called, and if this raises an exception the conection is closed.
-    ``CERT_REQUIRED``.  But this means you are not secure, and
+    (To avoid this behavior, pass in an SSL context that ha
-    vulnerable to for example man-in-the-middle attacks.)
+    verify_mode set to ``CERT_NONE``.  But this means you are not
+    secure, and vulnerable to for example man-in-the-middle attacks.)
 
   - ``family``, ``proto``, ``flags``: Address family, protocol and
     flags to be passed through to ``getaddrinfo()``.  These all
@@ -620,10 +623,11 @@ use a different transport and protocol interface.
 
   The <options> are all specified using optional keyword arguments:
 
-  - ``ssl``: Pass an ``ssl.SSLContext`` object to override the default
+  - ``ssl``: Pass an ``ssl.SSLContext`` object (or an object with the
-    SSL context object to be used.  (Unlike ``create_connection()``,
+    same interface) to override the default SSL context object to be
-    passing ``True`` does not make sense -- the ``SSLContext`` object
+    used.  (Unlike ``create_connection()``, passing ``True`` does not
-    is required to specify the certificate and key.)
+    make sense -- the ``SSLContext`` object is required to specify the
+    certificate and key.)
 
   - ``backlog``: Backlog value to be passed to the ``listen()`` call.
     Defaults to ``100``.
@@ -1013,8 +1017,8 @@ Transports work in conjunction with protocols.  Protocols are
 typically written without knowing or caring about the exact type of
 transport used, and transports can be used with a wide variety of
 protocols.  For example, an HTTP client protocol implementation may be
-used with either a plain socket transport or an SSL transport.  The
+used with either a plain socket transport or an SSL/TLS transport.
-plain socket transport can be used with many different protocols
+The plain socket transport can be used with many different protocols
 besides HTTP (e.g. SMTP, IMAP, POP, FTP, IRC, SPDY).
 
 The most common type of transport is a bidirectional stream transport.
@@ -1037,7 +1041,7 @@ Bidirectional Stream Transports
 '''''''''''''''''''''''''''''''
 
 A bidrectional stream transport is an abstraction on top of a socket
-or something similar (for example, a pair of UNIX pipes or an SSL
+or something similar (for example, a pair of UNIX pipes or an SSL/TLS
 connection).
 
 Most connections have an asymmetric nature: the client and server
@@ -1092,7 +1096,7 @@ Bidirectional stream transports have the following public methods:
   because some protocols need to change their behavior when
   ``write_eof()`` is unavailable.  For example, in HTTP, to send data
   whose size is not known ahead of time, the end of the data is
-  typically indicated using ``write_eof()``; however, SSL does not
+  typically indicated using ``write_eof()``; however, SSL/TLS does not
   support this, and an HTTP protocol implementation would have to use
   the "chunked" transfer encoding in this case.  But if the data size
   is known ahead of time, the best approach in both cases is to use
@@ -1519,7 +1523,7 @@ Open Issues
   users can write their own (it's not rocket science).
 
 - We may need APIs to control various timeouts.  E.g. we may want to
-  limit the time spent in DNS resolution, connecting, ssl handshake,
+  limit the time spent in DNS resolution, connecting, ssl/tls handshake,
   idle connection, close/shutdown, even per session.  Possibly it's
   sufficient to add ``timeout`` keyword arguments to some methods,
   and other timeouts can probably be implemented by clever use of