Managing MIME Content — Python 3.8.20 documentation (original) (raw)

email.contentmanager: Managing MIME Content

Source code: Lib/email/contentmanager.py

New in version 3.6: 1

class 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:

If none of these keys produce a handler, raise a KeyError for the full MIME type.

set_content(msg, obj, *args, **kw)

If the maintype is multipart, raise a TypeError; otherwise look up a handler function based on the type of obj (see next paragraph), call clear_content() on the_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:

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 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, see get_content().

add_set_handler(typekey, handler)

Record handler as the function to call when an object of a type matching typekey is passed to set_content(). For the possible values of typekey, see set_content().

Content Manager Instances

Currently the email package provides only one concrete content manager,raw_data_manager, although more may be added in the future.raw_data_manager is thecontent_manager provided byEmailPolicy 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), anEmailMessage object (for message/rfc822parts), or a bytes object (for all other non-multipart types). Raise a KeyError if called on a multipart. If the part is atext part and errors is specified, use it as the error handler when decoding the payload to unicode. The default error handler isreplace.

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 header with a maintype/subtypevalue.

If charset is provided (which is valid only for str), encode the string to bytes using the specified character set. The default isutf-8. If the specified charset is a known alias for a standard MIME charset name, use the standard charset instead.

If cte is set, encode the payload using the specified content transfer encoding, and set the header to that value. Possible values for cte are quoted-printable,base64, 7bit, 8bit, and binary. If the input cannot be encoded in the specified encoding (for example, specifying a cte of7bit for an input that contains non-ASCII values), raise aValueError.

Note

A cte of binary does not actually work correctly yet. The EmailMessage object as modified by set_content is correct, but BytesGenerator does not serialize it correctly.

If disposition is set, use it as the value of the header. If not specified, and_filename_ is specified, add the header with the value attachment. If disposition is not specified and filename is also not specified, do not add the header. The only valid values for disposition areattachment and inline.

If filename is specified, use it as the value of the filenameparameter of the header.

If cid is specified, add a header with_cid_ as its value.

If params is specified, iterate its items method and use the resulting (key, value) pairs to set additional parameters on the header.

If headers is specified and is a list of strings of the formheadername: headervalue or a list of header objects (distinguished from strings by having a name attribute), add the headers to msg.

Footnotes

1

Originally added in 3.4 as a provisional module