email.message: Представление электронного сообщения

Новая в версии 3.6: 1

Центральным классом в пакете email является класс EmailMessage, импортируемый из модуля email.message. Он является базовым классом для модели объектов email. EmailMessage предоставляет основную функциональность для установки и запроса полей заголовков, доступа к телам сообщений и создания или модификации структурированных сообщений.

Электронное сообщение состоит из заголовков и тела (также называемого содержимым). Заголовки представляют собой имена и значения полей в стиле RFC 5322 или RFC 6532, где имя поля и значение разделены двоеточием. Двоеточие не является частью имени поля или значения поля. Тело может быть простым текстовым сообщением, двоичным объектом или структурированной последовательностью подсообщений, каждое со своим набором заголовков и собственным телом. Последний тип тела указывается типом MIME сообщения, например, multipart/* или message/rfc822.

Концептуальная модель, предоставляемая объектом EmailMessage, представляет собой упорядоченный словарь заголовков, связанный с телом, которое представляет тело сообщения в формате RFC 5322, которое может быть списком под-EmailMessage объектов. Помимо обычных методов словаря для доступа к именам и значениям заголовков, существуют методы для доступа к специализированной информации из заголовков (например, типу содержимого MIME), для работы с телом, для генерации сериализованной версии сообщения и для рекурсивного обхода дерева объектов.

Интерфейс EmailMessage подобен словарю, и он индексируется именами заголовков, которые должны быть значениями ASCII. Значения словаря — это строки с дополнительными методами. Заголовки хранятся и возвращаются в форме, сохраняющей регистр, но имена полей сравниваются без учета регистра. В отличие от реального словаря, ключи упорядочены, и ключи могут повторяться. Предоставляются дополнительные методы для работы с заголовками, имеющими дублирующиеся ключи.

Тело — это либо строковый, либо байтовый объект в случае простых объектов сообщений, или список объектов EmailMessage для документов-контейнеров MIME, таких как multipart/* и message/rfc822 объекты сообщений.

class email.message.EmailMessage(policy=default)

Если задан параметр policy, используйте правила, которые он определяет, для обновления и сериализации представления сообщения. Если policy не задан, используйте политику default, которая следует правилам RFC для электронной почты, за исключением символов конца строки (вместо предписанных RFC \r\n, она использует стандартные Python \n символы конца строки). Для получения дополнительной информации см. документацию policy.

as_string(unixfrom=False, maxheaderlen=None, policy=None)

Возвращает всё сообщение, представленное как строка. Если необязательный параметр unixfrom равен True, заголовок конверта включается в возвращаемую строку. Значение unixfrom по умолчанию равно False. Для обратной совместимости с базовым классом Message принимается параметр maxheaderlen, но по умолчанию он равен None, что означает, что длина строки по умолчанию контролируется параметром max_line_length политики. Аргумент policy может быть использован для переопределения политики по умолчанию, полученной из экземпляра сообщения. Это может быть использовано для управления некоторыми форматами, производимыми методом, так как указанная policy будет передана в Generator.

Распаковка сообщения может вызвать изменения в EmailMessage, если необходимо заполнить значения по умолчанию для завершения преобразования в строку (например, могут быть сгенерированы или изменены MIME-разделители).

Обратите внимание, что этот метод предоставлен для удобства и может не быть наиболее полезным способом сериализации сообщений в вашем приложении, особенно если вы работаете с несколькими сообщениями. Для более гибкого API сериализации сообщений см. email.generator.Generator. Также обратите внимание, что этот метод ограничен созданием сериализованных сообщений, «чистых» в отношении 7 бит, когда utf8 имеет значение False, что является значением по умолчанию.

Изменено в версии 3.6: Поведение по умолчанию, когда maxheaderlen не указан, было изменено с значения по умолчанию 0 на значение по умолчанию max_line_length из политики.

__str__(): Эквивалентно as_string(policy=self.policy.clone(utf8=True)). Позволяет str(msg) генерировать строку, содержащую сериализованное сообщение в читаемом формате.

Изменено в версии 3.4: Метод был изменен на использование utf8=True, создавая представление сообщения в стиле RFC 6531, вместо прямого алиаса для as_string().

as_bytes(unixfrom=False, policy=None)

Возвращает всё сообщение, представленное как объект байтов. Если необязательный параметр unixfrom равен True, заголовок конверта включается в возвращаемую строку. Значение unixfrom по умолчанию равно False. Аргумент policy может быть использован для переопределения политики по умолчанию, полученной из экземпляра сообщения. Это может быть использовано для управления некоторыми форматами, производимыми методом, так как указанная policy будет передана в BytesGenerator.

__bytes__(): Эквивалентно as_bytes(). Позволяет bytes(msg) генерировать объект байтов, содержащий сериализованное сообщение.

is_multipart(): Возвращает True, если содержимое сообщения является списком вложенных объектов EmailMessage, иначе возвращает False. Когда is_multipart() возвращает False, содержимое должно быть строковым объектом (который может быть бинарным содержимым, закодированным CTE). Обратите внимание, что is_multipart() возвращает True, не обязательно означает, что «msg.get_content_maintype() == ‘multipart’» вернёт True. Например, is_multipart вернёт True, когда EmailMessage имеет тип message/rfc822.

set_unixfrom(unixfrom): Устанавливает заголовок конверта сообщения на unixfrom, который должен быть строкой. (См. mboxMessage для краткого описания этого заголовка.)

get_unixfrom(): Возвращает заголовок конверта сообщения. По умолчанию возвращает None, если заголовок конверта никогда не был установлен.

Следующие методы реализуют интерфейс типа отображения для доступа к заголовкам сообщения. Обратите внимание, что между этими методами и обычным интерфейсом отображения (например, словарем) есть некоторые семантические различия. Например, в словаре нет дублирующих ключей, а здесь могут быть дублирующиеся заголовки сообщения. Также в словарях нет гарантированного порядка ключей, возвращаемых методом keys(), но в объекте EmailMessage заголовки всегда возвращаются в порядке их появления в исходном сообщении или в порядке их добавления в сообщение позже. Любой удалённый и затем повторно добавленный заголовок всегда добавляется в конец списка заголовков.

Эти семантические различия являются умышленными и предвзятыми в пользу удобства в наиболее распространённых случаях использования.

Обратите внимание, что во всех случаях заголовок конверта, присутствующий в сообщении, не включается в интерфейс отображения.

__len__(): Возвращает общее количество заголовков, включая дубликаты.

__contains__(name)

Возвращает True, если в объекте сообщения есть поле с именем name. Сопоставление выполняется без учёта регистра, и name не включает заключительный двоеточие. Используется для оператора in. Например:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Возвращает значение поля заголовка с заданным именем. name не включает разделитель двоеточия. Если заголовок отсутствует, возвращается None; KeyError никогда не возникает.

Обратите внимание, что если заданное поле появляется более одного раза в заголовках сообщения, то какой из этих значений поля будет возвращён, не определено. Используйте метод get_all() для получения значений всех существующих заголовков с именем name.

Используя стандартные (не-compat32) политики, возвращаемое значение является экземпляром подкласса email.headerregistry.BaseHeader.

__setitem__(name, val)

Добавляет заголовок в сообщение с именем поля name и значением val. Поле добавляется в конец существующих заголовков сообщения.

Обратите внимание, что это не перезаписывает или удаляет любой существующий заголовок с таким же именем. Если вы хотите убедиться, что новый заголовок является единственным присутствующим в сообщении с именем поля name, удалите поле сначала, например:

del msg['subject']
msg['subject'] = 'Python roolz!'

Если policy определяет некоторые заголовки как уникальные (как это делают стандартные политики), этот метод может вызвать ValueError при попытке присвоить значение такому заголовку, когда он уже существует. Это поведение является умышленным для сохранения согласованности, но не полагайтесь на него, так как в будущем мы можем изменить такое присваивание, чтобы оно автоматически удаляло существующий заголовок.

__delitem__(name): Удаляет все вхождения поля с именем name из заголовков сообщения. Исключение не генерируется, если поле с заданным именем не присутствует в заголовках.

keys(): Возвращает список всех имён полей заголовков сообщения.

values(): Возвращает список всех значений полей сообщения.

items(): Возвращает список пар кортежей (2-кортежей), содержащих все заголовки и значения полей сообщения.

get(name, failobj=None): Возвращает значение поля с указанным именем заголовка. Это идентично __getitem__(), за исключением того, что в случае отсутствия заголовка с указанным именем возвращается необязательный failobj (по умолчанию None).

Вот некоторые дополнительные полезные методы, связанные с заголовками:

get_all(name, failobj=None): Возвращает список всех значений для поля с именем name. Если в сообщении нет заголовков с таким именем, возвращается failobj (по умолчанию None).

add_header(_name, _value, **_params)

Расширенная настройка заголовков. Этот метод похож на __setitem__(), за исключением того, что можно передавать дополнительные параметры заголовка в качестве ключевых аргументов. _name — добавляемое поле заголовка, _value — основное значение для заголовка.

Для каждого элемента в словаре ключевых аргументов _params, ключ используется как имя параметра, а подчеркивания заменяются дефисами (так как дефисы запрещены в идентификаторах Python). Обычно параметр добавляется как key="value", если значение не равно None, в этом случае добавляется только ключ.

Если значение содержит не-ASCII символы, кодировку и язык можно явно указать, задав значение как тройку в формате (CHARSET, LANGUAGE, VALUE), где CHARSET — строка, задающая кодировку для кодирования значения, LANGUAGE обычно может быть установлено как None или пустая строка (см. RFC 2231 для других возможностей), а VALUE — строка, содержащая не-ASCII символы. Если тройка не передаётся и значение содержит не-ASCII символы, оно автоматически кодируется в формате RFC 2231 с CHARSET utf-8 и LANGUAGE None.

Вот пример:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

Это добавит заголовок, похожий на

Content-Disposition: attachment; filename="bud.gif"

Пример расширенного интерфейса с не-ASCII символами:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

replace_header(_name, _value): Заменяет заголовок. Заменяет первый найденный в сообщении заголовок, соответствующий _name, сохраняя порядок заголовков и регистр имени поля исходного заголовка. Если соответствующий заголовок не найден, возникает исключение KeyError.

get_content_type()

Возвращает тип содержимого сообщения, приведённый к нижнему регистру в формате maintype/subtype. Если в сообщении нет заголовка Content-Type, возвращается значение, возвращаемое get_default_type(). Если заголовок Content-Type некорректен, возвращается text/plain.

(Согласно RFC 2045, у сообщений всегда есть тип по умолчанию, get_content_type() всегда вернёт значение. RFC 2045 определяет тип сообщения по умолчанию как text/plain, за исключением сообщений внутри контейнера multipart/digest, в этом случае это message/rfc822. Если заголовок Content-Type имеет некорректную спецификацию типа, RFC 2045 предписывает возвращать тип по умолчанию text/plain.)

get_content_maintype(): Возвращает основное содержимое типа сообщения. Это часть maintype строки, возвращаемой get_content_type().

get_content_subtype(): Возвращает подтип содержимого сообщения. Это часть subtype строки, возвращаемой get_content_type().

get_default_type(): Возвращает тип содержимого по умолчанию. У большинства сообщений тип содержимого по умолчанию — text/plain, за исключением подсообщений внутри контейнеров multipart/digest, для которых тип содержимого по умолчанию — message/rfc822.

set_default_type(ctype): Устанавливает тип содержимого по умолчанию. ctype должен быть либо text/plain, либо message/rfc822, хотя это не проверяется. Тип содержимого по умолчанию не хранится в заголовке Content-Type, поэтому он влияет только на возвращаемое значение методов get_content_type, когда в сообщении нет заголовка Content-Type.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Устанавливает параметр в заголовке Content-Type. Если параметр уже существует в заголовке, его значение заменяется на value. Когда header равен Content-Type (по умолчанию) и заголовок ещё не существует в сообщении, добавляется заголовок, его значение устанавливается на text/plain, и добавляется новое значение параметра. Необязательный header определяет альтернативный заголовок для Content-Type.

Если значение содержит не-ASCII символы, кодировку и язык можно явно указать, используя необязательные параметры charset и language. Необязательный language задаёт язык RFC 2231, по умолчанию пустая строка. charset и language должны быть строками. По умолчанию используется utf8 для charset и None для language.

Если replace равно False (по умолчанию), заголовок перемещается в конец списка заголовков. Если replace равно True, заголовок обновляется на месте.

Использование параметра requote с объектами EmailMessage устарело.

Обратите внимание, что существующие значения параметров заголовков можно получить через атрибут params значения заголовка (например, msg['Content-Type'].params['charset']).

Изменено в версии 3.4: replace ключевое слово было добавлено.

del_param(param, header='content-type', requote=True)

Полностью удаляет заданный параметр из заголовка Content-Type. Заголовок будет переписан на месте без параметра и его значения. Необязательный header указывает альтернативу заголовку Content-Type.

Использование параметра requote с объектами EmailMessage устарело.

get_filename(failobj=None): Возвращает значение параметра filename заголовка Content-Disposition сообщения. Если заголовок не имеет параметра filename, этот метод обращается к параметру name в заголовке Content-Type. Если ни тот, ни другой параметр не найден или заголовок отсутствует, возвращается failobj. Возвращаемая строка всегда будет без кавычек, как в email.utils.unquote().

get_boundary(failobj=None): Возвращает значение параметра boundary заголовка Content-Type сообщения или failobj, если заголовок отсутствует или не имеет параметра boundary. Возвращаемая строка всегда будет без кавычек, как в email.utils.unquote().

set_boundary(boundary)

Установите параметр boundary заголовка Content-Type в значение boundary. set_boundary() всегда будет заключать boundary в кавычки при необходимости. Возникает HeaderParseError, если у объекта сообщения нет заголовка Content-Type.

Обратите внимание, что использование этого метода отличается от удаления старого заголовка Content-Type и добавления нового со значением нового разделителя с помощью add_header(), так как set_boundary() сохраняет порядок заголовка Content-Type в списке заголовков.

get_content_charset(failobj=None): Возвращает параметр charset заголовка Content-Type, приведённый к нижнему регистру. Если заголовка Content-Type нет или этот заголовок не содержит параметра charset, возвращается failobj.

get_charsets(failobj=None)

Возвращает список, содержащий имена наборов символов в сообщении. Если сообщение является multipart, список будет содержать по одному элементу для каждой подчасти в полезной нагрузке, в противном случае он будет иметь длину 1.

Каждый элемент списка будет строкой, содержащей значение параметра charset в заголовке Content-Type для соответствующей подчасти. Если у подчасти нет заголовка Content-Type, параметра charset или она не является подтипом text основного MIME-типа, соответствующий элемент в возвращаемом списке будет failobj.

is_attachment(): Возвращает True, если есть заголовок Content-Disposition и его значение (независимо от регистра) равно attachment; False в противном случае.

Изменено в версии 3.4.2: is_attachment теперь является методом вместо свойства для согласованности с is_multipart().

get_content_disposition(): Возвращает значение заголовка Content-Disposition сообщения в нижнем регистре (без параметров), если оно есть, или None. Возможные значения для этого метода — inline, attachment или None, если сообщение соответствует RFC 2183.

Введено в версии 3.5.

Следующие методы относятся к опросу и манипулированию содержимым (полезной нагрузкой) сообщения.

walk()

Метод walk() — это универсальный генератор, который можно использовать для итерации по всем частям и подчастям дерева объекта сообщения в порядке обхода в глубину. Обычно вы используете walk() в качестве итератора в цикле for; на каждой итерации возвращается следующая подчасть.

Вот пример, который выводит тип MIME каждой части структуры сообщения multipart:

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk итерируется по подчастям любой части, где is_multipart() возвращает True, даже если msg.get_content_maintype() == 'multipart' может возвращать False. Мы можем увидеть это в нашем примере, используя вспомогательную функцию отладки _structure:

>>> from email.iterators import _structure
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

Здесь части message не являются multiparts, но они содержат подчасти. is_multipart() возвращает True и walk спускается к подчастям.

get_body(preferencelist=('related', 'html', 'plain'))

Возвращает MIME-часть, которая является лучшим кандидатом на роль «тела» сообщения.

preferencelist должен быть последовательностью строк из набора related, html и plain и указывает порядок предпочтения типа содержимого возвращаемой части.

Начните поиск соответствий с объекта, на котором вызывается метод get_body.

Если related не включён в preferencelist, рассмотрите корневую часть (или подчасть корневой части) любой связанной встреченной части, если (под-)часть соответствует предпочтению.

При обнаружении multipart/related проверьте параметр start и, если найдена часть с соответствующим заголовком Content-ID, рассмотрите только её при поиске соответствий кандидатов. В противном случае рассмотрите только первую (по умолчанию корневую) часть multipart/related.

Если ни одна из частей не соответствует ни одному из предпочтений в preferencelist, возвращает None.

Примечания: (1) Для большинства приложений единственными комбинациями preferencelist, которые действительно имеют смысл, являются ('plain',), ('html', 'plain') и значение по умолчанию ('related', 'html', 'plain'). (2) Поскольку сопоставление начинается с объекта, на котором вызывается get_body, вызов get_body на multipart/related вернёт сам объект, если preferencelist не имеет значения по умолчанию. (3) Сообщения (или части сообщений), не указывающие заголовок Content-Type или имеющие некорректный заголовок Content-Type, будут обрабатываться как имеющие тип text/plain, что иногда может привести к тому, что get_body вернёт неожиданные результаты.

iter_attachments(): Возвращает итератор по всем непосредственным подчастям сообщения, которые не являются частями «тела»—кандидатами. То есть пропустите первое вхождение каждой из text/plain, text/html, multipart/related или multipart/alternative (если они явно не помечены как вложения с помощью Content-Disposition: attachment) и верните все остальные части. При непосредственном применении к multipart/related возвращает итератор по всем связанным частям, за исключением корневой части (т. е. части, на которую указывает параметр start, или первой части, если нет параметра start или параметр start не соответствует идентификатору содержимого ни одной из частей). При непосредственном применении к multipart/alternative или не-multipart возвращает пустой итератор.

iter_parts(): Возвращает итератор по всем непосредственным подчастям сообщения, который будет пустым для не-multipart. (См. также walk().)

get_content(*args, content_manager=None, **kw): Вызывает метод get_content() объекта content_manager, передавая self в качестве объекта сообщения и передавая любые другие аргументы или ключевые слова в качестве дополнительных аргументов. Если content_manager не указан, используйте content_manager, определённый текущим policy.

set_content(*args, content_manager=None, **kw): Вызывает метод set_content() объекта content_manager, передавая self в качестве объекта сообщения и передавая любые другие аргументы или ключевые слова в качестве дополнительных аргументов. Если content_manager не указан, используйте content_manager, определённый текущим policy.

make_related(boundary=None): Преобразует сообщение, которое не является multipart, в сообщение multipart/related, перемещая все существующие заголовки Content- и полезную нагрузку в первую (новую) часть multipart. Если boundary указан, используйте его в качестве строки разделителя в multipart, иначе оставьте разделитель для автоматического создания при необходимости (например, при сериализации сообщения).

make_alternative(boundary=None): Преобразует сообщение, которое не является multipart или multipart/related, в сообщение multipart/alternative, перемещая все существующие заголовки Content- и полезную нагрузку в первую (новую) часть multipart. Если boundary указан, используйте его в качестве строки разделителя в multipart, иначе оставьте разделитель для автоматического создания при необходимости (например, при сериализации сообщения).

make_mixed(boundary=None): Преобразуйте не-multipart, multipart/related или multipart-alternative в multipart/mixed, переместив все существующие заголовки Content- и содержимое в первую (новую) часть multipart. Если указан boundary, используйте его как строку раздела в multipart, иначе оставьте раздел для автоматического создания при необходимости (например, при сериализации сообщения).

add_related(*args, content_manager=None, **kw): Если сообщение является multipart/related, создайте новый объект сообщения, передайте все аргументы в его метод set_content(), и attach() его в multipart. Если сообщение — не-multipart, вызовите make_related(), а затем выполните вышеуказанные действия. Если сообщение — любой другой тип multipart, вызовите TypeError. Если content_manager не указан, используйте значение content_manager, заданное текущим policy. Если у добавленной части нет заголовка Content-Disposition, добавьте его со значением inline.

add_alternative(*args, content_manager=None, **kw): Если сообщение является multipart/alternative, создайте новый объект сообщения, передайте все аргументы в его метод set_content(), и attach() его в multipart. Если сообщение — не-multipart или multipart/related, вызовите make_alternative(), а затем выполните вышеуказанные действия. Если сообщение — любой другой тип multipart, вызовите TypeError. Если content_manager не указан, используйте значение content_manager, заданное текущим policy.

add_attachment(*args, content_manager=None, **kw): Если сообщение является multipart/mixed, создайте новый объект сообщения, передайте все аргументы в его метод set_content(), и attach() его в multipart. Если сообщение — не-multipart, multipart/related или multipart/alternative, вызовите make_mixed(), а затем выполните вышеуказанные действия. Если content_manager не указан, используйте значение content_manager, заданное текущим policy. Если у добавленной части нет заголовка Content-Disposition, добавьте его со значением attachment. Этот метод может использоваться как для явных вложений (Content-Disposition: attachment), так и для вложений по умолчанию (Content-Disposition: inline), передавая соответствующие параметры в content_manager.

clear(): Удалить содержимое и все заголовки.

clear_content(): Удалить содержимое и все заголовки Content-, сохранив при этом все остальные заголовки в исходном порядке.

EmailMessage объекты имеют следующие атрибуты экземпляра:

preamble

Формат MIME-документа позволяет использовать некоторый текст между пустой строкой после заголовков и первой строкой раздела multipart. Обычно этот текст не отображается в почтовом клиенте, совместимом с MIME, так как он находится вне стандартного защитного барьера MIME. Однако при просмотре исходного текста сообщения или при просмотре сообщения в почтовом клиенте, не совместимом с MIME, этот текст может отобразиться.

Атрибут preamble содержит этот вводный текст вне стандартного барьера MIME для MIME-документов. Когда Parser обнаруживает текст после заголовков, но перед первой строкой раздела, он присваивает этот текст атрибуту preamble сообщения. При записи Generator текстового представления MIME-сообщения, и он обнаруживает, что у сообщения есть атрибут preamble, он запишет этот текст в области между заголовками и первым разделителем. См. email.parser и email.generator для получения более подробной информации.

Обратите внимание, что если у объекта сообщения нет преамбулы, атрибут preamble будет None.

epilogue: Атрибут epilogue действует аналогично атрибуту preamble, за исключением того, что он содержит текст, который появляется между последним разделителем и концом сообщения. Как и в случае с preamble, если текста эпилога нет, этот атрибут будет None.

defects: Атрибут defects содержит список всех проблем, обнаруженных при парсинге этого сообщения. См. email.errors для подробного описания возможных ошибок при разборе.

class email.message.MIMEPart(policy=default): Этот класс представляет собой подчасть MIME-сообщения. Он идентичен EmailMessage, за исключением того, что заголовки MIME-Version не добавляются при вызове set_content(), так как подчасти не нуждаются в собственных заголовках MIME-Version.

Примечания

1: Впервые добавлено в 3.4 как провизионный модуль. Документация для устаревшего класса сообщений перенесена в email.message.Message: Представление электронного сообщения с помощью API compat32.

© 2001–2023 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.10/library/email.message.html