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

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

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

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

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

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

FeedParser API

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, которая поддерживает обратную совместимость с версией Python 3.2 пакета электронной почты и предоставляет параметр Message в качестве фабрики по умолчанию. Все остальные политики предоставляют EmailMessage в качестве _factory по умолчанию. Дополнительные сведения о других элементах управления policy см. в документации по policy.

Примечание: Ключевое слово политики всегда должно быть указано; значение по умолчанию изменится на email.policy.default в будущей версии Python.

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

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

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

feed(data)

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

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.

Примечание: Ключевое слово политики всегда должно быть указано; значение по умолчанию изменится на 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 defaults to the policy message_factory.

parse(fp, headersonly=False)

Прочитайте все данные из текстового режима подобный файлу объект fp, разберите получающийся текст и объект сообщения корня возвращает the. fp должны поддерживать методы readline() и read() для файловых объектов.

Кроме требования текстового режима, этот метод работает как BytesParser.parse().

parsestr(text, headersonly=False)

Аналогично методу parse(), за исключением того, что он принимает объект строка вместо объекта, похожего на файл. Вызов этого метода в строка эквивалентен переносу text в StringIO сущность first и вызову 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)

Сообщение возвращает a возражает дереву структуры от открытого двоичного файлового объекта. Это эквивалентно BytesParser().parse(fp). _class и policy интерпретируются как с конструктором класса BytesParser.

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

Изменено в версии 3.3: Удален аргумент strict. Добавлен policy ключевой.

email.message_from_string(s, _class=None, *, policy=policy.compat32)

Возвращает a структуры объекта сообщения из строка. Это эквивалентно Parser().parsestr(s). _class и policy интерпретируются как с конструктором класса Parser.

Изменено в версии 3.3: Удален аргумент strict. Добавлен policy ключевой.

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

Сообщение возвращает a возражает дереву структуры от открытого файлового объекта. Это эквивалентно Parser().parse(fp). _class и policy интерпретируются как с конструктором класса Parser.

Изменено в версии 3.3: Удален аргумент strict. Добавлен policy ключевой.

Изменено в версии 3.6: _class defaults to the policy message_factory.

Вот пример того, как вы могли бы использовать message_from_bytes() в интерактивном незамедлительном Python:

>>> import email
>>> msg = email.message_from_bytes(myBytes)

Дополнительные примечания

Вот несколько заметок о семантике парсинг:

  • Большинство сообщений неmultipart типа анализируются как один объект сообщения с полезной нагрузкой строка. Эти объекты будут возвращает False для is_multipart(), и iter_parts() будет yield пустой список.
  • Все сообщения типа multipart будут проанализированы как объект контейнерного сообщения со списком объектов вложенных сообщений для их полезной нагрузки. Сообщение внешнего контейнера будет возвращает True для is_multipart(), и iter_parts() будет yield список подразделов.
  • Большинство сообщений с типом содержимого message/* (например, message/delivery-status и message/rfc822) также будут проанализированы как объект контейнера, содержащий полезную нагрузку списка длиной 1. Их метод is_multipart() будет возвращает True. Одиночный элемент, выдаваемый iter_parts(), будет объектом вложенного сообщения.
  • Некоторые сообщения, не совместимые со стандартами, могут быть внутренне несовместимыми с их multipart. Такие сообщения могут иметь заголовок Content-Type типа multipart, но их метод is_multipart() может быть возвращает False. Если такие сообщения были проанализированы с помощью FeedParser, они будут иметь сущность класса MultipartInvariantViolationDefect в своем списке defects атрибут. Дополнительные сведения см. в разделе email.errors.