From a2e3513bdf793dcaea7273038c745724cec2e37c Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 17:02:10 +0800 Subject: [PATCH 01/10] Update smtplib.rst --- Doc/library/smtplib.rst | 64 ++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index c5f8516f768a68..ef861e681e705f 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -80,8 +80,8 @@ 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:`starttls` is - not appropriate. If *host* is not specified, the local host is used. If + 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 meaning as they do in the :class:`SMTP` class. *context*, also optional, @@ -112,7 +112,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). 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 + :meth:`~SMTP.connect` method must support that as well as a regular host:port 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 '/'. @@ -147,9 +147,15 @@ A nice selection of exceptions is defined as well: .. exception:: SMTPResponseException Base class for all exceptions that include an SMTP error code. These exceptions - are generated in some instances when the SMTP server returns an error code. The - error code is stored in the :attr:`smtp_code` attribute of the error, and the - :attr:`smtp_error` attribute is set to the error message. + are generated in some instances when the SMTP server returns an error code. + + .. attribute:: smtp_code + + The error code. + + .. attribute:: smtp_error + + The error message. .. exception:: SMTPSenderRefused @@ -161,9 +167,13 @@ A nice selection of exceptions is defined as well: .. exception:: SMTPRecipientsRefused - All recipient addresses refused. The errors for each recipient are accessible - through the attribute :attr:`recipients`, which is a dictionary of exactly the - same sort as :meth:`SMTP.sendmail` returns. + All recipient addresses refused. + + .. attribute:: recipients + + The errors for each recipient are accessible through this + attribute, which is a dictionary of exactly thesame sort as + :meth:`SMTP.sendmail` returns. .. exception:: SMTPDataError @@ -211,7 +221,27 @@ A nice selection of exceptions is defined as well: SMTP Objects ------------ -An :class:`SMTP` instance has the following methods: +An :class:`SMTP` instance has the following methods and attributes: + +.. attribute:: SMTP.helo_resp + + The response to the ``HELO`` command, see :meth:`helo`. + + +.. attribute:: SMTP.ehlo_resp + + The response to the ``EHLO`` command, see :meth:`ehlo`. + +.. attribute:: SMTP.does_esmtp + + A boolean value indicating whether the server supports ESMTP, see + :meth:`ehlo`. + + +.. attribute:: SMTP.esmtp_features + + A dictionary of the names of SMTP service extensions supported by the server, + see :meth:`ehlo`. .. method:: SMTP.set_debuglevel(level) @@ -417,7 +447,7 @@ An :class:`SMTP` instance has the following methods: .. versionchanged:: 3.4 The method now supports hostname check with - :attr:`SSLContext.check_hostname` and *Server Name Indicator* (see + :attr:`ssl.SSLContext.check_hostname` and *Server Name Indicator* (see :const:`~ssl.HAS_SNI`). .. versionchanged:: 3.5 @@ -435,7 +465,7 @@ An :class:`SMTP` instance has the following methods: ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT`` commands can be passed as *rcpt_options*. (If you need to use different ESMTP options to different recipients you have to use the low-level methods such as - :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.) + :meth:`!mail`, :meth:`!rcpt` and :meth:`!data` to send the message.) .. note:: @@ -467,10 +497,12 @@ An :class:`SMTP` instance has the following methods: This method may raise the following exceptions: :exc:`SMTPRecipientsRefused` - All recipients were refused. Nobody got the mail. The :attr:`recipients` - attribute of the exception object is a dictionary with information about the - refused recipients (like the one returned when at least one recipient was - accepted). + All recipients were refused. Nobody got the mail. + + .. attribute:: recipients + + A dictionary with information about the refused recipients + (like the one returned when at least one recipient was accepted). :exc:`SMTPHeloError` The server didn't reply properly to the ``HELO`` greeting. From 02e7de09162eeb99e361b3001aab50fcdd77987d Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 17:02:27 +0800 Subject: [PATCH 02/10] Update .nitignore --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 60a80fe2c72a72..29fd3cfda458f0 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -29,7 +29,6 @@ Doc/library/profile.rst Doc/library/pyexpat.rst Doc/library/resource.rst Doc/library/select.rst -Doc/library/smtplib.rst Doc/library/socket.rst Doc/library/ssl.rst Doc/library/stdtypes.rst From 08abda42ef4ff6c12eb4bd962727a5e279f7dfb0 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 17:08:56 +0800 Subject: [PATCH 03/10] fix CI --- Doc/library/smtplib.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index ef861e681e705f..7d070d38428d4b 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -148,7 +148,7 @@ A nice selection of exceptions is defined as well: Base class for all exceptions that include an SMTP error code. These exceptions are generated in some instances when the SMTP server returns an error code. - + .. attribute:: smtp_code The error code. @@ -229,9 +229,10 @@ An :class:`SMTP` instance has the following methods and attributes: .. attribute:: SMTP.ehlo_resp - + The response to the ``EHLO`` command, see :meth:`ehlo`. + .. attribute:: SMTP.does_esmtp A boolean value indicating whether the server supports ESMTP, see From c75ae97c61ecf482d7e31761174d9bd51e645ff0 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:11:34 +0800 Subject: [PATCH 04/10] Update Doc/library/smtplib.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/smtplib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 7d070d38428d4b..702d54e5299993 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -171,9 +171,9 @@ A nice selection of exceptions is defined as well: .. attribute:: recipients - The errors for each recipient are accessible through this - attribute, which is a dictionary of exactly thesame sort as - :meth:`SMTP.sendmail` returns. + A dictionary of exactly the same sort as returned + by :meth:`SMTP.sendmail` containing the errors for + each recipient. .. exception:: SMTPDataError From db8837afc265aa3e12f823df239cb5e8ec614723 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:14:26 +0800 Subject: [PATCH 05/10] Update Doc/library/smtplib.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/smtplib.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 702d54e5299993..f890ef56c3c4bd 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -500,10 +500,6 @@ An :class:`SMTP` instance has the following methods and attributes: :exc:`SMTPRecipientsRefused` All recipients were refused. Nobody got the mail. - .. attribute:: recipients - - A dictionary with information about the refused recipients - (like the one returned when at least one recipient was accepted). :exc:`SMTPHeloError` The server didn't reply properly to the ``HELO`` greeting. From e8902a74f655d28c34ba773ec18c98bc344f09b2 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:15:30 +0800 Subject: [PATCH 06/10] reorder --- Doc/library/smtplib.rst | 44 ++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index f890ef56c3c4bd..c8b28c437e404c 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -223,28 +223,6 @@ SMTP Objects An :class:`SMTP` instance has the following methods and attributes: -.. attribute:: SMTP.helo_resp - - The response to the ``HELO`` command, see :meth:`helo`. - - -.. attribute:: SMTP.ehlo_resp - - The response to the ``EHLO`` command, see :meth:`ehlo`. - - -.. attribute:: SMTP.does_esmtp - - A boolean value indicating whether the server supports ESMTP, see - :meth:`ehlo`. - - -.. attribute:: SMTP.esmtp_features - - A dictionary of the names of SMTP service extensions supported by the server, - see :meth:`ehlo`. - - .. method:: SMTP.set_debuglevel(level) Set the debug output level. A value of 1 or ``True`` for *level* results in @@ -500,7 +478,6 @@ An :class:`SMTP` instance has the following methods and attributes: :exc:`SMTPRecipientsRefused` All recipients were refused. Nobody got the mail. - :exc:`SMTPHeloError` The server didn't reply properly to the ``HELO`` greeting. @@ -576,8 +553,29 @@ Normally these do not need to be called directly, so they are not documented here. For details, consult the module code. +.. attribute:: SMTP.helo_resp + + The response to the ``HELO`` command, see :meth:`helo`. + + +.. attribute:: SMTP.ehlo_resp + + The response to the ``EHLO`` command, see :meth:`ehlo`. + + +.. attribute:: SMTP.does_esmtp + + A boolean value indicating whether the server supports ESMTP, see + :meth:`ehlo`. + + +.. attribute:: SMTP.esmtp_features + + A dictionary of the names of SMTP service extensions supported by the server, + see :meth:`ehlo`. .. _smtp-example: + SMTP Example ------------ From 5a8d24fa4a7eafb9ebc98b8c86eb502b98c1af17 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:16:10 +0800 Subject: [PATCH 07/10] del blank line --- Doc/library/smtplib.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index c8b28c437e404c..ef69e0c1a031d1 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -575,7 +575,6 @@ here. For details, consult the module code. see :meth:`ehlo`. .. _smtp-example: - SMTP Example ------------ From 7f71d239601307e5c7caf66b1f59aa106e988969 Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:16:54 +0800 Subject: [PATCH 08/10] add blank line --- Doc/library/smtplib.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index ef69e0c1a031d1..48fb0fad3359ff 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -573,6 +573,8 @@ here. For details, consult the module code. A dictionary of the names of SMTP service extensions supported by the server, see :meth:`ehlo`. + + .. _smtp-example: SMTP Example From 9a0bf3570b7200c48784428182cda635cb50d5ed Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:26:36 +0800 Subject: [PATCH 09/10] Update Doc/library/smtplib.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/smtplib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 48fb0fad3359ff..d91792f8084db4 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -221,7 +221,7 @@ A nice selection of exceptions is defined as well: SMTP Objects ------------ -An :class:`SMTP` instance has the following methods and attributes: +An :class:`SMTP` instance has the following methods: .. method:: SMTP.set_debuglevel(level) From 2b9d03513e07ffdcbe0cd106f3426e836ba3ed5f Mon Sep 17 00:00:00 2001 From: Weilin Du <108666168+LamentXU123@users.noreply.github.com> Date: Sun, 12 Oct 2025 18:27:09 +0800 Subject: [PATCH 10/10] Update smtplib.rst --- Doc/library/smtplib.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index d91792f8084db4..c5a3de52090cee 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -552,6 +552,8 @@ Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``, Normally these do not need to be called directly, so they are not documented here. For details, consult the module code. +Additionally, an SMTP instance has the following attributes: + .. attribute:: SMTP.helo_resp