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

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 в качестве фабрики по умолчанию. Все остальные политики предоставляют 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.

API парсера

Класс 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(), но вместо объекта типа файл принимает объект типа байты. Вызов этого метода на объекте типа байты эквивалентен обертыванию bytes в экземпляр 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(), но вместо объекта типа файл принимает строковый объект. Вызов этого метода на строке эквивалентен обертыванию text в экземпляр 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)  

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

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

• Большинство сообщений типа, не являющихся 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.