[Python-checkins] cpython (3.3): #18179: document the local_hostname parameter.

Sun Jun 23 22:12:50 CEST 2013

http://hg.python.org/cpython/rev/3685d8074203
changeset: 84289:3685d8074203
branch: 3.3
parent: 84284:059432647de0
user: R David Murray <rdmurray at bitdance.com>
date: Sun Jun 23 15:47:50 2013 -0400
summary:
 #18179: document the local_hostname parameter.
Original patch by Berker Peksag.
files:
 Doc/library/smtplib.rst | 15 +++++++++++----
 Lib/smtplib.py | 11 +++++++----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -25,7 +25,10 @@
 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. If the :meth:`connect` call
+ 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 *timeout* parameter specifies a timeout in seconds for
 blocking operations like the connection attempt (if not specified, the
@@ -57,13 +60,17 @@
 .. versionchanged:: 3.3
 source_address argument was added.
 
-.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout], context=None, source_address=None)
+.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, \
+ certfile=None [, timeout], context=None, \
+ source_address=None)
 
 A :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
- *port* is zero, the standard SMTP-over-SSL port (465) is used. *keyfile*
+ *port* is zero, the standard SMTP-over-SSL port (465) is used. The optional
+ arguments *local_hostname* and *source_address* have the same meaning as
+ they do in the :class:`SMTP` class. *keyfile*
 and *certfile* are also optional, and can contain a PEM formatted private key
 and certificate chain file for the SSL connection. *context* also optional, can contain
 a SSLContext, and is an alternative to keyfile and certfile; If it is specified both
@@ -90,7 +97,7 @@
 standard SMTP client. It's common to use Unix sockets for LMTP, so our
 :meth:`connect` method must support that as well as a regular host:port
 server. The optional arguments local_hostname and source_address have the
- same meaning as that of SMTP client. To specify a Unix socket, you must use
+ same meaning as they do in the :class:`SMTP` class. To specify a Unix socket, you must use
 an absolute path for *host*, starting with a '/'.
 
 Authentication is supported, using the regular SMTP mechanism. When using a Unix
diff --git a/Lib/smtplib.py b/Lib/smtplib.py
--- a/Lib/smtplib.py
+++ b/Lib/smtplib.py
@@ -224,7 +224,8 @@
 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,
+ `local_hostname` is used as the FQDN of the local host in the
+ HELO/EHLO command. Otherwise,
 the local hostname is found using socket.getfqdn(). The
 `source_address` parameter takes a 2-tuple (host, port) for the socket
 to bind to as its source address before connecting. If the host is ''
@@ -855,8 +856,8 @@
 """ This is a subclass derived from SMTP that connects over an SSL encrypted
 socket (to use this class you need a socket module that was compiled with SSL
 support). If host is not specified, '' (the local host) is used. If port is
- omitted, the standard SMTP-over-SSL port (465) is used. The optional
- source_address takes a two-tuple (host,port) for socket to bind to. keyfile and certfile
+ omitted, the standard SMTP-over-SSL port (465) is used. local_hostname and
+ source_address have the same meaning as they do in the SMTP class. keyfile and certfile
 are also optional - they can contain a PEM formatted private key and
 certificate chain file for the SSL connection. context also optional, can contain
 a SSLContext, and is an alternative to keyfile and certfile; If it is specified both
@@ -905,7 +906,9 @@
 The LMTP protocol, which is very similar to ESMTP, is heavily based
 on the standard SMTP client. It's common to use Unix sockets for LMTP,
 so our connect() method must support that as well as a regular
- host:port server. To specify a Unix socket, you must use an absolute
+ host:port server. local_hostname and source_address have the same
+ meaning as they do in the SMTP class.
+ To specify a Unix socket, you must use an absolute
 path as the host, starting with a '/'.
 
 Authentication is supported, using the regular SMTP mechanism. When
-- 
Repository URL: http://hg.python.org/cpython
