[Python-checkins] cpython (merge 3.3 -> default): Merge #2118: clarify smtplib exception documentation.

[r.david.murray]

http://hg.python.org/cpython/rev/75e7bd46fcd7
changeset:   83309:75e7bd46fcd7
parent:      83304:f280786d0e64
parent:      83308:15c600674944
user:        R David Murray <rdmurray at bitdance.com>
date:        Sat Apr 13 14:42:36 2013 -0400
summary:
  Merge #2118: clarify smtplib exception documentation.

files:
  Doc/library/smtplib.rst |  43 +++++++++++++++-------------
  Lib/smtplib.py          |   5 ++-
  2 files changed, 26 insertions(+), 22 deletions(-)


diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -25,16 +25,16 @@
    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
-   *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.
+   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.
 
    For normal use, you should only require the initialization/connect,
    :meth:`sendmail`, and :meth:`~smtplib.quit` methods.
@@ -103,7 +103,8 @@
 
 .. 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 +183,6 @@
    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 +199,17 @@
    :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
--- a/Lib/smtplib.py
+++ b/Lib/smtplib.py
@@ -221,8 +221,9 @@
 
         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

-- 
Repository URL: http://hg.python.org/cpython