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

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

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

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

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

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

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

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

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

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

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

close(): Завершает разбор всех ранее переданных данных и возвращает корневой объект сообщения. Поведение вызова feed() после вызова этого метода не определено.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32): Работает как BytesFeedParser, за исключением того, что входные данные для метода feed() должны быть строкой. Этот класс имеет ограниченное применение, поскольку сообщение может быть допустимым только в том случае, если оно содержит исключительно текст ASCII или, если utf8 равно True, не содержит двоичных вложений.

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

API Parser

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

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

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

Изменено в версии 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, а не файловый объект. Вызов этого метода для объекта, подобного bytes, эквивалентен предварительной упаковке 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): Возвращает структуру объекта сообщения из объекта, подобного bytes. Эквивалентно 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, разбираются как единый объект сообщения со строковой полезной нагрузкой. Для этих объектов метод is_multipart() возвращает False, а 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.