Contributions by Eric Raymond: documentation for modules

cmd, multifile and smtplib.

1 files changed, 144 insertions, 0 deletions

diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex
new file mode 100644
index 0000000..90bbc1e1
--- /dev/null
+++ b/Doc/lib/libsmtplib.tex
@@ -0,0 +1,144 @@
+% Documentation by ESR
+\section{Standard Module \module{smtp}}
+\stmodindex{smtp}
+\label{module-smtp}
+
+The \code{smtp} module defines an SMTP session object that can be used
+to send mail to any Internet machine with an SMTP or ESMTP listener daemon.
+For details of SMTP and ESMTP operation, consult RFC 821 (Simple Mail
+Transfer Protocol) and RFC1869 (SMTP Service Extensions).
+
+\begin{classdesc}{SMTP}{\optional{host, port}}
+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 connect method is called with those parameters during
+initialization.
+
+For normal use, you should only require the initialization/connect,
+\var{sendmail}, and \var{quit} methods  An example is included below.
+\end{classdesc}
+
+\subsection{SMTP Objects}
+\label{SMTP-objects}
+
+A \class{SMTP} instance has the following methods:
+
+\begin{methoddesc}{set_debuglevel}{level}
+Set the debug output level.  A non-false value results in debug
+messages for connection and for all messages sent to and received from
+the server.
+\end{methoddesc}
+
+\begin{methoddesc}{connect}{\optional{host='localhost',port=0}}
+Connect to a host on a given port.
+
+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.
+
+Note:  This method is automatically invoked by __init__,
+if a host is specified during instantiation.
+\end{methoddesc}
+
+\begin{methoddesc}{docmd}{cmd, \optional{, argstring}}
+Send a command to the server.  The optional argument
+string is simply concatenated to the command.
+
+Get back a 2-tuple composed of a numeric response code and the actual
+response line (multiline responses are joined into one long line.)
+
+In normal operation it should not be necessary to call this method
+explicitly.  It is used to implement other methods and may be useful
+for testing private extensions.
+\end{methoddesc}
+
+\begin{methoddesc}{helo}{\optional{hostname}}
+Identify yourself to the SMTP server using HELO.  The hostname
+argument defaults to the FQDN of the local host.
+
+In normal operation it should not be necessary to call this method
+explicitly.  It will be implicitly called by the \var{sendmail} method
+when necessary.
+\end{methoddesc}
+
+\begin{methoddesc}{ehlo}{\optional{hostname}}
+Identify yourself to an ESMTP server using HELO.  The hostname
+argument defaults to the FQDN of the local host.  Examine the 
+response for ESMTP option and store them for use by the
+\var{has_option} method.
+
+Unless you wish to use the \var{has_option} method before sending
+mail, it should not be necessary to call this method explicitly.  It
+will be implicitly called by the \var{sendmail} method when necessary.
+\end{methoddesc}
+
+\begin{methoddesc}{has_option}{name}
+Return 1 if name is in the set of ESMTP options returned by the
+server, 0 otherwise.  Case is ignored.
+\end{methoddesc}
+
+\begin{methoddesc}{verify}{address}
+Check the validity of an address on this server using SMTP VRFY.
+Returns a tuple consisting of code 250 and a full RFC822 address
+(including human name) if the user address is valid. Otherwise returns
+an SMTP error code of 400 or greater and an error string.
+
+Note: many sites disable SMTP VRFY in order to foil spammers.
+\end{methoddesc}
+
+\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, options=[]}}
+Send mail.  The required arguments are an RFC822 from-address string,
+a list of RFC822 to-address strings, and a message string.  The caller
+may pass a list of ESMTP options to be used in MAIL FROM commands.
+
+If there has been no previous EHLO or HELO command this session, this
+method tries ESMTP EHLO first. If the server does ESMTP, message size
+and each of the specified options will be passed to it (if the option
+is in the feature set the server advertises).  If EHLO fails, HELO
+will be tried and ESMTP options suppressed.
+
+This method will return normally if the mail is accepted for at least 
+one recipient. Otherwise it will throw an exception (either
+SMTPSenderRefused, SMTPRecipientsRefused, or SMTPDataError)
+That is, if this method does not throw an exception, then someone 
+should get your mail.  If this method does not throw an exception,
+it returns a dictionary, with one entry for each recipient that was 
+refused. 
+\end{methoddesc}
+
+\begin{methoddesc}{quit}{}
+Terminate the SMTP session and close the connection.
+\end{methoddesc}
+
+Low-level methods corresponding to the standard SMTP/ESMTP commands
+HELP, RSET, NOOP, MAIL, RCPT, and DATA are also supported.  Normally
+these do not need to be called directly, so they are not documented
+here. For details, consult the module code.
+
+Example:
+
+\begin{verbatim}
+    import sys, rfc822
+
+    def prompt(prompt):
+        sys.stdout.write(prompt + ": ")
+        return string.strip(sys.stdin.readline())
+
+    fromaddr = prompt("From")
+    toaddrs  = string.splitfields(prompt("To"), ',')
+    print "Enter message, end with ^D:"
+    msg = ''
+    while 1:
+        line = sys.stdin.readline()
+        if not line:
+            break
+        msg = msg + line
+    print "Message length is " + `len(msg)`
+
+    server = SMTP('localhost')
+    server.set_debuglevel(1)
+    server.sendmail(fromaddr, toaddrs, msg)
+    server.quit()
+\end{verbatim}
+