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

API FeedParser

Модуль email.feedparser импортирует BytesFeedParser, предоставляющий 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 всегда должно быть указано; значение по умолчанию в будущей версии Python изменится на email.policy.default.

New in version 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, в их списке атрибута defects будет экземпляр класса MultipartInvariantViolationDefect. Подробнее см. email.errors.