18.1.1. `email.message`: Представление сообщения электронной почты¶email.message: Representing an email message

Центральный класс в пакете email – это класс Message, импортируемый из модуля email.message. Он служит базовым для объектной модели email. Message предоставляет основные средства для установки и чтения полей заголовков и доступа к телам сообщений.

Концептуально объект Message состоит из заголовков и полезных нагрузок. Заголовки представляют собой имена и значения полей в стиле RFC 2822, где имя и значение поля разделяются двоеточием. Двоеточие не является частью ни имени, ни значения поля.

Заголовки хранятся и возвращаются с сохранением регистра, но сравниваются без учёта регистра. Также может присутствовать одиночный конвертный заголовок, известный как заголовок Unix-From или заголовок From_. Полезная нагрузка – это либо строка для простых сообщений, либо список объектов Message для MIME-контейнеров (например, multipart/* и message/rfc822).

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

Ниже приведены методы класса Message:

class email.message.Message¶

Конструктор не принимает аргументов.

as_string([unixfrom])¶

Возвращает всё сообщение в виде плоской строки. Если необязательный unixfrom равен True, в возвращаемую строку включается конвертный заголовок. unixfrom по умолчанию равен False. Уплощение сообщения может вызвать изменения в Message, если для завершения преобразования в строку необходимо заполнить значения по умолчанию (например, могут быть созданы или изменены MIME-границы).

Обратите внимание, что этот метод предоставляется для удобства и не всегда форматирует сообщение так, как требуется. Например, по умолчанию он искажает строки, начинающиеся с From. Для большей гибкости можно создать экземпляр Generator и использовать его метод flatten() напрямую. Например:

from cStringIO import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

__str__()¶: Эквивалентно as_string(unixfrom=True).

is_multipart()¶: Возвращает True, если полезная нагрузка сообщения является списком подобъектов Message, в противном случае возвращает False. Когда is_multipart() возвращает False, полезная нагрузка должна быть строковым объектом.

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

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

attach(payload)¶: Добавляет указанный payload к текущему payload, который до вызова должен быть None или списком объектов Message. После вызова payload всегда будет списком объектов Message. Если нужно установить payload в виде скалярного объекта (например, строки), используйте set_payload().

get_payload([i[, decode]])¶

Возвращает текущий payload: список объектов Message, если is_multipart() равно True, или строку, если is_multipart() равно False. Если payload является списком и вы изменяете его, вы изменяете payload сообщения на месте.

С необязательным аргументом i, get_payload() возвращает i-й элемент payload (нумерация с нуля), если is_multipart() равно True. Возникает IndexError, если i меньше 0 или больше или равно количеству элементов в payload. Если payload является строкой (т.е. is_multipart() равно False) и передан i, возникает TypeError.

Необязательный decode – флаг, указывающий, следует ли декодировать полезную нагрузку в соответствии с заголовком Content-Transfer-Encoding. Когда True и сообщение не является многокомпонентным, полезная нагрузка будет декодирована, если значение этого заголовка равно quoted-printable или base64. Если используется какая-либо другая кодировка, или заголовок Content-Transfer-Encoding отсутствует, или полезная нагрузка содержит некорректные данные base64, она возвращается как есть (недекодированной). Если сообщение является многокомпонентным и флаг decode равен True, возвращается None. Значение по умолчанию для decode – False.

set_payload(payload[, charset])¶: Устанавливает payload всего объекта сообщения в payload. Ответственность за соблюдение инвариантов payload лежит на клиенте. Необязательный charset задаёт кодировку сообщения по умолчанию; подробнее см. set_charset().

Изменено в версии 2.2.2: добавлен аргумент charset.

set_charset(charset)¶

Устанавливает кодировку payload в charset, который может быть экземпляром Charset (см. email.charset), строкой с названием кодировки или None. Если это строка, она преобразуется в экземпляр Charset. Если charset равен None, параметр charset удаляется из заголовка Content-Type (сообщение больше не изменяется). Любое другое значение вызывает TypeError.

Если отсутствует заголовок MIME-Version, он будет добавлен. Если отсутствует заголовок Content-Type, он будет добавлен со значением text/plain. Независимо от того, существует ли заголовок Content-Type, его параметр charset будет установлен в charset.output_charset. Если charset.input_charset и charset.output_charset различаются, payload будет перекодирован в output_charset. Если отсутствует заголовок Content-Transfer-Encoding, payload будет закодирован для передачи при необходимости с использованием указанного Charset, и будет добавлен соответствующий заголовок. Если заголовок Content-Transfer-Encoding уже существует, считается, что payload уже корректно закодирован с использованием этого Content-Transfer-Encoding, и он не изменяется.

Предполагается, что сообщение имеет тип text/*, а полезная нагрузка представлена либо в unicode, либо закодирована с помощью charset.input_charset. При создании текстового представления сообщения она будет закодирована или преобразована в charset.output_charset и при необходимости правильно закодирована для передачи. Заголовки MIME (MIME-Version, Content-Type, Content-Transfer-Encoding) будут добавлены по мере необходимости.

Новое в версии 2.2.2.

get_charset()¶: Возвращает экземпляр Charset, связанный с payload сообщения.

Новое в версии 2.2.2.

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

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

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

__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(), чтобы получить значения всех существующих заголовков с данным именем.

__setitem__(name, val)¶

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

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

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

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

has_key(name)¶: Возвращает true, если сообщение содержит поле заголовка с именем name, в противном случае возвращает false.

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

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

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

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

Вот несколько дополнительных полезных методов:

get_all(name[, failobj])¶: Возвращает список всех значений для поля с именем 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.

Вот пример:

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

Что даёт

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

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

Новое в версии 2.2.2.

get_content_type()¶

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

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

Новое в версии 2.2.2.

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

Новое в версии 2.2.2.

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

Новое в версии 2.2.2.

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

Новое в версии 2.2.2.

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

Новое в версии 2.2.2.

get_params([failobj[, header[, unquote]]])¶

Возвращает параметры заголовка Content-Type сообщения в виде списка. Элементы возвращаемого списка – кортежи из двух элементов (ключ/значение), разделённые знаком '='. Левая часть от '=' – ключ, а правая – значение. Если в параметре нет знака '=', значением является пустая строка; в противном случае значение соответствует get_param() и не экранируется, если необязательный параметр unquote равен True (по умолчанию).

Необязательный параметр failobj – объект, возвращаемый при отсутствии заголовка Content-Type. Необязательный параметр header – заголовок, который нужно искать вместо Content-Type.

Изменено в версии 2.2.2: unquote добавлен аргумент.

get_param(param[, failobj[, header[, unquote]]])¶

Возвращает значение параметра param заголовка Content-Type в виде строки. Если сообщение не содержит заголовка Content-Type или такого параметра нет, возвращается failobj (по умолчанию None).

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

Ключи параметров всегда сравниваются без учёта регистра. Возвращаемое значение может быть строкой или кортежем из трёх элементов, если параметр был закодирован по RFC 2231. Если это кортеж из трёх элементов, элементы значения имеют вид (CHARSET, LANGUAGE, VALUE). Обратите внимание, что и CHARSET, и LANGUAGE могут быть None; в этом случае следует считать, что VALUE закодирован в кодировке us-ascii. Обычно LANGUAGE можно игнорировать.

Если вашему приложению безразлично, был ли параметр закодирован по RFC 2231, можно свернуть значение параметра, вызвав email.utils.collapse_rfc2231_value() и передав возвращаемое значение из get_param(). Это вернёт подходящим образом декодированную строку Unicode, если значение является кортежем, или исходную строку без кавычек, если нет. Например:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

В любом случае значение параметра (возвращённая строка или элемент VALUE кортежа из трёх элементов) всегда не экранируется, если только unquote не установлен в False.

Изменено в версии 2.2.2: unquote добавлен аргумент, и стало возможным возвращаемое значение в виде кортежа из 3 элементов.

set_param(param, value[, header[, requote[, charset[, language]]]])¶

Устанавливает параметр в заголовке Content-Type. Если параметр уже существует в заголовке, его значение будет заменено на value. Если заголовок Content-Type ещё не задан для этого сообщения, он будет установлен в text/plain, а новое значение параметра будет добавлено в соответствии с RFC 2045.

Необязательный параметр header задаёт альтернативный заголовок для Content-Type; все параметры будут экранированы при необходимости, если только необязательный параметр requote не равен False (по умолчанию True).

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

Новое в версии 2.2.2.

del_param(param[, header[, requote]])¶: Полностью удаляет указанный параметр из заголовка Content-Type. Заголовок будет перезаписан на месте без параметра и его значения. Все значения будут экранированы при необходимости, если только requote не равен False (по умолчанию True). Необязательный параметр header задаёт альтернативу заголовку Content-Type.

Новое в версии 2.2.2.

set_type(type[, header][, requote])¶

Устанавливает основной тип и подтип для заголовка Content-Type. type должен быть строкой вида maintype/subtype, в противном случае возбуждается ValueError.

Этот метод заменяет заголовок Content-Type, сохраняя все параметры на месте. Если requote равен False, экранирование существующего заголовка остаётся без изменений; в противном случае параметры будут экранированы (по умолчанию).

Альтернативный заголовок можно указать в аргументе header. При установке заголовка Content-Type также добавляется заголовок MIME-Version.

Новое в версии 2.2.2.

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

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

set_boundary(boundary)¶

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

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

get_content_charset([failobj])¶

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

Обратите внимание, что этот метод отличается от get_charset(), который возвращает экземпляр Charset для кодировки тела сообщения по умолчанию.

Новое в версии 2.2.2.

get_charsets([failobj])¶

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

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

walk()¶

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

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

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

Изменено в версии 2.5: Ранее устаревшие методы get_type(), get_main_type() и get_subtype() были удалены.

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

preamble¶

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

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

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

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

Изменено в версии 2.5: Не нужно устанавливать эпилог в пустую строку, чтобы Generator выводил перевод строки в конце файла.

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

Новое в версии 2.4.

18.1.1. email.message: Представление сообщения электронной почты¶email.message: Representing an email message

18.1.1. `email.message`: Представление сообщения электронной почты¶email.message: Representing an email message