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