email.parser: Парсинг email повідомлень

Kod źródłowy: Lib/email/parser.py

Структури об’єктів повідомлень можна створити одним із двох способів: їх можна створити з цілої тканини, створивши об’єкт EmailMessage, додавши заголовки за допомогою інтерфейсу словника та додавши корисне(і) навантаження за допомогою set_content() і пов’язані методи, або їх можна створити шляхом аналізу серіалізованого представлення повідомлення електронної пошти.

Пакет email надає стандартний аналізатор, який розуміє більшість структур документів електронної пошти, включаючи документи MIME. Ви можете передати аналізатору байти, рядок або файловий об’єкт, і аналізатор поверне вам кореневий екземпляр EmailMessage структури об’єкта. Для простих повідомлень без MIME корисним навантаженням цього кореневого об’єкта, ймовірно, буде рядок, що містить текст повідомлення. Для повідомлень MIME кореневий об’єкт поверне True зі свого методу is_multipart(), а доступ до підчастин можна отримати за допомогою методів маніпулювання корисним навантаженням, таких як get_body(), iter_parts() і walk().

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

Занотуйте, що парсер може бути розширений в обмежених напрямках ш, звісно, ви можете реалізувати свій власний парсер повністю з нуля. Вся логіка, що пов’язана з парсером з бібліотеки email та класом EmailMessage втілена у класі Policy, тому кастомний парсер може створювати дерева повідомлень у будь-який необхідний спосіб, через реалізацію кастомних версій методів Policy.

API FeedParser

The BytesFeedParser, imported from the email.feedparser module, provides an API that is conducive to incremental parsing of email messages, such as would be necessary when reading the text of an email message from a source that can block (such as a socket). The BytesFeedParser can of course be used to parse an email message fully contained in a bytes-like object, string, or file, but the BytesParser API may be more convenient for such use cases. The semantics and results of the two parser APIs are identical.

API BytesFeedParser простий; ви створюєте екземпляр, передаєте йому купу байтів, доки більше не залишиться, а потім закриваєте аналізатор, щоб отримати кореневий об’єкт повідомлення. BytesFeedParser є надзвичайно точним під час аналізу повідомлень, що відповідають стандартам, і він дуже добре справляється з аналізом невідповідних повідомлень, надаючи інформацію про те, як повідомлення було визнано зламаним. Він заповнить атрибут defects об’єкта повідомлення списком будь-яких проблем, знайдених у повідомленні. Дивіться модуль email.errors, щоб переглянути список дефектів, які він може знайти.

Ось API для BytesFeedParser:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

Створіть екземпляр BytesFeedParser. Необов’язковий _factory — виклик без аргументів; якщо не вказано, використовуйте message_factory з політики. Викликати _factory щоразу, коли потрібен новий об’єкт повідомлення.

Якщо вказано policy, використовуйте правила, які вона визначає, щоб оновити представлення повідомлення. Якщо policy не налаштовано, використовуйте політику compat32, яка підтримує зворотну сумісність із версією пакета електронної пошти Python 3.2 і надає Message як фабрику за замовчуванням. Усі інші політики передбачають EmailMessage як _factory за умовчанням. Щоб дізнатися більше про те, що ще контролює policy, перегляньте документацію policy.

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

Dodane w wersji 3.2.

Zmienione w wersji 3.3: Додано ключове слово політика.

Zmienione w wersji 3.6: _factory за умовчанням використовує політику message_factory.

feed(data)

Подайте аналізатору ще трохи даних. data має бути bytes-подібний об’єкт, що містить один або більше рядків. Рядки можуть бути частковими, і синтаксичний аналізатор правильно з’єднає такі часткові рядки. Рядки можуть мати будь-яке з трьох загальних закінчень рядків: повернення каретки, новий рядок або повернення каретки та новий рядок (вони навіть можуть бути змішаними).

close()

Завершіть розбір усіх попередньо поданих даних і поверніть кореневий об’єкт повідомлення. Не визначено, що відбувається, якщо feed() викликається після виклику цього методу.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

