email.parser: Парсинг сообщений электронной почты

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

Структуры объектов сообщений можно создать двумя способами: создать их с нуля, используя объект EmailMessage, добавив заголовки с помощью интерфейса словаря и добавив содержимое (payload) с помощью set_content() и связанных методов, или создать их, разобрав сериализованное представление сообщения электронной почты.

Пакет email предоставляет стандартный парсер, который понимает большинство структур документов электронной почты, включая MIME-документы. Вы можете передать парсеру объект типа bytes, string или file, и парсер вернёт вам корневой объект EmailMessage структуры. Для простых, не-MIME сообщений, содержимое (payload) этого корневого объекта, скорее всего, будет строкой, содержащей текст сообщения. Для MIME-сообщений корневой объект вернёт True от своего метода is_multipart(), а к подчастям можно получить доступ с помощью методов обработки содержимого (payload), таких как get_body(), iter_parts() и walk().

На самом деле доступны два интерфейса парсеров: API Parser и инкрементный API FeedParser. API Parser наиболее полезен, если у вас есть весь текст сообщения в памяти или если всё сообщение находится в файле на файловой системе. FeedParser более уместен, когда вы читаете сообщение из потока, который может блокироваться в ожидании дополнительного ввода (например, при чтении сообщения электронной почты из сокета). FeedParser может потреблять и парсить сообщение по частям и возвращает только корневой объект при закрытии парсера.

Обратите внимание, что парсер можно расширить ограниченными способами, и, конечно, вы можете реализовать свой собственный парсер с нуля. Вся логика, связывающая встроенный парсер пакета email и класс EmailMessage, содержится в классе policy, поэтому пользовательский парсер может создавать деревья объектов сообщений любым необходимым способом, реализовав пользовательские версии соответствующих методов policy.

19.1.2.1. API FeedParser

Класс BytesFeedParser, импортированный из модуля email.feedparser, предоставляет API, подходящий для пошагового разбора сообщений электронной почты, например, при чтении текста сообщения электронной почты из источника, который может блокироваться (например, из сокета). Класс BytesFeedParser, конечно, может использоваться для полного разбора сообщения электронной почты, содержащегося в объекте типа bytes, строке или файле, но API BytesParser может быть более удобным для таких случаев. Семантика и результаты двух API парсеров идентичны.

API класса BytesFeedParser прост: вы создаёте экземпляр, передаёте ему последовательность байтов до тех пор, пока не закончатся данные, затем закрываете парсер, чтобы получить корневой объект сообщения. Класс BytesFeedParser чрезвычайно точен при разборе сообщений, соответствующих стандартам, и хорошо справляется с разбором несоответствующих сообщений, предоставляя информацию о том, как сообщение было признано некорректным. Он заполнит атрибут defects объекта сообщения списком всех обнаруженных проблем в сообщении. Смотрите модуль email.errors для списка дефектов, которые он может найти.

Вот API для класса BytesFeedParser:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

Создайте экземпляр BytesFeedParser. Необязательный параметр _factory — это функция без аргументов; если он не указан, используется message_factory из policy. Вызывайте _factory всякий раз, когда нужен новый объект сообщения.

Если указан параметр policy, используются его правила для обновления представления сообщения. Если policy не задан, используется политика compat32, которая поддерживает обратную совместимость с версией пакета email Python 3.2 и предоставляет Message в качестве значения по умолчанию для параметра factory. Все остальные политики предоставляют EmailMessage в качестве значения по умолчанию для _factory. Для получения дополнительной информации о том, что ещё контролирует policy, смотрите документацию policy.

Примечание: Параметр policy всегда должен быть указан; значение по умолчанию будет изменено на email.policy.default в будущих версиях Python.

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

Изменено в версии 3.3: Добавлен параметр policy.

Изменено в версии 3.6: По умолчанию _factory имеет значение, задаваемое политикой message_factory.

feed(data)

Передать парсеру дополнительные данные. data должен быть объектом типа bytes-like object, содержащим одну или несколько строк. Строки могут быть частичными, и парсер правильно склеит такие частичные строки. Строки могут иметь любой из трёх стандартных символов конца строки: возврат каретки, перевод строки или возврат каретки и перевод строки (они могут быть даже смешанными).

close()

Завершить разбор всех ранее переданных данных и вернуть корневой объект сообщения. Не определено, что происходит, если метод feed() вызывается после вызова этого метода.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

Работает как BytesFeedParser, за исключением того, что входные данные для метода feed() должны быть строкой. Это имеет ограниченное применение, так как единственный способ сделать такое сообщение корректным — это если оно содержит только текст ASCII или, если utf8 имеет значение True, никаких бинарных вложений.

Изменено в версии 3.3: Добавлен параметр policy.

19.1.2.2. API Parser

Класс BytesParser, импортированный из модуля email.parser, предоставляет API для разбора сообщения, когда все содержимое сообщения доступно в объекте типа байты или файле. Модуль email.parser также предоставляет Parser для разбора строк и парсеры только заголовков, BytesHeaderParser и HeaderParser, которые могут быть использованы, если вас интересуют только заголовки сообщения. BytesHeaderParser и HeaderParser могут быть значительно быстрее в таких ситуациях, поскольку они не пытаются разобрать тело сообщения, вместо этого устанавливая содержимое в исходное тело.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

