rest25/library/email.rst => rest262/library/email.rst
n1-.. % Copyright (C) 2001-2006 Python Software Foundation
2-.. % Author: barry@python.org (Barry Warsaw)
3- 
4- 
5:mod:`email` --- An email and MIME handling package
6===================================================
7
8.. module:: email
9   :synopsis: Package supporting the parsing, manipulating, and generating email messages,
10              including MIME documents.
11.. moduleauthor:: Barry A. Warsaw <barry@python.org>
12.. sectionauthor:: Barry A. Warsaw <barry@python.org>
n9+.. Copyright (C) 2001-2007 Python Software Foundation
13
14
15.. versionadded:: 2.2
16
17The :mod:`email` package is a library for managing email messages, including
18MIME and other :rfc:`2822`\ -based message documents.  It subsumes most of the
19functionality in several older standard modules such as :mod:`rfc822`,
20:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as
47above.
48
49Also included are detailed specifications of all the classes and modules that
50the :mod:`email` package provides, the exception classes you might encounter
51while using the :mod:`email` package, some auxiliary utilities, and a few
52examples.  For users of the older :mod:`mimelib` package, or previous versions
53of the :mod:`email` package, a section on differences and porting is provided.
54
n52+Contents of the :mod:`email` package documentation:
53+ 
54+.. toctree::
55+ 
56+   email.message.rst
57+   email.parser.rst
58+   email.generator.rst
59+   email.mime.rst
60+   email.header.rst
61+   email.charset.rst
62+   email.encoders.rst
63+   email.errors.rst
64+   email.util.rst
65+   email.iterators.rst
66+   email-examples.rst
67+ 
55
56.. seealso::
57
58   Module :mod:`smtplib`
59      SMTP protocol client
60
61   Module :mod:`nntplib`
62      NNTP protocol client
n63- 
64- 
65-Representing an email message
66------------------------------
67- 
68- 
69-.. include:: email.message.rst
70- 
71- 
72-Parsing email messages
73-----------------------
74- 
75- 
76-.. include:: email.parser.rst
77- 
78- 
79-Generating MIME documents
80--------------------------
81- 
82- 
83-.. include:: email.generator.rst
84- 
85- 
86-Creating email and MIME objects from scratch
87---------------------------------------------
88- 
89- 
90-.. include:: email.mime.rst
91- 
92- 
93-Internationalized headers
94--------------------------
95- 
96- 
97-.. include:: email.header.rst
98- 
99- 
100-Representing character sets
101----------------------------
102- 
103- 
104-.. include:: email.charset.rst
105- 
106- 
107-Encoders
108---------
109- 
110- 
111-.. include:: email.encoders.rst
112- 
113- 
114-Exception and Defect classes
115-----------------------------
116- 
117- 
118-.. include:: email.errors.rst
119- 
120- 
121-Miscellaneous utilities
122------------------------
123- 
124- 
125-.. include:: email.util.rst
126- 
127- 
128-Iterators
129----------
130- 
131- 
132-.. include:: email.iterators.rst
133
134
135.. _email-pkg-history:
136
137Package History
138---------------
139
140This table describes the release history of the email package, corresponding to
141the version of Python that the package was released with.  For purposes of this
142document, when you see a note about change or added versions, these refer to the
n143-Python version the change was made it, *not* the email package version.  This
n86+Python version the change was made in, *not* the email package version.  This
144table also describes the Python compatibility of each version of the package.
145
146+---------------+------------------------------+-----------------------+
147| email version | distributed with             | compatible with       |
148+===============+==============================+=======================+
149| :const:`1.x`  | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
150+---------------+------------------------------+-----------------------+
151| :const:`2.5`  | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5     |
368:mod:`mimelib` provided some utility functions in its :mod:`address` and
369:mod:`date` modules.  All of these functions have been moved to the
370:mod:`email.utils` module.
371
372The ``MsgReader`` class/module has been removed.  Its functionality is most
373closely supported in the :func:`body_line_iterator` function in the
374:mod:`email.iterators` module.
375
n376- 
377-Examples
378---------
379- 
380-Here are a few examples of how to use the :mod:`email` package to read, write,
381-and send simple email messages, as well as more complex MIME messages.
382- 
383-First, let's see how to create and send a simple text message:
384- 
385- 
386-.. include:: ../includes/email-simple.py
387-   :literal:
388- 
389-Here's an example of how to send a MIME message containing a bunch of family
390-pictures that may be residing in a directory:
391- 
392- 
393-.. include:: ../includes/email-mime.py
394-   :literal:
395- 
396-Here's an example of how to send the entire contents of a directory as an email
397-message:  [#]_
398- 
399- 
400-.. include:: ../includes/email-dir.py
401-   :literal:
402- 
403-And finally, here's an example of how to unpack a MIME message like the one
404-above, into a directory of files:
405- 
406- 
407-.. include:: ../includes/email-unpack.py
408-   :literal:
409- 
410.. rubric:: Footnotes
411
412.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
t413- 
414-.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
415- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op