Debian Codegraph @

Doc/library/email.rst

raw
1 :mod:`!email` --- An email and MIME handling package
2 ====================================================
3
4 .. module:: email
5 :synopsis: Package supporting the parsing, manipulating, and generating
6 email messages.
7 .. moduleauthor:: Barry A. Warsaw <[email protected]>,
8 R. David Murray <[email protected]>
9 .. sectionauthor:: R. David Murray <[email protected]>
10
11 **Source code:** :source:`Lib/email/__init__.py`
12
13 --------------
14
15 The :mod:`!email` package is a library for managing email messages. It is
16 specifically *not* designed to do any sending of email messages to SMTP
17 (:rfc:`2821`), NNTP, or other servers; those are functions of modules such as
18 :mod:`smtplib`. The :mod:`!email` package attempts to be as
19 RFC-compliant as possible, supporting :rfc:`5322` and :rfc:`6532`, as well as
20 such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`,
21 and :rfc:`2231`.
22
23 The overall structure of the email package can be divided into three major
24 components, plus a fourth component that controls the behavior of the other
25 components.
26
27 The central component of the package is an "object model" that represents email
28 messages. An application interacts with the package primarily through the
29 object model interface defined in the :mod:`~email.message` sub-module. The
30 application can use this API to ask questions about an existing email, to
31 construct a new email, or to add or remove email subcomponents that themselves
32 use the same object model interface. That is, following the nature of email
33 messages and their MIME subcomponents, the email object model is a tree
34 structure of objects that all provide the :class:`~email.message.EmailMessage`
35 API.
36
37 The other two major components of the package are the :mod:`~email.parser` and
38 the :mod:`~email.generator`. The parser takes the serialized version of an
39 email message (a stream of bytes) and converts it into a tree of
40 :class:`~email.message.EmailMessage` objects. The generator takes an
41 :class:`~email.message.EmailMessage` and turns it back into a serialized byte
42 stream. (The parser and generator also handle streams of text characters, but
43 this usage is discouraged as it is too easy to end up with messages that are
44 not valid in one way or another.)
45
46 The control component is the :mod:`~email.policy` module. Every
47 :class:`~email.message.EmailMessage`, every :mod:`~email.generator`, and every
48 :mod:`~email.parser` has an associated :mod:`~email.policy` object that
49 controls its behavior. Usually an application only needs to specify the policy
50 when an :class:`~email.message.EmailMessage` is created, either by directly
51 instantiating an :class:`~email.message.EmailMessage` to create a new email,
52 or by parsing an input stream using a :mod:`~email.parser`. But the policy can
53 be changed when the message is serialized using a :mod:`~email.generator`.
54 This allows, for example, a generic email message to be parsed from disk, but
55 to serialize it using standard SMTP settings when sending it to an email
56 server.
57
58 The email package does its best to hide the details of the various governing
59 RFCs from the application. Conceptually the application should be able to
60 treat the email message as a structured tree of unicode text and binary
61 attachments, without having to worry about how these are represented when
62 serialized. In practice, however, it is often necessary to be aware of at
63 least some of the rules governing MIME messages and their structure,
64 specifically the names and nature of the MIME "content types" and how they
65 identify multipart documents. For the most part this knowledge should only be
66 required for more complex applications, and even then it should only be the
67 high level structure in question, and not the details of how those structures
68 are represented. Since MIME content types are used widely in modern internet
69 software (not just email), this will be a familiar concept to many programmers.
70
71 The following sections describe the functionality of the :mod:`!email` package.
72 We start with the :mod:`~email.message` object model, which is the primary
73 interface an application will use, and follow that with the
74 :mod:`~email.parser` and :mod:`~email.generator` components. Then we cover the
75 :mod:`~email.policy` controls, which completes the treatment of the main
76 components of the library.
77
78 The next three sections cover the exceptions the package may raise and the
79 defects (non-compliance with the RFCs) that the :mod:`~email.parser` may
80 detect. Then we cover the :mod:`~email.headerregistry` and the
81 :mod:`~email.contentmanager` sub-components, which provide tools for doing more
82 detailed manipulation of headers and payloads, respectively. Both of these
83 components contain features relevant to consuming and producing non-trivial
84 messages, but also document their extensibility APIs, which will be of interest
85 to advanced applications.
86
87 Following those is a set of examples of using the fundamental parts of the APIs
88 covered in the preceding sections.
89
90 The foregoing represent the modern (unicode friendly) API of the email package.
91 The remaining sections, starting with the :class:`~email.message.Message`
92 class, cover the legacy :data:`~email.policy.compat32` API that deals much more
93 directly with the details of how email messages are represented. The
94 :data:`~email.policy.compat32` API does *not* hide the details of the RFCs from
95 the application, but for applications that need to operate at that level, they
96 can be useful tools. This documentation is also relevant for applications that
97 are still using the :mod:`~email.policy.compat32` API for backward
98 compatibility reasons.
99
100 .. versionchanged:: 3.6
101 Docs reorganized and rewritten to promote the new
102 :class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy`
103 API.
104
105 Contents of the :mod:`!email` package documentation:
106
107 .. toctree::
108
109 email.message.rst
110 email.parser.rst
111 email.generator.rst
112 email.policy.rst
113
114 email.errors.rst
115 email.headerregistry.rst
116 email.contentmanager.rst
117
118 email.examples.rst
119
120 Legacy API:
121
122 .. toctree::
123
124 email.compat32-message.rst
125 email.mime.rst
126 email.header.rst
127 email.charset.rst
128 email.encoders.rst
129 email.utils.rst
130 email.iterators.rst
131
132
133 .. seealso::
134
135 Module :mod:`smtplib`
136 SMTP (Simple Mail Transport Protocol) client
137
138 Module :mod:`poplib`
139 POP (Post Office Protocol) client
140
141 Module :mod:`imaplib`
142 IMAP (Internet Message Access Protocol) client
143
144 Module :mod:`mailbox`
145 Tools for creating, reading, and managing collections of messages on disk
146 using a variety standard formats.