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