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 (их можно даже смешивать).
-
-
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 и policyBytesFeedParser
.Примечание: Ключевое слово политики всегда должно быть указано; значение по умолчанию изменится на
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-Encoding8bit
).Необязательный 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()
.
-
-
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
.