Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
Dec 28, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
70453c6
Fix parameter names for each module
hugovk Dec 22, 2022
770bc01
Update docs for params removed in 3.12
hugovk Dec 22, 2022
d288832
Update docs for params removed in 3.12
hugovk Dec 23, 2022
879e651
Update some formatting
hugovk Dec 23, 2022
6938e1f
Apply suggestions from code review
hugovk Dec 27, 2022
25421ff
Update keyword-only
hugovk Dec 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions Doc/library/ftplib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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')
Expand Down
36 changes: 19 additions & 17 deletions Doc/library/http.client.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand Down
15 changes: 6 additions & 9 deletions Doc/library/imaplib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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:


Expand Down Expand Up @@ -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.
Expand Down
9 changes: 4 additions & 5 deletions Doc/library/poplib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:


Expand Down
27 changes: 14 additions & 13 deletions Doc/library/smtplib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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 '/'.

Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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`
Expand All @@ -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.

Expand Down
8 changes: 5 additions & 3 deletions Doc/whatsnew/3.12.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -628,9 +628,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`.)

Expand Down
8 changes: 5 additions & 3 deletions Misc/NEWS.d/3.12.0a2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down