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 в текущее содержимое, которое должно быть None или списком объектов Message перед вызовом. После вызова содержимое всегда будет списком объектов Message. Если вы хотите установить содержимое в скалярный объект (например, строку), используйте set_payload() вместо этого.

get_payload([i[, decode]])

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

С необязательным аргументом i, get_payload() вернёт i-й элемент содержимого, считая с нуля, если is_multipart() равно True. IndexError будет поднят, если i меньше 0 или больше или равно количеству элементов в содержимом. Если содержимое является строкой (т. е. 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. Ответственность клиента — обеспечение соблюдения инвариантов содержимого. Необязательный параметр charset устанавливает кодировку символов по умолчанию; см. set_charset() для подробностей.

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

set_charset(charset)

Устанавливает кодировку символов содержимого на 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 отличаются, содержимое будет закодировано заново в output_charset. Если отсутствует существующий заголовок Content-Transfer-Encoding, содержимое будет закодировано с помощью указанного Charset, если необходимо, и будет добавлен заголовок с соответствующим значением. Если заголовок Content-Transfer-Encoding уже существует, предполагается, что содержимое уже правильно закодировано с помощью этого 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, связанный с содержимым сообщения.

Новое в версии 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]]])

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

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

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

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

Обратите внимание, что использование этого метода немного отличается от удаления старого заголовка 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, или она не типа text, то этот элемент в возвращаемом списке будет равен failobj.

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

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

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

preamble

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

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

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

epilogue

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

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

defects

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

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