Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-email.Iterators.html" /> | |
13 | <link rel="prev" href="module-email.Errors.html" /> | |
14 | <link rel="parent" href="module-email.html" /> | |
15 | <link rel="next" href="module-email.Iterators.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>12.2.9 Miscellaneous utilities</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="12.2.8 Exception and Defect" | |
25 | href="module-email.Errors.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="12.2 email " | |
28 | href="module-email.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="12.2.10 Iterators" | |
31 | href="module-email.Iterators.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="module-email.Errors.html">12.2.8 Exception and Defect</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-email.Iterators.html">12.2.10 Iterators</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0014290000000000000000"> | |
56 | 12.2.9 Miscellaneous utilities</A> | |
57 | </H2> | |
58 | <A NAME="module-email.Utils"></A> | |
59 | ||
60 | <P> | |
61 | There are several useful utilities provided in the <tt class="module">email.Utils</tt> | |
62 | module: | |
63 | ||
64 | <P> | |
65 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
66 | <td><nobr><b><tt id='l2h-3942' xml:id='l2h-3942' class="function">quote</tt></b>(</nobr></td> | |
67 | <td><var>str</var>)</td></tr></table></dt> | |
68 | <dd> | |
69 | Return a new string with backslashes in <var>str</var> replaced by two | |
70 | backslashes, and double quotes replaced by backslash-double quote. | |
71 | </dl> | |
72 | ||
73 | <P> | |
74 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
75 | <td><nobr><b><tt id='l2h-3943' xml:id='l2h-3943' class="function">unquote</tt></b>(</nobr></td> | |
76 | <td><var>str</var>)</td></tr></table></dt> | |
77 | <dd> | |
78 | Return a new string which is an <em>unquoted</em> version of <var>str</var>. | |
79 | If <var>str</var> ends and begins with double quotes, they are stripped | |
80 | off. Likewise if <var>str</var> ends and begins with angle brackets, they | |
81 | are stripped off. | |
82 | </dl> | |
83 | ||
84 | <P> | |
85 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
86 | <td><nobr><b><tt id='l2h-3944' xml:id='l2h-3944' class="function">parseaddr</tt></b>(</nobr></td> | |
87 | <td><var>address</var>)</td></tr></table></dt> | |
88 | <dd> | |
89 | Parse address - which should be the value of some address-containing | |
90 | field such as <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span> - into its constituent | |
91 | <em>realname</em> and <em>email address</em> parts. Returns a tuple of that | |
92 | information, unless the parse fails, in which case a 2-tuple of | |
93 | <code>('', '')</code> is returned. | |
94 | </dl> | |
95 | ||
96 | <P> | |
97 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
98 | <td><nobr><b><tt id='l2h-3945' xml:id='l2h-3945' class="function">formataddr</tt></b>(</nobr></td> | |
99 | <td><var>pair</var>)</td></tr></table></dt> | |
100 | <dd> | |
101 | The inverse of <tt class="method">parseaddr()</tt>, this takes a 2-tuple of the form | |
102 | <code>(realname, email_address)</code> and returns the string value suitable | |
103 | for a <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span> header. If the first element of | |
104 | <var>pair</var> is false, then the second element is returned unmodified. | |
105 | </dl> | |
106 | ||
107 | <P> | |
108 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
109 | <td><nobr><b><tt id='l2h-3946' xml:id='l2h-3946' class="function">getaddresses</tt></b>(</nobr></td> | |
110 | <td><var>fieldvalues</var>)</td></tr></table></dt> | |
111 | <dd> | |
112 | This method returns a list of 2-tuples of the form returned by | |
113 | <code>parseaddr()</code>. <var>fieldvalues</var> is a sequence of header field | |
114 | values as might be returned by <tt class="method">Message.get_all()</tt>. Here's a | |
115 | simple example that gets all the recipients of a message: | |
116 | ||
117 | <P> | |
118 | <div class="verbatim"><pre> | |
119 | from email.Utils import getaddresses | |
120 | ||
121 | tos = msg.get_all('to', []) | |
122 | ccs = msg.get_all('cc', []) | |
123 | resent_tos = msg.get_all('resent-to', []) | |
124 | resent_ccs = msg.get_all('resent-cc', []) | |
125 | all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs) | |
126 | </pre></div> | |
127 | </dl> | |
128 | ||
129 | <P> | |
130 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
131 | <td><nobr><b><tt id='l2h-3947' xml:id='l2h-3947' class="function">parsedate</tt></b>(</nobr></td> | |
132 | <td><var>date</var>)</td></tr></table></dt> | |
133 | <dd> | |
134 | Attempts to parse a date according to the rules in <a class="rfc" id='rfcref-90972' xml:id='rfcref-90972' | |
135 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>. | |
136 | however, some mailers don't follow that format as specified, so | |
137 | <tt class="function">parsedate()</tt> tries to guess correctly in such cases. | |
138 | <var>date</var> is a string containing an <a class="rfc" id='rfcref-90974' xml:id='rfcref-90974' | |
139 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> date, such as | |
140 | <code>"Mon, 20 Nov 1995 19:12:08 -0500"</code>. If it succeeds in parsing | |
141 | the date, <tt class="function">parsedate()</tt> returns a 9-tuple that can be passed | |
142 | directly to <tt class="function">time.mktime()</tt>; otherwise <code>None</code> will be | |
143 | returned. Note that fields 6, 7, and 8 of the result tuple are not | |
144 | usable. | |
145 | </dl> | |
146 | ||
147 | <P> | |
148 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
149 | <td><nobr><b><tt id='l2h-3948' xml:id='l2h-3948' class="function">parsedate_tz</tt></b>(</nobr></td> | |
150 | <td><var>date</var>)</td></tr></table></dt> | |
151 | <dd> | |
152 | Performs the same function as <tt class="function">parsedate()</tt>, but returns | |
153 | either <code>None</code> or a 10-tuple; the first 9 elements make up a tuple | |
154 | that can be passed directly to <tt class="function">time.mktime()</tt>, and the tenth | |
155 | is the offset of the date's timezone from UTC (which is the official | |
156 | term for Greenwich Mean Time)<A NAME="tex2html124" | |
157 | HREF="#foot58346"><SUP>12.3</SUP></A>. If the input | |
158 | string has no timezone, the last element of the tuple returned is | |
159 | <code>None</code>. Note that fields 6, 7, and 8 of the result tuple are not | |
160 | usable. | |
161 | </dl> | |
162 | ||
163 | <P> | |
164 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
165 | <td><nobr><b><tt id='l2h-3949' xml:id='l2h-3949' class="function">mktime_tz</tt></b>(</nobr></td> | |
166 | <td><var>tuple</var>)</td></tr></table></dt> | |
167 | <dd> | |
168 | Turn a 10-tuple as returned by <tt class="function">parsedate_tz()</tt> into a UTC | |
169 | timestamp. It the timezone item in the tuple is <code>None</code>, assume | |
170 | local time. Minor deficiency: <tt class="function">mktime_tz()</tt> interprets the | |
171 | first 8 elements of <var>tuple</var> as a local time and then compensates | |
172 | for the timezone difference. This may yield a slight error around | |
173 | changes in daylight savings time, though not worth worrying about for | |
174 | common use. | |
175 | </dl> | |
176 | ||
177 | <P> | |
178 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
179 | <td><nobr><b><tt id='l2h-3950' xml:id='l2h-3950' class="function">formatdate</tt></b>(</nobr></td> | |
180 | <td><var></var><big>[</big><var>timeval</var><big>[</big><var>, localtime</var><big>]</big><var></var><big>[</big><var>, usegmt</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
181 | <dd> | |
182 | Returns a date string as per <a class="rfc" id='rfcref-90976' xml:id='rfcref-90976' | |
183 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, e.g.: | |
184 | ||
185 | <P> | |
186 | <div class="verbatim"><pre> | |
187 | Fri, 09 Nov 2001 01:08:47 -0000 | |
188 | </pre></div> | |
189 | ||
190 | <P> | |
191 | Optional <var>timeval</var> if given is a floating point time value as | |
192 | accepted by <tt class="function">time.gmtime()</tt> and <tt class="function">time.localtime()</tt>, | |
193 | otherwise the current time is used. | |
194 | ||
195 | <P> | |
196 | Optional <var>localtime</var> is a flag that when <code>True</code>, interprets | |
197 | <var>timeval</var>, and returns a date relative to the local timezone | |
198 | instead of UTC, properly taking daylight savings time into account. | |
199 | The default is <code>False</code> meaning UTC is used. | |
200 | ||
201 | <P> | |
202 | Optional <var>usegmt</var> is a flag that when <code>True</code>, outputs a | |
203 | date string with the timezone as an ascii string <code>GMT</code>, rather | |
204 | than a numeric <code>-0000</code>. This is needed for some protocols (such | |
205 | as HTTP). This only applies when <var>localtime</var> is <code>False</code>. | |
206 | ||
207 | <span class="versionnote">New in version 2.4.</span> | |
208 | ||
209 | </dl> | |
210 | ||
211 | <P> | |
212 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
213 | <td><nobr><b><tt id='l2h-3951' xml:id='l2h-3951' class="function">make_msgid</tt></b>(</nobr></td> | |
214 | <td><var></var><big>[</big><var>idstring</var><big>]</big><var></var>)</td></tr></table></dt> | |
215 | <dd> | |
216 | Returns a string suitable for an <a class="rfc" id='rfcref-90978' xml:id='rfcref-90978' | |
217 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant | |
218 | <span class="mailheader">Message-ID:</span> header. Optional <var>idstring</var> if given, is | |
219 | a string used to strengthen the uniqueness of the message id. | |
220 | </dl> | |
221 | ||
222 | <P> | |
223 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
224 | <td><nobr><b><tt id='l2h-3952' xml:id='l2h-3952' class="function">decode_rfc2231</tt></b>(</nobr></td> | |
225 | <td><var>s</var>)</td></tr></table></dt> | |
226 | <dd> | |
227 | Decode the string <var>s</var> according to <a class="rfc" id='rfcref-90980' xml:id='rfcref-90980' | |
228 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. | |
229 | </dl> | |
230 | ||
231 | <P> | |
232 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
233 | <td><nobr><b><tt id='l2h-3953' xml:id='l2h-3953' class="function">encode_rfc2231</tt></b>(</nobr></td> | |
234 | <td><var>s</var><big>[</big><var>, charset</var><big>[</big><var>, language</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
235 | <dd> | |
236 | Encode the string <var>s</var> according to <a class="rfc" id='rfcref-90982' xml:id='rfcref-90982' | |
237 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. Optional | |
238 | <var>charset</var> and <var>language</var>, if given is the character set name | |
239 | and language name to use. If neither is given, <var>s</var> is returned | |
240 | as-is. If <var>charset</var> is given but <var>language</var> is not, the | |
241 | string is encoded using the empty string for <var>language</var>. | |
242 | </dl> | |
243 | ||
244 | <P> | |
245 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
246 | <td><nobr><b><tt id='l2h-3954' xml:id='l2h-3954' class="function">collapse_rfc2231_value</tt></b>(</nobr></td> | |
247 | <td><var>value</var><big>[</big><var>, errors</var><big>[</big><var>, | |
248 | fallback_charset</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
249 | <dd> | |
250 | When a header parameter is encoded in <a class="rfc" id='rfcref-90984' xml:id='rfcref-90984' | |
251 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> format, | |
252 | <tt class="method">Message.get_param()</tt> may return a 3-tuple containing the character | |
253 | set, language, and value. <tt class="function">collapse_rfc2231_value()</tt> turns this into | |
254 | a unicode string. Optional <var>errors</var> is passed to the <var>errors</var> | |
255 | argument of the built-in <tt class="function">unicode()</tt> function; it defaults to | |
256 | <code>replace</code>. Optional <var>fallback_charset</var> specifies the character set | |
257 | to use if the one in the <a class="rfc" id='rfcref-90986' xml:id='rfcref-90986' | |
258 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a> header is not known by Python; it defaults | |
259 | to <code>us-ascii</code>. | |
260 | ||
261 | <P> | |
262 | For convenience, if the <var>value</var> passed to | |
263 | <tt class="function">collapse_rfc2231_value()</tt> is not a tuple, it should be a string and | |
264 | it is returned unquoted. | |
265 | </dl> | |
266 | ||
267 | <P> | |
268 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
269 | <td><nobr><b><tt id='l2h-3955' xml:id='l2h-3955' class="function">decode_params</tt></b>(</nobr></td> | |
270 | <td><var>params</var>)</td></tr></table></dt> | |
271 | <dd> | |
272 | Decode parameters list according to <a class="rfc" id='rfcref-90988' xml:id='rfcref-90988' | |
273 | href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>. <var>params</var> is a | |
274 | sequence of 2-tuples containing elements of the form | |
275 | <code>(content-type, string-value)</code>. | |
276 | </dl> | |
277 | ||
278 | <P> | |
279 | ||
280 | <span class="versionnote">Changed in version 2.4: | |
281 | The <tt class="function">dump_address_pair()</tt> function has been removed; | |
282 | use <tt class="function">formataddr()</tt> instead..</span> | |
283 | ||
284 | <P> | |
285 | ||
286 | <span class="versionnote">Changed in version 2.4: | |
287 | The <tt class="function">decode()</tt> function has been removed; use the | |
288 | <tt class="method">Header.decode_header()</tt> method instead..</span> | |
289 | ||
290 | <P> | |
291 | ||
292 | <span class="versionnote">Changed in version 2.4: | |
293 | The <tt class="function">encode()</tt> function has been removed; use the | |
294 | <tt class="method">Header.encode()</tt> method instead..</span> | |
295 | ||
296 | ||
297 | <P> | |
298 | <BR><HR><H4>Footnotes</H4> | |
299 | <DL> | |
300 | <DT><A NAME="foot58346">... Time)</A><A | |
301 | href="module-email.Utils.html#tex2html124"><SUP>12.3</SUP></A></DT> | |
302 | <DD>Note that the sign of the timezone | |
303 | offset is the opposite of the sign of the <code>time.timezone</code> | |
304 | variable for the same timezone; the latter variable follows the | |
305 | POSIX standard while this module follows <a class="rfc" id='rfcref-90963' xml:id='rfcref-90963' | |
306 | href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>. | |
307 | ||
308 | </DD> | |
309 | </DL> | |
310 | <DIV CLASS="navigation"> | |
311 | <div class='online-navigation'> | |
312 | <p></p><hr /> | |
313 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
314 | <tr> | |
315 | <td class='online-navigation'><a rel="prev" title="12.2.8 Exception and Defect" | |
316 | href="module-email.Errors.html"><img src='../icons/previous.png' | |
317 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
318 | <td class='online-navigation'><a rel="parent" title="12.2 email " | |
319 | href="module-email.html"><img src='../icons/up.png' | |
320 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
321 | <td class='online-navigation'><a rel="next" title="12.2.10 Iterators" | |
322 | href="module-email.Iterators.html"><img src='../icons/next.png' | |
323 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
324 | <td align="center" width="100%">Python Library Reference</td> | |
325 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
326 | href="contents.html"><img src='../icons/contents.png' | |
327 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
328 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
329 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
330 | <td class='online-navigation'><a rel="index" title="Index" | |
331 | href="genindex.html"><img src='../icons/index.png' | |
332 | border='0' height='32' alt='Index' width='32' /></A></td> | |
333 | </tr></table> | |
334 | <div class='online-navigation'> | |
335 | <b class="navlabel">Previous:</b> | |
336 | <a class="sectref" rel="prev" href="module-email.Errors.html">12.2.8 Exception and Defect</A> | |
337 | <b class="navlabel">Up:</b> | |
338 | <a class="sectref" rel="parent" href="module-email.html">12.2 email </A> | |
339 | <b class="navlabel">Next:</b> | |
340 | <a class="sectref" rel="next" href="module-email.Iterators.html">12.2.10 Iterators</A> | |
341 | </div> | |
342 | </div> | |
343 | <hr /> | |
344 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
345 | </DIV> | |
346 | <!--End of Navigation Panel--> | |
347 | <ADDRESS> | |
348 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
349 | </ADDRESS> | |
350 | </BODY> | |
351 | </HTML> |