gh-94172: Update docs for params removed in 3.12 (#100431)

Co-authored-by: Shantanu <[email protected]>
Co-authored-by: Stanley <[email protected]>

Author: 3 people

Doc/library/ftplib.rst

@@ -85,7 +85,8 @@ The module defines the following items:
       The *encoding* parameter was added, and the default was changed from
       Latin-1 to UTF-8 to follow :rfc:`2640`.
 
-.. class:: FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')
+.. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None,
+                   timeout=None, source_address=None, encoding='utf-8')
 
    A :class:`FTP` subclass which adds TLS support to FTP as described in
    :rfc:`4217`.
@@ -96,10 +97,6 @@ The module defines the following items:
    options, certificates and private keys into a single (potentially
    long-lived) structure.  Please read :ref:`ssl-security` for best practices.
 
-   *keyfile* and *certfile* are a legacy alternative to *context* -- they
-   can point to PEM-formatted private key and certificate chain files
-   (respectively) for the SSL connection.
-
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.3
@@ -111,7 +108,6 @@ The module defines the following items:
       :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
@@ -123,6 +119,9 @@ The module defines the following items:
       The *encoding* parameter was added, and the default was changed from
       Latin-1 to UTF-8 to follow :rfc:`2640`.
 
+   .. versionchanged:: 3.12
+       The deprecated *keyfile* and *certfile* parameters have been removed.
+
    Here's a sample session using the :class:`FTP_TLS` class::
 
       >>> ftps = FTP_TLS('ftp.pureftpd.org')

Doc/library/http.client.rst

@@ -20,7 +20,7 @@ HTTPS protocols.  It is normally not used directly --- the module
 
 .. seealso::
 
-    The `Requests package <https://requests.readthedocs.io/en/master/>`_
+    The `Requests package <https://requests.readthedocs.io/en/latest/>`_
     is recommended for a higher-level HTTP client interface.
 
 .. note::
@@ -67,10 +67,9 @@ The module provides the following classes:
       *blocksize* parameter was added.
 
 
-.. class:: HTTPSConnection(host, port=None, key_file=None, \
-                           cert_file=None[, timeout], \
-                           source_address=None, *, context=None, \
-                           check_hostname=None, blocksize=8192)
+.. class:: HTTPSConnection(host, port=None, *[, timeout], \
+                           source_address=None, context=None, \
+                           blocksize=8192)
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
    secure servers.  Default port is ``443``.  If *context* is specified, it
@@ -96,6 +95,16 @@ 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.
+
    .. versionchanged:: 3.8
       This class now enables TLS 1.3
       :attr:`ssl.SSLContext.post_handshake_auth` for the default *context* or
@@ -106,16 +115,9 @@ The module provides the following classes:
       ``http/1.1`` when no *context* is given. Custom *context* should set
       ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
 
-   .. 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.
+   .. versionchanged:: 3.12
+       The deprecated *key_file*, *cert_file* and *check_hostname* parameters
+       have been removed.
 
 
 .. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None)
@@ -344,11 +346,11 @@ HTTPConnection Objects
    Set the host and the port for HTTP Connect Tunnelling. This allows running
    the connection through a proxy server.
 
-   The host and port arguments specify the endpoint of the tunneled connection
+   The *host* and *port* arguments specify the endpoint of the tunneled connection
    (i.e. the address included in the CONNECT request, *not* the address of the
    proxy server).
 
-   The headers argument should be a mapping of extra HTTP headers to send with
+   The *headers* argument should be a mapping of extra HTTP headers to send with
    the CONNECT request.
 
    For example, to tunnel through a HTTPS proxy server running locally on port

Doc/library/imaplib.rst

@@ -84,8 +84,8 @@ Three exceptions are defined as attributes of the :class:`IMAP4` class:
 There's also a subclass for secure connections:
 
 
