Содержание страницы

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

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

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

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

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

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

API FeedParser¶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 пакета email и предоставляет 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 Parser¶Parser API

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

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 в экземпляр 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(), но принимает строковый объект вместо файлоподобного. Вызов этого метода для строки eквивалентен предварительной обёртке 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)¶: Return a message object structure from a bytes-like object. This is equivalent to BytesParser().parsebytes(s). Optional _class and policy are interpreted as with the BytesParser class constructor.

Новое в версии 3.2.

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

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)¶: Return a message object structure tree from an open binary file object. This is equivalent to BytesParser().parse(fp). _class and policy are interpreted as with the BytesParser class constructor.

Новое в версии 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)¶: Return a message object structure tree from an open file object. This is equivalent to Parser().parse(fp). _class and policy are interpreted as with the Parser class constructor.

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

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

Вот пример использования message_from_bytes() в интерактивной подсказке Python:

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

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

Вот некоторые замечания по семантике разбора:

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