traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge #2118: clarify smtplib exception documentation.

This commit is contained in:
R David Murray 2013-04-13 14:42:36 -04:00
parent 6d80046628 0bfd6acf03
commit c1d3daf58b
2 changed files with 26 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Doc/library/smtplib.rst
View File

@ -25,16 +25,16 @@ 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
*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 @@ 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 +183,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 +199,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

5
Lib/smtplib.py
View File

@ -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