Создайте экземпляр BytesParser. Аргументы _class и policy имеют такое же значение и семантику, что и аргументы _factory и policy класса BytesFeedParser.

Примечание: Ключевое слово policy должно всегда указываться; по умолчанию будет email.policy.default в будущих версиях Python.

Изменено в версии 3.3: Удалён устаревший аргумент strict (был удалён в версии 2.4). Добавлено ключевое слово policy.

Изменено в версии 3.6: По умолчанию _class устанавливается в политику message_factory.

parse(fp, headersonly=False)

Прочитайте все данные из объекта-подобного файлу fp, обработайте полученные байты и верните объект сообщения. fp должен поддерживать как метод readline(), так и метод read().

Байты, содержащиеся в fp, должны быть отформатированы как блок заголовков в стиле RFC 5322 (или, если utf8 равно True, RFC 6532) и строки продолжения заголовков, необязательно с заголовком конверта. Блок заголовков завершается либо концом данных, либо пустой строкой. После блока заголовков следует тело сообщения (которое может содержать кодированные MIME-подчасти, включая подчасти с Content-Transfer-Encoding типа 8bit).

Необязательный параметр headersonly — флаг, указывающий, нужно ли прекратить разбор после чтения заголовков. По умолчанию значение False, что означает, что он обрабатывает всё содержимое файла.

parsebytes(bytes, headersonly=False)

Аналогично методу parse(), но принимает объект типа байты вместо объекта типа файл. Вызов этого метода на объекте типа байты эквивалентен первому обертыванию байтов в экземпляр BytesIO и последующему вызову parse().

Необязательный параметр headersonly такой же, как и в методе parse().

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

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Точно такой же, как BytesParser, за исключением того, что headersonly по умолчанию True.

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

class email.parser.Parser(_class=None, *, policy=policy.compat32)

Этот класс аналогичен BytesParser, но обрабатывает входные данные в виде строк.

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

Изменено в версии 3.6: По умолчанию _class устанавливается в политику message_factory.

parse(fp, headersonly=False)

Прочитайте все данные из объекта типа текстовый файл fp, обработайте полученный текст и верните корневой объект сообщения. fp должен поддерживать методы readline() и read() для объектов типа файл.

За исключением требования к режиму работы с текстом, этот метод работает так же, как BytesParser.parse().

parsestr(text, headersonly=False)

Аналогично методу parse(), но принимает строковый объект вместо объекта типа файл. Вызов этого метода на строке эквивалентен первому обертыванию текста в экземпляр StringIO и последующему вызову parse().

Необязательный параметр headersonly такой же, как и в методе parse().

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

Точно такой же, как Parser, за исключением того, что headersonly по умолчанию True.

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

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

Возвращает структуру объекта сообщения из объекта типа байты. Это эквивалентно BytesParser().parsebytes(s). Необязательные _class и policy интерпретируются так же, как и в конструкторе класса BytesParser.

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

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

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

Возвращает структуру дерева объекта сообщения из открытого двоичного объекта файла. Это эквивалентно BytesParser().parse(fp). _class и policy интерпретируются так же, как и в конструкторе класса BytesParser.

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

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

email.message_from_string(s, _class=None, *, policy=policy.compat32)

Возвращает структуру объекта сообщения из строки. Это эквивалентно Parser().parsestr(s). _class и policy интерпретируются так же, как и в конструкторе класса Parser.

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

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

Возвращает структуру дерева объекта сообщения из открытого объекта файла. Это эквивалентно Parser().parse(fp). _class и policy интерпретируются так же, как и в конструкторе класса Parser.

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

Изменено в версии 3.6: _class по умолчанию равен политике message_factory.

Вот пример использования message_from_bytes() в интерактивной Python-консоли:

>>> import email
>>> msg = email.message_from_bytes(myBytes)  

19.1.2.3. Дополнительные заметки

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

• Большинство сообщений типа, не являющихся multipart, разбираются как один объект сообщения с строковым содержимым. Эти объекты вернут False для is_multipart(), и iter_parts() вернёт пустой список.
• Все сообщения типа multipart разбираются как контейнерный объект сообщения со списком дочерних объектов сообщения для их содержимого. Внешний контейнерный объект вернёт True для is_multipart(), а iter_parts() вернёт список подчастей.
• Большинство сообщений с типом содержимого message/* (таких как message/delivery-status и message/rfc822) также будут обработаны как контейнерный объект, содержащий список содержимого длиной 1. Их метод is_multipart() вернёт True. Единственный элемент, возвращаемый iter_parts(), будет объектом подсообщения.
• Некоторые сообщения, не соответствующие стандартам, могут быть внутренне несогласованными по своей multipart-структуре. Такие сообщения могут иметь заголовок Content-Type типа multipart, но их метод is_multipart() может вернуть False. Если такие сообщения были обработаны с помощью FeedParser, у них будет экземпляр класса MultipartInvariantViolationDefect в списке атрибута defects. Подробнее см. email.errors.