mirror of
https://github.com/python/cpython.git
synced 2025-11-01 02:38:53 +00:00
gh-94172: Update docs for params removed in 3.12 (#100431)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
This commit is contained in:
Hugo van Kemenade
GitHub
parent
025b5c3780
commit
9eca7235af
7 changed files with 58 additions and 56 deletions
|
|
@ -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')
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.)
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue