https://github.com/python/cpython/commit/b5196fa15a6c5aaa90eafff06206f8e44a9da216
commit: b5196fa15a6c5aaa90eafff06206f8e44a9da216
branch: main
author: Aniket <[email protected]>
committer: bitdancer <[email protected]>
date: 2025-11-11T15:25:26-05:00
summary:
gh-137339: Clarify host and port parameter behavior in smtplib.SMTP{_SSL}
initialization (#137340)
This also documents the previously undocumented default_port parameter.
Co-authored-by: Stan Ulbrych <[email protected]>
files:
M Doc/library/smtplib.rst
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index c5a3de52090cee..3ee8b82a1880f3 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
