Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5b68362

Browse files
freddrakefreddrake
committed
Use the real name of the module: "smtplib", not "smtp".
Use logical (& consistent) markup. Added a see-also section at the end.
1 parent 8ec619f commit 5b68362

1 file changed

Lines changed: 73 additions & 56 deletions

File tree

‎Doc/lib/libsmtplib.tex‎

Lines changed: 73 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,56 @@
11
% Documentation by ESR
2-
\section{Standard Module \module{smtp}}
3-
\stmodindex{smtp}
4-
\label{module-smtp}
2+
\section{Standard Module \module{smtplib}}
3+
\stmodindex{smtplib}
4+
\label{module-smtplib}
55

6-
The \code{smtp} module defines an SMTP session object that can be used
7-
to send mail to any Internet machine with an SMTP or ESMTP listener daemon.
8-
For details of SMTP and ESMTP operation, consult RFC 821 (Simple Mail
9-
Transfer Protocol) and RFC1869 (SMTP Service Extensions).
6+
The \module{smtplib} module defines an SMTP session object that can be
7+
used to send mail to any Internet machine with an SMTP or ESMTP
8+
listener daemon. For details of SMTP and ESMTP operation, consult
9+
\rfc{821} (\emph{Simple Mail Transfer Protocol}) and \rfc{1869}
10+
(\emph{SMTP Service Extensions}).
1011

1112
\begin{classdesc}{SMTP}{\optional{host, port}}
1213
A \class{SMTP} instance encapsulates an SMTP connection. It has
1314
methods that support a full repertoire of SMTP and ESMTP
1415
operations. If the optional host and port parameters are given, the
15-
SMTP connect method is called with those parameters during
16+
SMTP \method{connect()} method is called with those parameters during
1617
initialization.
1718

1819
For normal use, you should only require the initialization/connect,
19-
\var{sendmail}, and \var{quit} methods An example is included below.
20+
\method{sendmail()}, and \method{quit()} methods An example is
21+
included below.
2022
\end{classdesc}
2123

2224
\subsection{SMTP Objects}
2325
\label{SMTP-objects}
2426

25-
A \class{SMTP} instance has the following methods:
27+
An \class{SMTP} instance has the following methods:
2628

2729
\begin{methoddesc}{set_debuglevel}{level}
28-
Set the debug output level. A non-false value results in debug
29-
messages for connection and for all messages sent to and received from
30-
the server.
30+
Set the debug output level. A true value for \var{level} results in
31+
debug messages for connection and for all messages sent to and
32+
received from the server.
3133
\end{methoddesc}
3234

33-
\begin{methoddesc}{connect}{\optional{host='localhost',port=0}}
35+
\begin{methoddesc}{connect}{\optional{host='localhost'\optional{, port=0}}}
3436
Connect to a host on a given port.
3537