-.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, \
-                     certfile=None, ssl_context=None, timeout=None)
+.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, \
+                     timeout=None)
 
    This is a subclass derived from :class:`IMAP4` that connects over an SSL
    encrypted socket (to use this class you need a socket module that was compiled
@@ -96,12 +96,6 @@ There's also a subclass for secure connections:
    (potentially long-lived) structure.  Please read :ref:`ssl-security` for
    best practices.
 
-   *keyfile* and *certfile* are a legacy alternative to *ssl_context* - they
-   can point to PEM-formatted private key and certificate chain files for
-   the SSL connection.  Note that the *keyfile*/*certfile* parameters are
-   mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
-   if *keyfile*/*certfile* is provided along with *ssl_context*.
-
    The optional *timeout* parameter specifies a timeout in seconds for the
    connection attempt. If timeout is not given or is None, the global default
    socket timeout is used.
@@ -124,6 +118,9 @@ There's also a subclass for secure connections:
    .. versionchanged:: 3.9
       The optional *timeout* parameter was added.
 
+   .. versionchanged:: 3.12
+       The deprecated *keyfile* and *certfile* parameters have been removed.
+
 The second subclass allows for connections created by a child process:
 
 
@@ -564,7 +561,7 @@ An :class:`IMAP4` instance has the following methods:
    ``search``, the searching *charset* argument is mandatory.  There is also a
    ``uid thread`` command which corresponds to ``thread`` the way that ``uid
    search`` corresponds to ``search``.  The ``thread`` command first searches the
-   mailbox for messages that match the given searching criteria using the charset
+   mailbox for messages that match the given searching criteria using the *charset*
    argument for the interpretation of strings in the searching criteria. It then
    returns the matching messages threaded according to the specified threading
    algorithm.

Doc/library/poplib.rst

@@ -53,7 +53,7 @@ The :mod:`poplib` module provides two classes:
       If the *timeout* parameter is set to be zero, it will raise a
       :class:`ValueError` to prevent the creation of a non-blocking socket.
 
-.. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)
+.. class:: POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)
 
    This is a subclass of :class:`POP3` that connects to the server over an SSL
    encrypted socket.  If *port* is not specified, 995, the standard POP3-over-SSL
@@ -63,10 +63,6 @@ The :mod:`poplib` module provides two classes:
    single (potentially long-lived) structure.  Please read :ref:`ssl-security`
    for best practices.
 
-   *keyfile* and *certfile* are a legacy alternative to *context* - they can
-   point to PEM-formatted private key and certificate chain files,
-   respectively, for the SSL connection.
-
    .. audit-event:: poplib.connect self,host,port poplib.POP3_SSL
 
    .. audit-event:: poplib.putline self,line poplib.POP3_SSL
@@ -94,6 +90,9 @@ The :mod:`poplib` module provides two classes:
       If the *timeout* parameter is set to be zero, it will raise a
       :class:`ValueError` to prevent the creation of a non-blocking socket.
 
+   .. versionchanged:: 3.12
+       The deprecated *keyfile* and *certfile* parameters have been removed.
+
 One exception is defined as an attribute of the :mod:`poplib` module:
 
 

Doc/library/smtplib.rst

@@ -66,18 +66,17 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
       Support for the :keyword:`with` statement was added.
 
    .. versionchanged:: 3.3
-      source_address argument was added.
+      *source_address* argument was added.
 
    .. versionadded:: 3.5
       The SMTPUTF8 extension (:rfc:`6531`) is now supported.
 
    .. versionchanged:: 3.9
       If the *timeout* parameter is set to be zero, it will raise a
-      :class:`ValueError` to prevent the creation of a non-blocking socket
+      :class:`ValueError` to prevent the creation of a non-blocking socket.
 
-.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, \
-                    certfile=None [, timeout], context=None, \
-                    source_address=None)
+.. class:: SMTP_SSL(host='', port=0, local_hostname=None, * [, timeout], \
+                    context=None, source_address=None)
 
    An :class:`SMTP_SSL` instance behaves exactly the same as instances of
    :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
@@ -90,15 +89,11 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    aspects of the secure connection.  Please read :ref:`ssl-security` for
    best practices.
 
-   *keyfile* and *certfile* are a legacy alternative to *context*, and can
-   point to a PEM formatted private key and certificate chain file for the
-   SSL connection.
-
    .. versionchanged:: 3.3
       *context* was added.
 
    .. versionchanged:: 3.3