Works like BytesFeedParser except that the input to the feed() method must be a string. This is of limited utility, since the only way for such a message to be valid is for it to contain only ASCII text or, if utf8 is True, no binary attachments.

Zmienione w wersji 3.3: Додано ключове слово політика.

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.

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

Zmienione w wersji 3.3: Видалено аргумент strict, який був застарілим у версії 2.4. Додано ключове слово політика.

Zmienione w wersji 3.6: _class за умовчанням використовує політику message_factory.

parse(fp, headersonly=False)

Read all the data from the binary file-like object fp, parse the resulting bytes, and return the message object. fp must support both the readline() and the read() methods.

The bytes contained in fp must be formatted as a block of RFC 5322 (or, if utf8 is True, RFC 6532) style headers and header continuation lines, optionally preceded by an envelope header. The header block is terminated either by the end of the data or by a blank line. Following the header block is the body of the message (which may contain MIME-encoded subparts, including subparts with a Content-Transfer-Encoding of 8bit).

Необов’язковий параметр headersonly — це позначка, яка вказує, чи зупиняти аналіз після читання заголовків. Типовим значенням є False, що означає, що аналізується весь вміст файлу.

parsebytes(bytes, headersonly=False)

Подібний до методу parse(), за винятком того, що він приймає bytes-подібний об’єкт замість файлоподібного об’єкта. Виклик цього методу для bytes-подібний об’єкт еквівалентний обгортанню bytes в екземплярі BytesIO і виклику parse().

Необов’язковий headersonly такий же, як у випадку з методом parse().

Dodane w wersji 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Точно так само, як BytesParser, за винятком того, що headersonly за умовчанням має значення True.

Dodane w wersji 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

Цей клас є паралельним до BytesParser, але обробляє введення рядків.

Zmienione w wersji 3.3: Видалено суворий аргумент. Додано ключове слово політика.

Zmienione w wersji 3.6: _class за умовчанням використовує політику message_factory.

parse(fp, headersonly=False)

Прочитати всі дані з файлоподібного об’єкта текстового режиму fp, проаналізувати отриманий текст і повернути кореневий об’єкт повідомлення. fp має підтримувати як методи readline(), так і read() для файлоподібних об’єктів.

За винятком вимог текстового режиму, цей метод працює як BytesParser.parse().

parsestr(text, headersonly=False)

Подібний до методу parse(), за винятком того, що він приймає рядковий об’єкт замість файлоподібного об’єкта. Виклик цього методу для рядка еквівалентний обгортанню тексту в екземплярі 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.

Dodane w wersji 3.2.

Zmienione w wersji 3.3: Видалено суворий аргумент. Додано ключове слово політика.

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

Повертає дерево структури об’єкта повідомлення з відкритого двійкового файлу file object. Це еквівалентно BytesParser().parse(fp). _class і policy інтерпретуються як конструктор класу BytesParser.

Dodane w wersji 3.2.

Zmienione w wersji 3.3: Видалено суворий аргумент. Додано ключове слово політика.

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

Повертає структуру об’єкта повідомлення з рядка. Це еквівалентно Parser().parsestr(s). _class і policy інтерпретуються як конструктор класу Parser.

Zmienione w wersji 3.3: Видалено суворий аргумент. Додано ключове слово політика.

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

Повертає дерево структури об’єкта повідомлення з відкритого file object. Це еквівалентно Parser().parse(fp). _class і policy інтерпретуються як конструктор класу Parser.

Zmienione w wersji 3.3: Видалено суворий аргумент. Додано ключове слово політика.

Zmienione w wersji 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-edness. Такі повідомлення можуть мати заголовок Content-Type типу multipart, але їхній метод is_multipart() може повертати значення False. Якщо такі повідомлення були проаналізовані за допомогою FeedParser, вони матимуть екземпляр класу MultipartInvariantViolationDefect у своєму списку атрибутів defects. Перегляньте email.errors для деталей.