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

Skip to content

Commit 7969f31

Browse files
gvanrossumgvanrossum
committed
Updated documentation by Per Cederqvist. I've added back the
documentation sendmail() to reflect the changes by The Dragon (see smtplib.py checkin).
1 parent 8c67e4e commit 7969f31

1 file changed

Lines changed: 58 additions & 15 deletions

File tree

‎Doc/lib/libsmtplib.tex‎

Lines changed: 58 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,11 @@ \section{\module{smtplib} ---
1919
methods that support a full repertoire of SMTP and ESMTP
2020
operations. If the optional host and port parameters are given, the
2121
SMTP \method{connect()} method is called with those parameters during
22-
initialization.
22+
initialization. An \exception{SMTPConnectError} is raised if the
23+
specified host doesn't respond correctly.
2324

2425
For normal use, you should only require the initialization/connect,
25-
\method{sendmail()}, and \method{quit()} methods An example is
26+
\method{sendmail()}, and \method{quit()} methods. An example is
2627
included below.
2728
\end{classdesc}
2829

@@ -62,6 +63,9 @@ \subsection{SMTP Objects}
6263
In normal operation it should not be necessary to call this method
6364
explicitly. It is used to implement other methods and may be useful
6465
for testing private extensions.
66+
67+
If the connection to the server is lost while waiting for the reply an
68+
\exception{SMTPServerDisconnected} exception will be raised.
6569
\end{methoddesc}
6670

6771
\begin{methoddesc}{helo}{\optional{hostname}}
@@ -75,7 +79,7 @@ \subsection{SMTP Objects}
7579
\end{methoddesc}
7680

7781
\begin{methoddesc}{ehlo}{\optional{hostname}}
78-
Identify yourself to an ESMTP server using \samp{HELO}. The hostname
82+
Identify yourself to an ESMTP server using \samp{EHLO}. The hostname
7983
argument defaults to the fully qualified domain name of the local
8084
host. Examine the response for ESMTP option and store them for use by
8185
\method{has_option()}.
@@ -85,8 +89,8 @@ \subsection{SMTP Objects}
8589
will be implicitly called by \method{sendmail()} when necessary.
8690
\end{methoddesc}
8791

88-
\begin{methoddesc}{has_option}{name}
89-
Return \code{1} if \var{name} is in the set of ESMTP options returned
92+
\begin{methoddesc}{has_extn}{name}
93+
Return \code{1} if \var{name} is in the set of SMTP service extensions returned
9094
by the server, \code{0} otherwise. Case is ignored.
9195
\end{methoddesc}
9296

@@ -99,11 +103,17 @@ \subsection{SMTP Objects}
99103
Note: many sites disable SMTP \samp{VRFY} in order to foil spammers.
100104
\end{methoddesc}
101105

102-
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, options}}
106+
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{,
107+
mail_options, rcpt_options}}
103108
Send mail. The required arguments are an \rfc{822} from-address
104109
string, a list of \rfc{822} to-address strings, and a message string.
105-
The caller may pass a list of ESMTP options to be used in \samp{MAIL
106-
FROM} commands as \var{options}.
110+
The caller may pass a list of ESMTP options (such as \samp{8bitmime})
111+
to be used in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP
112+
options (such as \samp{DSN} commands) that should be used with all
113+
\samp{RCPT} commands can be passed as \var{rcpt_options}. (If you
114+
need to use different ESMTP options to different recipients you have
115+
to use the low-level methods such as \method{mail}, \method{rcpt} and
116+
\method{data} to send the message.)
107117

108118
If there has been no previous \samp{EHLO} or \samp{HELO} command this
109119
session, this method tries ESMTP \samp{EHLO} first. If the server does
@@ -112,13 +122,46 @@ \subsection{SMTP Objects}
112122
\samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options
113123
suppressed.
114124

115-
This method will return normally if the mail is accepted for at least
116-
one recipient. Otherwise it will throw an exception (either
117-
\exception{SMTPSenderRefused}, \exception{SMTPRecipientsRefused}, or
118-
\exception{SMTPDataError}). That is, if this method does not throw an
119-
exception, then someone should get your mail. If this method does not
120-
throw an exception, it returns a dictionary, with one entry for each
121-
recipient that was refused.
125+
This method will return normally if the mail is accepted for at least
126+
one recipient. Otherwise it will throw an exception. That is, if this
127+
method does not throw an exception, then someone should get your mail.
128+
If this method does not throw an exception, it returns a dictionary,
129+
with one entry for each recipient that was refused. Each entry
130+
contains a tuple of the SMTP error code and the accompanying error
131+
message sent by the server.
132+
133+
This method may raise the following exceptions:
134+
135+
\begin{itemize}
136+
137+
\item \exception{SMTPRecipientsRefused}
138+
139+
All recipients were refused. Nobody got the mail. The
140+
\var{recipients} attribute of the exception object is a dictionary
141+
with information about the refused recipients (like the one returned
142+
when at least one recipient was accepted).
143+
144+
\item \exception{SMTPHeloError}
145+
146+
The server didn't reply properly to
147+
the helo greeting. The connection has
148+
been closed.
149+
150+
\item \exception{SMTPSenderRefused}
151+
152+
The server didn't accept the from_addr.
153+
154+
\item \exception{SMTPDataError}
155+
156+
The server replied with an unexpected
157+
error code (other than a refusal of
158+
a recipient).
159+
160+
\end{itemize}
161+
162+
Unless otherwise noted the connection will be open even after
163+
an exception is raised.
164+
122165
\end{methoddesc}
123166

124167
\begin{methoddesc}{quit}{}

0 commit comments

Comments
 (0)