From 36beb66be9110c06b69c8b81c3fe286042d2d962 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Sun, 23 Jun 2013 15:47:50 -0400 Subject: #18179: document the local_hostname parameter. Original patch by Berker Peksag. --- 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 index 9593dea..9f67028 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -25,7 +25,10 @@ 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. 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 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). .. 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 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). 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 index f2c8452..4de846e 100644 --- a/Lib/smtplib.py +++ b/Lib/smtplib.py @@ -224,7 +224,8 @@ class SMTP: 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 @@ if _have_ssl: """ 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 @@ class LMTP(SMTP): 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 -- cgit v0.12 From 021362dbd4b1385dbb5cd36200bf790399a1335f Mon Sep 17 00:00:00 2001 From: R David Murray Date: Sun, 23 Jun 2013 16:05:44 -0400 Subject: #18179: reflow paragraphs. --- Doc/library/smtplib.rst | 48 ++++++++++++++++++++++++------------------------ Lib/smtplib.py | 45 +++++++++++++++++++++++---------------------- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 9f67028..c00476e 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -24,20 +24,20 @@ 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. 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 - 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. + host and port parameters are given, the SMTP :meth:`connect` method is + called 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 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. @@ -70,11 +70,11 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). 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. 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 - keyfile and certfile must be None. The optional *timeout* + 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 keyfile and certfile must be None. 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 @@ -97,12 +97,12 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). 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 they do in the :class:`SMTP` class. To specify a Unix socket, you must use - an absolute path for *host*, starting with a '/'. + 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 - socket, LMTP generally don't support or require any authentication, but your - mileage might vary. + Authentication is supported, using the regular SMTP mechanism. When using a + Unix socket, LMTP generally don't support or require any authentication, but + your mileage might vary. A nice selection of exceptions is defined as well: diff --git a/Lib/smtplib.py b/Lib/smtplib.py index 4de846e..072b973 100644 --- a/Lib/smtplib.py +++ b/Lib/smtplib.py @@ -222,14 +222,14 @@ 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. 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 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 '' - and port is 0, the OS default behavior will be used. + 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 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 '' and port is 0, the OS default behavior + will be used. """ self.timeout = timeout @@ -853,15 +853,17 @@ class SMTP: if _have_ssl: class SMTP_SSL(SMTP): - """ 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. 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 - keyfile and certfile must be None. + """ 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. 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 keyfile and certfile must be None. + """ default_port = SMTP_SSL_PORT @@ -904,12 +906,11 @@ class LMTP(SMTP): """LMTP - Local Mail Transfer Protocol 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 + 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. 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 '/'. + 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 using a Unix socket, LMTP generally don't support or require any -- cgit v0.12