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

API FeedParser

Класс BytesFeedParser, импортированный из модуля email.feedparser, предоставляет API, подходящий для поэтапного разбора сообщений электронной почты, что необходимо при чтении текста сообщения электронной почты из источника, который может блокироваться (например, из сокета). Класс BytesFeedParser, конечно, может использоваться для разбора сообщения электронной почты, полностью содержащегося в объекте типа байты, строке или файле, но 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.

Новое в версии 3.2.

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

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

feed(data)

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

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.