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

Исходный код: Lib/email/message.py

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

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

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

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

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

class email.message.Message(policy=compat32)

Если параметр policy указан (он должен быть экземпляром класса policy) используйте правила, которые он определяет, для обновления и сериализации представления сообщения. Если policy не задан, используйте политику compat32, которая поддерживает обратную совместимость с версией пакета email Python 3.2. Для получения дополнительной информации см. документацию policy.

Изменено в версии 3.3: Добавлен ключевой аргумент policy.

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

Возвращает всё сообщение, сглаженное в виде строки. При значении необязательного параметра unixfrom равном true, заголовок конверта включён в возвращаемую строку. По умолчанию unixfrom равно False. По соображениям обратной совместимости maxheaderlen по умолчанию равно 0, поэтому если вам нужно другое значение, вы должны явно его переопределить (значение, указанное для max_line_length в политике, будет проигнорировано этим методом). Аргумент policy может быть использован для переопределения политики по умолчанию, полученной из экземпляра сообщения. Это может быть использовано для управления некоторым форматированием, производимым методом, поскольку указанная политика будет передана в Generator.

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

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

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

Если объект сообщения содержит двоичные данные, которые не закодированы в соответствии со стандартами RFC, несовместимые данные будут заменены кодами неизвестных символов Юникода. (См. также as_bytes() и BytesGenerator.)

Изменено в версии 3.4: Добавлен ключевой аргумент policy.

__str__()

Эквивалентно as_string(). Позволяет str(msg) создавать строку, содержащую отформатированное сообщение.

as_bytes(unixfrom=False, policy=None)

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

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

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

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Добавлена в версии 3.4.

__bytes__()

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

Добавлена в версии 3.4.

is_multipart()

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

set_unixfrom(unixfrom)

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

get_unixfrom()

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

attach(payload)

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

get_payload(i=None, decode=False)

Возвращает текущее содержимое, которое будет списком объектов 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 отсутствует, содержимое возвращается как есть (недекодированное). Во всех случаях возвращаемое значение является двоичными данными. Если сообщение является составным, и флаг decode равен True, то None возвращается. Если содержимое закодировано base64 и не было полностью сформировано (отсутствует заполнение, символы вне алфавита base64), в свойство ошибок сообщения будет добавлена соответствующая ошибка (InvalidBase64PaddingDefect или InvalidBase64CharactersDefect, соответственно).

Когда decode равно False (значение по умолчанию), тело возвращается как строка без декодирования Content-Transfer-Encoding. Однако для Content-Transfer-Encoding 8bit производится попытка декодировать исходные байты с помощью charset , указанного в заголовке Content-Type, используя обработчик ошибок replace. Если charset не указан или если заданный charset не распознаётся пакетом email, тело декодируется с использованием кодировки по умолчанию ASCII.

set_payload(payload, charset=None)

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

get_charset()

Возвращает экземпляр Charset, связанный с полезной нагрузкой сообщения.

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

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

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

В модели, сгенерированной из байтов, любые значения заголовков, которые (вопреки RFC) содержат не-ASCII байты, при получении через этот интерфейс будут представлены как объекты Header с кодировкой символов unknown-8bit.

__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 из заголовков сообщения. Исключение не генерируется, если указанное поле отсутствует в заголовках.

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

Что даёт

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

replace_header(_name, _value)

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

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.

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_params(failobj=None, header='content-type', unquote=True)

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

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

get_param(param, failobj=None, header='content-type', unquote=True)

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

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

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

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

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

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

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

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

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

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

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

set_type(type, header='Content-Type', requote=True)

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

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

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

get_filename(failobj=None)

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

get_boundary(failobj=None)

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

set_boundary(boundary)

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

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

get_content_charset(failobj=None)

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

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

get_charsets(failobj=None)

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

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

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:

>>> 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 переходит к подчастям.

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

preamble

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

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

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

epilogue

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

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

defects

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