diff options
Diffstat (limited to 'Doc/lib/libsmtplib.tex')
| -rw-r--r-- | Doc/lib/libsmtplib.tex | 51 |
1 files changed, 37 insertions, 14 deletions
diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex index a873a9d..26293d6 100644 --- a/Doc/lib/libsmtplib.tex +++ b/Doc/lib/libsmtplib.tex @@ -15,13 +15,16 @@ listener daemon. For details of SMTP and ESMTP operation, consult (\citetitle{SMTP Service Extensions}). \begin{classdesc}{SMTP}{\optional{host\optional{, port\optional{, - local_hostname}}}} + local_hostname\optional{, timeout}}}}} 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 \method{connect()} method is called with those parameters during initialization. An \exception{SMTPConnectError} is raised if the specified host doesn't respond correctly. +The optional \var{timeout} parameter specifies a timeout in seconds for the +connection attempt (if not specified, or passed as None, the global +default timeout setting will be used). For normal use, you should only require the initialization/connect, \method{sendmail()}, and \method{quit()} methods. An example is @@ -31,7 +34,7 @@ included below. \begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{, local_hostname\optional{, keyfile\optional{, - certfile}}}}}} + certfile\optional{, timeout}}}}}}} 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 \method{starttls()} is not appropriate. @@ -39,6 +42,26 @@ If \var{host} is not specified, the local host is used. If \var{port} is omitted, the standard SMTP-over-SSL port (465) is used. \var{keyfile} and \var{certfile} are also optional, and can contain a PEM formatted private key and certificate chain file for the SSL connection. +The optional \var{timeout} parameter specifies a timeout in seconds for the +connection attempt (if not specified, or passed as None, the global +default timeout setting will be used). +\end{classdesc} + +\begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{, + local_hostname}}}} + +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 +path for \var{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. + +\versionadded{2.6} + \end{classdesc} A nice selection of exceptions is defined as well: @@ -103,13 +126,13 @@ A nice selection of exceptions is defined as well: An \class{SMTP} instance has the following methods: -\begin{methoddesc}{set_debuglevel}{level} +\begin{methoddesc}[SMTP]{set_debuglevel}{level} Set the debug output level. A true value for \var{level} results in debug messages for connection and for all messages sent to and received from the server. \end{methoddesc} -\begin{methoddesc}{connect}{\optional{host\optional{, port}}} +\begin{methoddesc}[SMTP]{connect}{\optional{host\optional{, port}}} 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 (\character{:}) followed by a @@ -119,7 +142,7 @@ This method is automatically invoked by the constructor if a host is specified during instantiation. \end{methoddesc} -\begin{methoddesc}{docmd}{cmd, \optional{, argstring}} +\begin{methoddesc}[SMTP]{docmd}{cmd, \optional{, argstring}} Send a command \var{cmd} to the server. The optional argument \var{argstring} is simply concatenated to the command, separated by a space. @@ -136,7 +159,7 @@ If the connection to the server is lost while waiting for the reply, \exception{SMTPServerDisconnected} will be raised. \end{methoddesc} -\begin{methoddesc}{helo}{\optional{hostname}} +\begin{methoddesc}[SMTP]{helo}{\optional{hostname}} Identify yourself to the SMTP server using \samp{HELO}. The hostname argument defaults to the fully qualified domain name of the local host. @@ -146,7 +169,7 @@ explicitly. It will be implicitly called by the \method{sendmail()} when necessary. \end{methoddesc} -\begin{methoddesc}{ehlo}{\optional{hostname}} +\begin{methoddesc}[SMTP]{ehlo}{\optional{hostname}} Identify yourself to an ESMTP server using \samp{EHLO}. The hostname argument defaults to the fully qualified domain name of the local host. Examine the response for ESMTP option and store them for use by @@ -157,13 +180,13 @@ mail, it should not be necessary to call this method explicitly. It will be implicitly called by \method{sendmail()} when necessary. \end{methoddesc} -\begin{methoddesc}{has_extn}{name} +\begin{methoddesc}[SMTP]{has_extn}{name} Return \constant{True} if \var{name} is in the set of SMTP service extensions returned by the server, \constant{False} otherwise. Case is ignored. \end{methoddesc} -\begin{methoddesc}{verify}{address} +\begin{methoddesc}[SMTP]{verify}{address} Check the validity of an address on this server using SMTP \samp{VRFY}. Returns a tuple consisting of code 250 and a full \rfc{822} address (including human name) if the user address is valid. Otherwise returns @@ -172,7 +195,7 @@ an SMTP error code of 400 or greater and an error string. \note{Many sites disable SMTP \samp{VRFY} in order to foil spammers.} \end{methoddesc} -\begin{methoddesc}{login}{user, password} +\begin{methoddesc}[SMTP]{login}{user, password} Log in on an SMTP server that requires authentication. The arguments are the username and the password to authenticate with. If there has been no previous \samp{EHLO} or \samp{HELO} command this @@ -190,7 +213,7 @@ or may raise the following exceptions: \end{description} \end{methoddesc} -\begin{methoddesc}{starttls}{\optional{keyfile\optional{, certfile}}} +\begin{methoddesc}[SMTP]{starttls}{\optional{keyfile\optional{, certfile}}} Put the SMTP connection in TLS (Transport Layer Security) mode. All SMTP commands that follow will be encrypted. You should then call \method{ehlo()} again. @@ -199,8 +222,8 @@ If \var{keyfile} and \var{certfile} are provided, these are passed to the \refmodule{socket} module's \function{ssl()} function. \end{methoddesc} -\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, - mail_options, rcpt_options}} +\begin{methoddesc}[SMTP]{sendmail}{from_addr, to_addrs, msg\optional{, + mail_options, rcpt_options}} Send mail. The required arguments are an \rfc{822} from-address string, a list of \rfc{822} to-address strings (a bare string will be treated as a list with 1 address), and a message string. The caller @@ -256,7 +279,7 @@ an exception is raised. \end{methoddesc} -\begin{methoddesc}{quit}{} +\begin{methoddesc}[SMTP]{quit}{} Terminate the SMTP session and close the connection. \end{methoddesc} |