gh-137339: Clarify host and port parameter behavior in smtplib.SMTP{_SSL} initializat...

This also documents the previously undocumented default_port parameter.

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index c5a3de52090cee758a79551f352dbfc7ed18ce6b..3ee8b82a1880f38937e29f1c1877a1de9789c5c8 100644 (file)
--- 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