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`.
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
: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
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')
.. 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::
*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
: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
``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)
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
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
(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.
.. 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:
``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.
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
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
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:
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
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
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 '/'.
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)
.. 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`
: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.
<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`.)
.. 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.
projects / thirdparty / Python / cpython.git / commitdiff