36-
If the hostname ends with a colon (`:') followed by a number,
37-
that suffix will be stripped off and the number interpreted as
38+
If the hostname ends with a colon (\character{:}) followed by a
39+
number, that suffix will be stripped off and the number interpreted as
3840
the port number to use.
3941

40-
Note: This method is automatically invoked by __init__,
41-
if a host is specified during instantiation.
42+
Note: This method is automatically invoked by the constructor if a
43+
host is specified during instantiation.
4244
\end{methoddesc}
4345

4446
\begin{methoddesc}{docmd}{cmd, \optional{, argstring}}
45-
Send a command to the server. The optional argument
46-
string is simply concatenated to the command.
47+
Send a command \var{cmd} to the server. The optional argument
48+
\var{argstring} is simply concatenated to the command, separated by a
49+
space.
4750

48-
Get back a 2-tuple composed of a numeric response code and the actual
49-
response line (multiline responses are joined into one long line.)
51+
This returns a 2-tuple composed of a numeric response code and the
52+
actual response line (multiline responses are joined into one long
53+
line.)
5054

5155
In normal operation it should not be necessary to call this method
5256
explicitly. It is used to implement other methods and may be useful
@@ -58,38 +62,38 @@ \subsection{SMTP Objects}
5862
argument defaults to the FQDN of the local host.
5963

6064
In normal operation it should not be necessary to call this method
61-
explicitly. It will be implicitly called by the \var{sendmail} method
65+
explicitly. It will be implicitly called by the \method{sendmail()}
6266
when necessary.
6367
\end{methoddesc}
6468

6569
\begin{methoddesc}{ehlo}{\optional{hostname}}
6670
Identify yourself to an ESMTP server using HELO. The hostname
6771
argument defaults to the FQDN of the local host. Examine the
68-
response for ESMTP option and store them for use by the
69-
\var{has_option} method.
72+
response for ESMTP option and store them for use by
73+
\method{has_option()}.
7074

71-
Unless you wish to use the \var{has_option} method before sending
75+
Unless you wish to use \method{has_option()} before sending
7276
mail, it should not be necessary to call this method explicitly. It
73-
will be implicitly called by the \var{sendmail} method when necessary.
77+
will be implicitly called by \method{sendmail()} when necessary.
7478
\end{methoddesc}
7579

7680
\begin{methoddesc}{has_option}{name}
77-
Return 1 if name is in the set of ESMTP options returned by the
78-
server, 0 otherwise. Case is ignored.
81+
Return \code{1} if \var{name} is in the set of ESMTP options returned
82+
by the server, \code{0} otherwise. Case is ignored.
7983
\end{methoddesc}
8084

8185
\begin{methoddesc}{verify}{address}
8286
Check the validity of an address on this server using SMTP VRFY.
83-
Returns a tuple consisting of code 250 and a full RFC822 address
87+
Returns a tuple consisting of code 250 and a full \rfc{822} address
8488
(including human name) if the user address is valid. Otherwise returns
8589
an SMTP error code of 400 or greater and an error string.
8690

8791
Note: many sites disable SMTP VRFY in order to foil spammers.
8892
\end{methoddesc}
8993

9094
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, options=[]}}
91-
Send mail. The required arguments are an RFC822 from-address string,
92-
a list of RFC822 to-address strings, and a message string. The caller
95+
Send mail. The required arguments are an \rfc{822} from-address string,
96+
a list of \rfc{822} to-address strings, and a message string. The caller
9397
may pass a list of ESMTP options to be used in MAIL FROM commands.
9498

9599
If there has been no previous EHLO or HELO command this session, this
@@ -100,11 +104,12 @@ \subsection{SMTP Objects}
100104

101105
This method will return normally if the mail is accepted for at least
102106
one recipient. Otherwise it will throw an exception (either
103-
SMTPSenderRefused, SMTPRecipientsRefused, or SMTPDataError)
107+
\exception{SMTPSenderRefused}, \exception{SMTPRecipientsRefused}, or
108+
\exception{SMTPDataError}).
104109
That is, if this method does not throw an exception, then someone
105110
should get your mail. If this method does not throw an exception,
106111
it returns a dictionary, with one entry for each recipient that was
107-
refused.
112+
refused.
108113
\end{methoddesc}
109114

110115
\begin{methoddesc}{quit}{}
@@ -116,29 +121,41 @@ \subsection{SMTP Objects}
116121
these do not need to be called directly, so they are not documented
117122
here. For details, consult the module code.
118123

119-
Example:
124+
125+
\subsection{SMTP Example}
126+
\label{SMTP-example}
127+
128+
% really need a little description here...
120129

121130
\begin{verbatim}
122-
import sys, rfc822
123-
124-
def prompt(prompt):
125-
sys.stdout.write(prompt + ": ")
126-
return string.strip(sys.stdin.readline())
127-
128-
fromaddr = prompt("From")
129-
toaddrs = string.splitfields(prompt("To"), ',')
130-
print "Enter message, end with ^D:"
131-
msg = ''
132-
while 1:
133-
line = sys.stdin.readline()
134-
if not line:
135-
break
136-
msg = msg + line
137-
print "Message length is " + `len(msg)`
138-
139-
server = SMTP('localhost')
140-
server.set_debuglevel(1)
141-
server.sendmail(fromaddr, toaddrs, msg)
142-
server.quit()
131+
import sys, rfc822
132+
133+
def prompt(prompt):
134+
sys.stdout.write(prompt + ": ")
135+
return string.strip(sys.stdin.readline())
136+
137+
fromaddr = prompt("From")
138+
toaddrs = string.splitfields(prompt("To"), ',')
139+
print "Enter message, end with ^D:"
140+
msg = ''
141+
while 1:
142+
line = sys.stdin.readline()
143+
if not line:
144+
break
145+
msg = msg + line
146+
print "Message length is " + `len(msg)`
147+
148+
server = SMTP('localhost')
149+
server.set_debuglevel(1)
150+
server.sendmail(fromaddr, toaddrs, msg)
151+
server.quit()
143152
\end{verbatim}
144153

154+
155+
\begin{seealso}
156+
\seetext{\rfc{821}, \emph{Simple Mail Transfer Protocol}. Available
157+
online at \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt}.}
158+
159+
\seetext{\rfc{1869}, \emph{SMTP Service Extensions}. Available online
160+
at \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt}.}
161+
\end{seealso}

0 commit comments

Comments
 (0)