From 14ee3cf244aad69d138159cf70715eedb95ce00f Mon Sep 17 00:00:00 2001 From: R David Murray Date: Sat, 13 Apr 2013 14:40:33 -0400 Subject: [PATCH 1/2] #2118: clarify smtplib exception documentation. --- Doc/library/smtplib.rst | 28 ++++++++++++++++------------ Lib/smtplib.py | 5 +++-- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 40b2561c6b2..38d5f310985 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -25,8 +25,9 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). A :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. An :exc:`SMTPConnectError` is - raised if the specified host doesn't respond correctly. The optional + with those parameters during initialization. If the :meth:`connect` call + returns anything other than a success code, an :exc:`SMTPConnectError` is + raised. The optional *timeout* parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). The optional source_address parameter allows to bind to some @@ -103,7 +104,8 @@ A nice selection of exceptions is defined as well: .. exception:: SMTPException - Base exception class for all exceptions raised by this module. + The base exception class for all the other excpetions provided by this + module. .. exception:: SMTPServerDisconnected @@ -182,15 +184,6 @@ An :class:`SMTP` instance has the following methods: for connection and for all messages sent to and received from the server. -.. method:: SMTP.connect(host='localhost', port=0) - - Connect to a host on a given port. The defaults are to connect to the local - host at the standard SMTP port (25). If the hostname ends with a colon (``':'``) - followed by a number, that suffix will be stripped off and the number - interpreted as the port number to use. This method is automatically invoked by - the constructor if a host is specified during instantiation. - - .. method:: SMTP.docmd(cmd, args='') Send a command *cmd* to the server. The optional argument *args* is simply @@ -207,6 +200,17 @@ An :class:`SMTP` instance has the following methods: :exc:`SMTPServerDisconnected` will be raised. +.. method:: SMTP.connect(host='localhost', port=0) + + Connect to a host on a given port. The defaults are to connect to the local + host at the standard SMTP port (25). If the hostname ends with a colon (``':'``) + followed by a number, that suffix will be stripped off and the number + interpreted as the port number to use. This method is automatically invoked by + the constructor if a host is specified during instantiation. Returns a + 2-tuple of the response code and message sent by the server in its + connection response. + + .. method:: SMTP.helo(name='') Identify yourself to the SMTP server using ``HELO``. The hostname argument diff --git a/Lib/smtplib.py b/Lib/smtplib.py index 562a18280b7..f2c8452f0e7 100644 --- a/Lib/smtplib.py +++ b/Lib/smtplib.py @@ -221,8 +221,9 @@ class SMTP: If specified, `host' is the name of the remote host to which to connect. If specified, `port' specifies the port to which to connect. - By default, smtplib.SMTP_PORT is used. An SMTPConnectError is raised - if the specified `host' doesn't respond correctly. If specified, + By default, smtplib.SMTP_PORT is used. If a host is specified the + connect method is called, and if it returns anything other than + a success code an SMTPConnectError is raised. If specified, `local_hostname` is used as the FQDN of the local host. By default, the local hostname is found using socket.getfqdn(). The `source_address` parameter takes a 2-tuple (host, port) for the socket From 0bfd6acf03640f8910b8f9fa10cc7775a7c55449 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Sat, 13 Apr 2013 14:40:51 -0400 Subject: [PATCH 2/2] Reflow paragraph. --- Doc/library/smtplib.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 38d5f310985..9593dea8116 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -27,15 +27,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). host and port parameters are given, the SMTP :meth:`connect` method is called with those parameters during initialization. If the :meth:`connect` call returns anything other than a success code, an :exc:`SMTPConnectError` is - raised. The optional - *timeout* parameter specifies a timeout in seconds for blocking operations - like the connection attempt (if not specified, the global default timeout - setting will be used). The optional source_address parameter allows to bind to some - specific source address in a machine with multiple network interfaces, - and/or to some specific source TCP port. It takes a 2-tuple (host, port), - for the socket to bind to as its source address before connecting. If - omitted (or if host or port are ``''`` and/or 0 respectively) the OS default - behavior will be used. + raised. The optional *timeout* parameter specifies a timeout in seconds for + blocking operations like the connection attempt (if not specified, the + global default timeout setting will be used). The optional source_address + parameter allows to bind to some specific source address in a machine with + multiple network interfaces, and/or to some specific source TCP port. It + takes a 2-tuple (host, port), for the socket to bind to as its source + address before connecting. If omitted (or if host or port are ``''`` and/or + 0 respectively) the OS default behavior will be used. For normal use, you should only require the initialization/connect, :meth:`sendmail`, and :meth:`~smtplib.quit` methods.