-      source_address argument was added.
+      The *source_address* argument was added.
 
    .. versionchanged:: 3.4
       The class now supports hostname check with
@@ -116,13 +111,16 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
       If the *timeout* parameter is set to be zero, it will raise a
       :class:`ValueError` to prevent the creation of a non-blocking socket
 
+   .. versionchanged:: 3.12
+       The deprecated *keyfile* and *certfile* parameters have been removed.
+
 .. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, \
                 source_address=None[, timeout])
 
    The LMTP protocol, which is very similar to ESMTP, is heavily based on the
    standard SMTP client. It's common to use Unix sockets for LMTP, so our
    :meth:`connect` method must support that as well as a regular host:port
-   server. The optional arguments local_hostname and source_address have the
+   server. The optional arguments *local_hostname* and *source_address* have the
    same meaning as they do in the :class:`SMTP` class. To specify a Unix
    socket, you must use an absolute path for *host*, starting with a '/'.
 
@@ -360,7 +358,7 @@ An :class:`SMTP` instance has the following methods:
    be used as argument to the ``AUTH`` command; the valid values are
    those listed in the ``auth`` element of :attr:`esmtp_features`.
 
-   *authobject* must be a callable object taking an optional single argument:
+   *authobject* must be a callable object taking an optional single argument::
 
      data = authobject(challenge=None)
 
@@ -393,7 +391,7 @@ An :class:`SMTP` instance has the following methods:
    .. versionadded:: 3.5
 
 
-.. method:: SMTP.starttls(keyfile=None, certfile=None, context=None)
+.. method:: SMTP.starttls(*, context=None)
 
    Put the SMTP connection in TLS (Transport Layer Security) mode.  All SMTP
    commands that follow will be encrypted.  You should then call :meth:`ehlo`
@@ -416,6 +414,9 @@ An :class:`SMTP` instance has the following methods:
        :func:`ssl.create_default_context` select the system's trusted CA
        certificates for you.
 
+   .. versionchanged:: 3.12
+       The deprecated *keyfile* and *certfile* parameters have been removed.
+
    :exc:`SMTPHeloError`
       The server didn't reply properly to the ``HELO`` greeting.
 

Doc/whatsnew/3.12.rst

@@ -631,9 +631,11 @@ Removed
   <https://github.com/sphinx-contrib/sphinx-lint>`_.
   (Contributed by Julien Palard in :gh:`98179`.)
 
-* Remove the *keyfile*, *certfile* and *check_hostname* parameters, deprecated
-  since Python 3.6, in modules: :mod:`ftplib`, :mod:`http.client`,
-  :mod:`imaplib`, :mod:`poplib` and :mod:`smtplib`. Use the *context* parameter
+* Remove the *keyfile* and *certfile* parameters from the
+  :mod:`ftplib`, :mod:`imaplib`, :mod:`poplib` and :mod:`smtplib` modules,
+  and the *key_file*, *cert_file* and *check_hostname* parameters from the
+  :mod:`http.client` module,
+  all deprecated since Python 3.6. Use the *context* parameter
   (*ssl_context* in :mod:`imaplib`) instead.
   (Contributed by Victor Stinner in :gh:`94172`.)
 

Misc/NEWS.d/3.12.0a2.rst

@@ -725,9 +725,11 @@ Fix handling of ``bytes`` :term:`path-like objects <path-like object>` in
 .. nonce: AXE2IZ
 .. section: Library
 
-Remove the *keyfile*, *certfile* and *check_hostname* parameters, deprecated
-since Python 3.6, in modules: :mod:`ftplib`, :mod:`http.client`,
-:mod:`imaplib`, :mod:`poplib` and :mod:`smtplib`. Use the *context*
+Remove the *keyfile* and *certfile* parameters from the
+:mod:`ftplib`, :mod:`imaplib`, :mod:`poplib` and :mod:`smtplib` modules,
+and the *key_file*, *cert_file* and *check_hostname* parameters from the
+:mod:`http.client` module,
+all deprecated since Python 3.6. Use the *context*
 parameter (*ssl_context* in :mod:`imaplib`) instead. Patch by Victor
 Stinner.