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. Значения словаря — это строки с дополнительными методами. Заголовки хранятся и возвращаются в виде, сохраняющем регистр, но имена полей сопоставляются без учёта регистра. В отличие от реального словаря, ключи упорядочены, и могут быть дублирующие ключи. Предоставляются дополнительные методы для работы с заголовками, имеющими дублирующие ключи.

Поленая нагрузка — это либо строка, либо объект типа bytes, в случае простых сообщений, либо список объектов 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).

Обратите внимание, что этот метод предоставляется для удобства и может не быть самым полезным способом сериализации сообщений в вашем приложении, особенно если вы работаете с несколькими сообщениями. См. email.generator.Generator для более гибкого API сериализации сообщений. Также обратите внимание, что этот метод ограничен производством сериализованных сообщений, как «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)

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

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

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 в кавычки при необходимости. Если у объекта сообщения нет заголовка Content-Type, генерируется HeaderParseError.

Обратите внимание, что использование этого метода отличается от удаления старого заголовка Content-Type и добавления нового с новым значением boundary через 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, или она не имеет основного MIME типа text, то соответствующий элемент возвращаемого списка будет равен 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 не соответствует Content-ID ни одной из частей). При применении непосредственно к 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, используйте его как строку разделителя в составном объекте, иначе оставьте разделитель для автоматического создания при необходимости (например, при сериализации сообщения).

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-документа позволяет использовать некоторый текст между пустой строкой после заголовков и первой строкой разделителя составного объекта. Обычно этот текст не отображается в почтовом клиенте, поддерживающем MIME, так как он находится вне стандартной MIME-защиты. Однако при просмотре исходного текста сообщения или при просмотре сообщения в почтовом клиенте, не поддерживающем MIME, этот текст может отображаться.

Атрибут preamble содержит этот вводный дополнительный текст для 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–2022 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.8/library/email.message.html