Issue #28022: Deprecate ssl-related arguments in favor of SSLContext.

The deprecation include manual creation of SSLSocket and certfile/keyfile
(or similar) in ftplib, httplib, imaplib, smtplib, poplib and urllib.

ssl.wrap_socket() is not marked as deprecated yet.

7 files changed, 58 insertions, 9 deletions

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 1e35f37..b8c1dcf 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -97,6 +97,13 @@ The module defines the following items:
       :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
       :data:`ssl.HAS_SNI`).
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
    Here's a sample session using the :class:`FTP_TLS` class::
 
       >>> ftps = FTP_TLS('ftp.pureftpd.org')
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 90c0421..17f289d 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -69,13 +69,6 @@ The module provides the following classes:
    must be a :class:`ssl.SSLContext` instance describing the various SSL
    options.
 
-   *key_file* and *cert_file* are deprecated, please use
-   :meth:`ssl.SSLContext.load_cert_chain` instead, or let
-   :func:`ssl.create_default_context` select the system's trusted CA
-   certificates for you.  The *check_hostname* parameter is also deprecated; the
-   :attr:`ssl.SSLContext.check_hostname` attribute of *context* should be used
-   instead.
-
    Please read :ref:`ssl-security` for more information on best practices.
 
    .. versionchanged:: 3.2
@@ -95,6 +88,17 @@ The module provides the following classes:
       :func:`ssl._create_unverified_context` can be passed to the *context*
       parameter.
 
+   .. deprecated:: 3.6
+
+       *key_file* and *cert_file* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
+       The *check_hostname* parameter is also deprecated; the
+       :attr:`ssl.SSLContext.check_hostname` attribute of *context* should
+       be used instead.
+
 
 .. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None)
 
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index b9b3b91..7024a1b 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -103,6 +103,14 @@ There's also a subclass for secure connections:
       :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
       :data:`ssl.HAS_SNI`).
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *ssl_context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
+
 The second subclass allows for connections created by a child process:
 
 
diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index ffabc32..d72b660 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -62,6 +62,13 @@ The :mod:`poplib` module provides two classes:
       :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
       :data:`ssl.HAS_SNI`).
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
 One exception is defined as an attribute of the :mod:`poplib` module:
 
 
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 83d5c2d..1cb3aaf 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -95,6 +95,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
       :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
       :data:`ssl.HAS_SNI`).
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
+
 .. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None)
 
    The LMTP protocol, which is very similar to ESMTP, is heavily based on the
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 98008fa..af0c5ab 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -230,7 +230,6 @@ instead.
    .. versionchanged:: 3.2
       New optional argument *ciphers*.
 
-
 Context creation
 ^^^^^^^^^^^^^^^^
 
@@ -925,7 +924,7 @@ SSL Sockets
    :ref:`notes on non-blocking sockets <ssl-nonblocking>`.
 
    Usually, :class:`SSLSocket` are not created directly, but using the
-   :func:`wrap_socket` function or the :meth:`SSLContext.wrap_socket` method.
+   the :meth:`SSLContext.wrap_socket` method.
 
    .. versionchanged:: 3.5
       The :meth:`sendfile` method was added.
@@ -935,6 +934,10 @@ SSL Sockets
       are received or sent. The socket timeout is now to maximum total duration
       of the shutdown.
 
+   .. deprecated:: 3.6
+      It is deprecated to create a :class:`SSLSocket` instance directly, use
+      :meth:`SSLContext.wrap_socket` to wrap a socket.
+
 
 SSL sockets also have the following additional methods and attributes:
 
@@ -955,6 +958,9 @@ SSL sockets also have the following additional methods and attributes:
       The socket timeout is now to maximum total duration to read up to *len*
       bytes.
 
+   .. deprecated:: 3.6
+      Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`.
+
 .. method:: SSLSocket.write(buf)
 
    Write *buf* to the SSL socket and return the number of bytes written. The
@@ -970,6 +976,9 @@ SSL sockets also have the following additional methods and attributes:
       The socket timeout is no more reset each time bytes are received or sent.
       The socket timeout is now to maximum total duration to write *buf*.
 
+   .. deprecated:: 3.6
+      Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`.
+
 .. note::
 
    The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index d288165..491bded 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -111,6 +111,12 @@ The :mod:`urllib.request` module defines the following functions:
    .. versionchanged:: 3.4.3
       *context* was added.
 
+   .. deprecated:: 3.6
+
+       *cafile*, *capath* and *cadefault* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
 
 .. function:: install_opener(opener)