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).

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

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

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

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

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

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 не указан, используйте значение, заданное текущим 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 не указан, используйте значение, заданное текущим policy.

add_attachment(*args, content_manager=None, **kw): Если сообщение является multipart/mixed, создайте новый объект сообщения, передайте все аргументы в его метод set_content(), и attach() его в multipart. Если сообщение не является multipart, multipart/related, или multipart/alternative, вызовите make_mixed(), а затем выполните действия, как описано выше. Если content_manager не указан, используйте значение, заданное текущим policy. Если у добавленной части нет заголовка Content-Disposition, добавьте его со значением attachment. Этот метод можно использовать как для явных вложений (Content-Disposition: attachment), так и для inline вложений (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, за исключением того, что при вызове set_content() не добавляются заголовки MIME-Version, так как подчасти не нуждаются в собственных заголовках 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.11/library/email.message.html