1berry/cpython
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge #2118: clarify smtplib exception documentation.

Browse Source
This commit is contained in:
R David Murray 2013-04-13 14:42:36 -04:00
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 A :class:`SMTP` instance encapsulates an SMTP connection. It has methods
that support a full repertoire of SMTP and ESMTP operations. If the optional 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 host and port parameters are given, the SMTP :meth:`connect` method is called
with those parameters during initialization. An :exc:`SMTPConnectError` is with those parameters during initialization. If the :meth:`connect` call
raised if the specified host doesn't respond correctly. The optional returns anything other than a success code, an :exc:`SMTPConnectError` is
*timeout* parameter specifies a timeout in seconds for blocking operations raised. The optional *timeout* parameter specifies a timeout in seconds for
like the connection attempt (if not specified, the global default timeout blocking operations like the connection attempt (if not specified, the
setting will be used). The optional source_address parameter allows to bind to some global default timeout setting will be used). The optional source_address
specific source address in a machine with multiple network interfaces, parameter allows to bind to some specific source address in a machine with
and/or to some specific source TCP port. It takes a 2-tuple (host, port), multiple network interfaces, and/or to some specific source TCP port. It
for the socket to bind to as its source address before connecting. If takes a 2-tuple (host, port), for the socket to bind to as its source
omitted (or if host or port are ``''`` and/or 0 respectively) the OS default address before connecting. If omitted (or if host or port are ``''`` and/or
behavior will be used. 0 respectively) the OS default behavior will be used.
For normal use, you should only require the initialization/connect, For normal use, you should only require the initialization/connect,
:meth:`sendmail`, and :meth:`~smtplib.quit` methods. :meth:`sendmail`, and :meth:`~smtplib.quit` methods.
@ -103,7 +103,8 @@ A nice selection of exceptions is defined as well:
.. exception:: SMTPException .. 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 .. 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. 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='') .. method:: SMTP.docmd(cmd, args='')
Send a command *cmd* to the server. The optional argument *args* is simply 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. :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='') .. method:: SMTP.helo(name='')
Identify yourself to the SMTP server using ``HELO``. The hostname argument 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 If specified, `host' is the name of the remote host to which to
connect. If specified, `port' specifies the port to which to connect. connect. If specified, `port' specifies the port to which to connect.
By default, smtplib.SMTP_PORT is used. An SMTPConnectError is raised By default, smtplib.SMTP_PORT is used. If a host is specified the
if the specified `host' doesn't respond correctly. If specified, 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, `local_hostname` is used as the FQDN of the local host. By default,
the local hostname is found using socket.getfqdn(). The the local hostname is found using socket.getfqdn(). The
`source_address` parameter takes a 2-tuple (host, port) for the socket `source_address` parameter takes a 2-tuple (host, port) for the socket