email.contentmanager
: Managing MIME Content
¶
源代码： Lib/email/contentmanager.py
3.6 版新增： [1]
email.contentmanager.
ContentManager
¶
Base class for content managers. Provides the standard registry mechanisms to register converters between MIME content and other representations, as well as the
get_content
and
set_content
dispatch methods.
get_content
(
msg
,
*args
,
**kw
)
¶
Look up a handler function based on the
mimetype
of
msg
(see next paragraph), call it, passing through all arguments, and return the result of the call. The expectation is that the handler will extract the payload from
msg
and return an object that encodes information about the extracted data.
To find the handler, look for the following keys in the registry, stopping with the first one found:
- the string representing the full MIME type (
maintype/subtype)- the string representing the
maintype- the empty string
If none of these keys produce a handler, raise a
KeyError
for the full MIME type.
set_content
(
msg
,
obj
,
*args
,
**kw
)
¶
若
maintype
is
multipart
, raise a
TypeError
; otherwise look up a handler function based on the type of
obj
(see next paragraph), call
clear_content()
在
msg
, and call the handler function, passing through all arguments. The expectation is that the handler will transform and store
obj
into
msg
, possibly making other changes to
msg
as well, such as adding various MIME headers to encode information needed to interpret the stored data.
To find the handler, obtain the type of
obj
(
typ
=
type(obj)
), and look for the following keys in the registry, stopping with the first one found:
- the type itself (
typ)- the type’s fully qualified name (
typ.__module__ + '.' + typ.__qualname__).- the type’s qualname (
typ.__qualname__)- the type’s name (
typ.__name__).
If none of the above match, repeat all of the checks above for each of the types in the
MRO
(
typ.__mro__
). Finally, if no other key yields a handler, check for a handler for the key
None
. If there is no handler for
None
, raise a
KeyError
for the fully qualified name of the type.
Also add a
MIME-Version
header if one is not present (see also
MIMEPart
).
add_get_handler
(
key
,
handler
)
¶
Record the function
handler
as the handler for
key
. For the possible values of
key
，见
get_content()
.
add_set_handler
(
typekey
,
handler
)
¶
Record
handler
as the function to call when an object of a type matching
typekey
会被传递给
set_content()
. For the possible values of
typekey
，见
set_content()
.
Currently the email package provides only one concrete content manager,
raw_data_manager
, although more may be added in the future.
raw_data_manager
是
content_manager
provided by
EmailPolicy
and its derivatives.
email.contentmanager.
raw_data_manager
¶
This content manager provides only a minimum interface beyond that provided by
Message
itself: it deals only with text, raw byte strings, and
Message
objects. Nevertheless, it provides significant advantages compared to the base API:
get_content
on a text part will return a unicode string without the application needing to manually decode it,
set_content
provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the various
add_
methods, thereby simplifying the creation of multipart messages.
email.contentmanager.
get_content
(
msg
,
errors='replace'
)
¶
Return the payload of the part as either a string (for
text
parts), an
EmailMessage
object (for
message/rfc822
parts), or a
bytes
object (for all other non-multipart types). Raise a
KeyError
if called on a
multipart
. If the part is a
text
part and
errors
is specified, use it as the error handler when decoding the payload to unicode. The default error handler is
replace
.
email.contentmanager.
set_content
(
msg
,
<'str'>
,
subtype="plain"
,
charset='utf-8' cte=None
,
disposition=None
,
filename=None
,
cid=None
,
params=None
,
headers=None
)
¶
email.contentmanager.
set_content
(
msg
,
<'bytes'>
,
maintype
,
subtype
,
cte="base64"
,
disposition=None
,
filename=None
,
cid=None
,
params=None
,
headers=None
)
email.contentmanager.
set_content
(
msg
,
<'EmailMessage'>
,
cte=None
,
disposition=None
,
filename=None
,
cid=None
,
params=None
,
headers=None
)
Add headers and payload to msg :
Add a
Content-Type
header with a
maintype/subtype
值。
- For
str, set the MIMEmaintypetotext, and set the subtype to subtype if it is specified, orplainif it is not.- For
bytes, use the specified maintype and subtype , or raise aTypeErrorif they are not specified.- For
EmailMessageobjects, set the maintype tomessage, and set the subtype to subtype if it is specified orrfc822if it is not. If subtype ispartial, raise an error (bytesobjects must be used to constructmessage/partialparts).
若
charset
is provided (which is valid only for
str
), encode the string to bytes using the specified character set. The default is
utf-8
. If the specified
charset
is a known alias for a standard MIME charset name, use the standard charset instead.
若
cte
is set, encode the payload using the specified content transfer encoding, and set the
Content-Transfer-Encoding
header to that value. Possible values for
cte
are
quoted-printable
,
base64
,
7bit
,
8bit
，和
binary
. If the input cannot be encoded in the specified encoding (for example, specifying a
cte
of
7bit
for an input that contains non-ASCII values), raise a
ValueError
.
- For
strobjects, if cte is not set use heuristics to determine the most compact encoding.- For
EmailMessage, per RFC 2046 , raise an error if a cte ofquoted-printableorbase64is requested for subtyperfc822, and for any cte other than7bitfor subtypeexternal-body. Formessage/rfc822，使用8bitif cte is not specified. For all other values of subtype ，使用7bit.
注意
A
cte
of
binary
does not actually work correctly yet.
EmailMessage
object as modified by
set_content
is correct, but
BytesGenerator
does not serialize it correctly.
若
disposition
is set, use it as the value of the
Content-Disposition
header. If not specified, and
filename
is specified, add the header with the value
attachment
。若
disposition
is not specified and
filename
is also not specified, do not add the header. The only valid values for
disposition
are
attachment
and
inline
.
若
filename
is specified, use it as the value of the
filename
parameter of the
Content-Disposition
header.
若 cid is specified, add a Content-ID header with cid as its value.
若
params
is specified, iterate its
items
method and use the resulting
(key,
value)
pairs to set additional parameters on the
Content-Type
header.
若
headers
is specified and is a list of strings of the form
headername:
headervalue
or a list of
header
objects (distinguished from strings by having a
name
attribute), add the headers to
msg
.
脚注
| [1] | Originally added in 3.4 as a provisional module |