Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-02-13 19:04:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-137339: Clarify host and port parameter behavior in smtplib.SMTP{_SSL} initialization (#137340)

Browse source 
This also documents the previously undocumented default_port parameter.

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
This commit is contained in:
Aniket 2025-11-12 01:55:26 +05:30 • committed by GitHub
parent 2fb2b82161
commit b5196fa15a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 26 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

34
Doc/library/smtplib.rst
View file

@ -24,10 +24,13 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
.. class:: SMTP(host='', port=0, local_hostname=None[, timeout], source_address=None)
An :class:`SMTP` instance encapsulates an SMTP connection. It has methods
that support a full repertoire of SMTP and ESMTP operations. If the optional
*host* and *port* parameters are given, the SMTP :meth:`connect` method is
called with those parameters during initialization. If specified,
*local_hostname* is used as the FQDN of the local host in the HELO/EHLO
that support a full repertoire of SMTP and ESMTP operations.
If the host parameter is set to a truthy value, :meth:`SMTP.connect` is called with
host and port automatically when the object is created; otherwise, :meth:`!connect` must
be called manually.
If specified, *local_hostname* is used as the FQDN of the local host in the HELO/EHLO
command. Otherwise, the local hostname is found using
:func:`socket.getfqdn`. If the :meth:`connect` call returns anything other
than a success code, an :exc:`SMTPConnectError` is raised. The optional
@ -62,6 +65,10 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
``smtplib.SMTP.send`` with arguments ``self`` and ``data``,
where ``data`` is the bytes about to be sent to the remote host.
.. attribute:: SMTP.default_port
The default port used for SMTP connections (25).
.. versionchanged:: 3.3
Support for the :keyword:`with` statement was added.
@ -80,15 +87,23 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
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
required from the beginning of the connection and using :meth:`~SMTP.starttls`
is not appropriate. If *host* is not specified, the local host is used. If
*port* is zero, the standard SMTP-over-SSL port (465) is used. The optional
arguments *local_hostname*, *timeout* and *source_address* have the same
required from the beginning of the connection and using :meth:`SMTP.starttls` is
not appropriate.
If the host parameter is set to a truthy value, :meth:`SMTP.connect` is called with host
and port automatically when the object is created; otherwise, :meth:`!SMTP.connect` must
be called manually.
The optional arguments *local_hostname*, *timeout* and *source_address* have the same
meaning as they do in the :class:`SMTP` class. *context*, also optional,
can contain a :class:`~ssl.SSLContext` and allows configuring various
aspects of the secure connection. Please read :ref:`ssl-security` for
best practices.
.. attribute:: SMTP_SSL.default_port
The default port used for SMTP-over-SSL connections (465).
.. versionchanged:: 3.3
*context* was added.
@ -259,6 +274,9 @@ An :class:`SMTP` instance has the following methods:
2-tuple of the response code and message sent by the server in its
connection response.
If port is not changed from its default value of 0, the value of the :attr:`default_port`
attribute is used.
.. audit-event:: smtplib.connect self,host,port smtplib.SMTP.connect