From 65451a646a10a76d72e5c3173996870771c8ba98 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 3 Aug 2025 17:13:29 +0530 Subject: [PATCH 1/7] Clarify host and port parameter behavior in smtplib.SMTP_SSL initialization --- Doc/library/smtplib.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index c5f8516f768a68..8e0ce855b47464 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -26,7 +26,10 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). 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, + called with those parameters during initialization.If *host* is omitted or + an empty string, no connection is made during initialization; you must + call :meth:`connect` manually before using the instance. + If *port* is zero, the default SMTP port (25) is used. 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 @@ -81,7 +84,10 @@ 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 + not appropriate. If the optional *host* and *port* parameters are given, the + SMTP_SSL :meth:`connect` method is called with those parameters during initialization. + If *host* is omitted or an empty string, no connection is made during initialization; + you must call :meth:`connect` manually before using the instance. 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, From 7337b6d400f8ee1cd0480c4835cd0b57811d5c06 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Sun, 3 Aug 2025 18:31:02 +0530 Subject: [PATCH 2/7] Clarify host and port parameter behavior in smtplib.SMTP_SSL initialization --- Doc/library/smtplib.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 8e0ce855b47464..f500071aa3ffa2 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -24,12 +24,10 @@ 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 *host* is omitted or - an empty string, no connection is made during initialization; you must + that support a full repertoire of SMTP and ESMTP operations. + If *host* is omitted or set to an empty string, no connection is made during initialization; you must call :meth:`connect` manually before using the instance. - If *port* is zero, the default SMTP port (25) is used. If specified, + If *port* is zero,the value of the :attr:`default_port` attribute is used. 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 From 54907a0e28034cb01652c59241d1eda886eb8759 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Tue, 19 Aug 2025 10:28:48 +0530 Subject: [PATCH 3/7] Clarify smtplib docs: host/port explanation --- Doc/library/smtplib.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index f500071aa3ffa2..6f6262fd05c69a 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -27,8 +27,9 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). that support a full repertoire of SMTP and ESMTP operations. If *host* is omitted or set to an empty string, no connection is made during initialization; you must call :meth:`connect` manually before using the instance. - If *port* is zero,the value of the :attr:`default_port` attribute is used. If specified, - *local_hostname* is used as the FQDN of the local host in the HELO/EHLO + If *port* is zero,the value of the :attr:`default_port` attribute is used. + + 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 @@ -86,8 +87,9 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). SMTP_SSL :meth:`connect` method is called with those parameters during initialization. If *host* is omitted or an empty string, no connection is made during initialization; you must call :meth:`connect` manually before using the instance. 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 + *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, can contain a :class:`~ssl.SSLContext` and allows configuring various aspects of the secure connection. Please read :ref:`ssl-security` for From 058ab0a7fc7f996cdf33819f6b39ee86fb1138b1 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Wed, 27 Aug 2025 15:44:22 +0530 Subject: [PATCH 4/7] Doc: Add iterator reference and anchor to range() documentation --- Doc/library/functions.rst | 5 ++++- Doc/library/smtplib.rst | 20 +++++++------------- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 80bd1275973f8d..324a10c38c0779 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1735,7 +1735,10 @@ are always available. They are listed here in alphabetical order. Rather than being a function, :class:`range` is actually an immutable sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. - + + The object returned by :class:`range` is an :term:`iterator` and supports iteration. + See also :ref:`iterator` for more information about iterators and how to implement + custom iterable classes. .. function:: repr(object) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 6f6262fd05c69a..c5f8516f768a68 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -24,12 +24,10 @@ 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 *host* is omitted or set to an empty string, no connection is made during initialization; you must - call :meth:`connect` manually before using the instance. - If *port* is zero,the value of the :attr:`default_port` attribute is used. - - 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 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 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 @@ -83,13 +81,9 @@ 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 the optional *host* and *port* parameters are given, the - SMTP_SSL :meth:`connect` method is called with those parameters during initialization. - If *host* is omitted or an empty string, no connection is made during initialization; - you must call :meth:`connect` manually before using the instance. 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 + 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, can contain a :class:`~ssl.SSLContext` and allows configuring various aspects of the secure connection. Please read :ref:`ssl-security` for From a1e470bb9cd4e638a86dff243af8815981c86d42 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Wed, 27 Aug 2025 16:07:00 +0530 Subject: [PATCH 5/7] Doc: Add iterator reference and anchor to range() documentation --- Doc/library/functions.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 324a10c38c0779..453b43e97534c9 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1735,11 +1735,10 @@ are always available. They are listed here in alphabetical order. Rather than being a function, :class:`range` is actually an immutable sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. - + The object returned by :class:`range` is an :term:`iterator` and supports iteration. See also :ref:`iterator` for more information about iterators and how to implement custom iterable classes. - .. function:: repr(object) Return a string containing a printable representation of an object. For many From 3f553c0f428a3bbecfaa691eb2a11e1d3172748a Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Wed, 27 Aug 2025 19:45:14 +0530 Subject: [PATCH 6/7] Doc: Add iterator reference and anchor to range() documentation --- Doc/library/functions.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 453b43e97534c9..b56286511aa780 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1736,9 +1736,7 @@ are always available. They are listed here in alphabetical order. Rather than being a function, :class:`range` is actually an immutable sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. - The object returned by :class:`range` is an :term:`iterator` and supports iteration. - See also :ref:`iterator` for more information about iterators and how to implement - custom iterable classes. + The :class:`range` type is iterable and supports iteration. .. function:: repr(object) Return a string containing a printable representation of an object. For many From 771dafcd8fc02f820f366d716f6b2e371b7103f2 Mon Sep 17 00:00:00 2001 From: Aniket Singh Yadav Date: Thu, 28 Aug 2025 00:08:33 +0530 Subject: [PATCH 7/7] Doc: Add iterator reference and anchor to range() documentation --- Doc/library/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index b56286511aa780..2a08c3d08fd521 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1734,9 +1734,9 @@ are always available. They are listed here in alphabetical order. :noindex: Rather than being a function, :class:`range` is actually an immutable - sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. + :term:`sequence` type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. + - The :class:`range` type is iterable and supports iteration. .. function:: repr(object) Return a string containing a printable representation of an object. For many