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

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