email.parser.md

1> **Источник:** https://python-all.ru/3.10/library/email.parser.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email.parser`](https://python-all.ru/3.10/library/email.parser.html#module-email.parser): Разбор сообщений электронной почты89**Исходный код:** [Lib/email/parser.py](https://python-all.ru/src/3.10/Lib/email/parser.py)1011---1213Структуры объектов сообщений можно создать одним из двух способов: их можно создать с нуля, создав объект [`EmailMessage`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage), добавляя заголовки через интерфейс словаря и добавляя содержимое (payload) с помощью [`set_content()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.set_content) и связанных методов, или их можно создать путём разбора сериализованного представления сообщения электронной почты.1415Пакет [`email`](https://python-all.ru/3.10/library/email.html#module-email) предоставляет стандартный анализатор, который понимает большинство структур документов электронной почты, включая MIME-документы. Можно передать анализатору объект bytes, строку или файл, и анализатор вернёт корневой экземпляр [`EmailMessage`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage) структуры объекта. Для простых, не-MIME сообщений содержимое (payload) этого корневого объекта, скорее всего, будет строкой, содержащей текст сообщения. Для MIME-сообщений корневой объект вернёт `True` из своего метода [`is_multipart()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.is_multipart), а к подчастям можно получить доступ через методы манипуляции содержимым, такие как [`get_body()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.get_body), [`iter_parts()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.iter_parts) и [`walk()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.walk).1617На самом деле доступны два интерфейса анализатора: [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser) API и инкрементальный [`FeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.FeedParser) API. [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser) API наиболее полезен, если всё сообщение находится в памяти или если всё сообщение хранится в файле в файловой системе. [`FeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.FeedParser) больше подходит, когда сообщение читается из потока, который может заблокироваться в ожидании новых данных (например, чтение сообщения электронной почты из сокета). [`FeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.FeedParser) может потреблять и анализировать сообщение инкрементально и возвращает корневой объект только после закрытия анализатора.1819Обратите внимание, что анализатор можно расширить ограниченными способами, и, конечно, можно реализовать собственный анализатор полностью с нуля. Вся логика, связывающая встроенный анализатор пакета [`email`](https://python-all.ru/3.10/library/email.html#module-email) и класс [`EmailMessage`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage), воплощена в классе `policy`, поэтому пользовательский анализатор может создавать деревья объектов сообщений любым необходимым способом, реализуя пользовательские версии соответствующих методов `policy`.2021## API FeedParser2223[`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser), импортированный из модуля `email.feedparser`, предоставляет API, подходящий для инкрементального разбора сообщений электронной почты, например, когда необходимо читать текст сообщения из источника, который может блокироваться (например, сокет). [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser), конечно, можно использовать для разбора сообщения, полностью содержащегося в [байтоподобном объекте](https://python-all.ru/3.10/glossary.html#term-bytes-like-object), строке или файле, но API [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser) может быть удобнее для таких случаев. Семантика и результаты двух API анализаторов идентичны.2425API [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser) прост: создаётся экземпляр, в него подаётся набор байтов, пока больше нечего подавать, затем анализатор закрывается, чтобы получить корневой объект сообщения. [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser) чрезвычайно точен при разборе сообщений, соответствующих стандартам, и очень хорошо справляется с разбором несоответствующих сообщений, предоставляя информацию о том, почему сообщение было признано некорректным. Он заполняет атрибут [`defects`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.defects) объекта сообщения списком любых проблем, найденных в сообщении. Смотрите модуль [`email.errors`](https://python-all.ru/3.10/library/email.errors.html#module-email.errors) для получения списка дефектов, которые он может найти.2627Вот API для [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser):2829#### `class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)`3031Создаёт экземпляр [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser). Необязательный параметр *\_factory* – это вызываемый объект без аргументов; если не указан, используется [`message_factory`](https://python-all.ru/3.10/library/email.policy.html#email.policy.Policy.message_factory) из *policy*. Вызов *\_factory* производится каждый раз, когда требуется новый объект сообщения.3233Если указан *policy*, используются заданные им правила для обновления представления сообщения. Если *policy* не задан, используется политика [`compat32`](https://python-all.ru/3.10/library/email.policy.html#email.policy.Compat32), которая обеспечивает обратную совместимость с версией Python 3.2 пакета email и предоставляет [`Message`](https://python-all.ru/3.10/library/email.compat32-message.html#email.message.Message) в качестве фабрики по умолчанию. Все остальные политики предоставляют [`EmailMessage`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage) в качестве *\_factory* по умолчанию. Дополнительную информацию о том, что ещё контролирует *policy*, см. в документации [`policy`](https://python-all.ru/3.10/library/email.policy.html#module-email.policy).3435Примечание: **Параметр policy всегда следует указывать**; значение по умолчанию изменится на [`email.policy.default`](https://python-all.ru/3.10/library/email.policy.html#email.policy.default) в будущей версии Python.3637Новое в версии 3.2.3839Изменено в версии 3.3: Добавлен параметр *policy*.4041Изменено в версии 3.6: *\_factory* по умолчанию равен политике `message_factory`.4243#### `feed(data)`4445Подайте анализатору ещё данные. *data* должен быть [байтоподобным объектом](https://python-all.ru/3.10/glossary.html#term-bytes-like-object), содержащим одну или несколько строк. Строки могут быть неполными, и анализатор правильно склеит такие неполные строки вместе. Строки могут иметь любой из трёх распространённых окончаний строк: возврат каретки, перевод строки или возврат каретки и перевод строки (они даже могут быть смешаны).4647#### `close()`4849Завершает разбор всех ранее переданных данных и возвращает корневой объект сообщения. Не определено, что произойдёт, если [`feed()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser.feed) будет вызван после вызова этого метода.5051#### `class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)`5253Работает как [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser), за исключением того, что входные данные для метода [`feed()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser.feed) должны быть строкой. Это имеет ограниченную полезность, поскольку единственный способ сделать такое сообщение допустимым – чтобы оно содержало только текст ASCII или, если `utf8` равно `True`, не содержало двоичных вложений.5455Изменено в версии 3.3: Добавлен параметр *policy*.5657## API Parser5859Класс [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser), импортированный из модуля [`email.parser`](https://python-all.ru/3.10/library/email.parser.html#module-email.parser), предоставляет API, который можно использовать для разбора сообщения, когда полное содержимое сообщения доступно в виде [байтоподобного объекта](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) или файла. Модуль [`email.parser`](https://python-all.ru/3.10/library/email.parser.html#module-email.parser) также предоставляет [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser) для разбора строк, а также анализаторы только заголовков, [`BytesHeaderParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesHeaderParser) и [`HeaderParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.HeaderParser), которые можно использовать, если интересуют только заголовки сообщения. [`BytesHeaderParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesHeaderParser) и [`HeaderParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.HeaderParser) могут быть значительно быстрее в таких ситуациях, поскольку они не пытаются разобрать тело сообщения, а вместо этого устанавливают содержимое (payload) как сырое тело.6061#### `class email.parser.BytesParser(_class=None, *, policy=policy.compat32)`6263Создаёт экземпляр [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser). Аргументы *\_class* и *policy* имеют тот же смысл и семантику, что и аргументы *\_factory* и *policy* в [`BytesFeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesFeedParser).6465Примечание: **Параметр policy всегда следует указывать**; значение по умолчанию изменится на [`email.policy.default`](https://python-all.ru/3.10/library/email.policy.html#email.policy.default) в будущей версии Python.6667Изменено в версии 3.3: Удалён аргумент *strict*, устаревший в версии 2.4. Добавлен параметр *policy*.6869Изменено в версии 3.6: *\_class* по умолчанию использует политику `message_factory`.7071#### `parse(fp, headersonly=False)`7273Читает все данные из двоичного файлоподобного объекта *fp*, разбирает полученные байты и возвращает объект сообщения. *fp* должен поддерживать оба метода: [`readline()`](https://python-all.ru/3.10/library/io.html#io.IOBase.readline) и `read()`.7475Байты, содержащиеся в *fp*, должны быть отформатированы как блок [**RFC 5322**](https://python-all.ru/3.10/library/email.parser.html) (или, если `utf8` равно `True`, [**RFC 6532**](https://python-all.ru/3.10/library/email.parser.html)) заголовков и строк продолжения заголовков, возможно, с предшествующим конвертным заголовком. Блок заголовков завершается либо концом данных, либо пустой строкой. После блока заголовков следует тело сообщения (которое может содержать MIME-кодированные подчасти, включая подчасти с *Content-Transfer-Encoding* равным `8bit`).7677Необязательный параметр *headersonly* – флаг, указывающий, следует ли остановить разбор после чтения заголовков. По умолчанию `False`, то есть разбирается всё содержимое файла.7879#### `parsebytes(bytes, headersonly=False)`8081Аналогичен методу [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser.parse), но принимает [байтоподобный объект](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) вместо файлоподобного. Вызов этого метода для [байтоподобного объекта](https://python-all.ru/3.10/glossary.html#term-bytes-like-object) эквивалентен обёртыванию *bytes* в экземпляр [`BytesIO`](https://python-all.ru/3.10/library/io.html#io.BytesIO) с последующим вызовом [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser.parse).8283Необязательный параметр *headersonly* действует так же, как в методе [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser.parse).8485Новое в версии 3.2.8687#### `class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)`8889Точно как [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser), за исключением того, что *headersonly* по умолчанию равен `True`.9091Новое в версии 3.3.9293#### `class email.parser.Parser(_class=None, *, policy=policy.compat32)`9495Этот класс аналогичен [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser), но работает с строковыми входными данными.9697Изменено в версии 3.3: Удалён аргумент *strict*. Добавлен ключевой аргумент *policy*.9899Изменено в версии 3.6: *\_class* по умолчанию использует политику `message_factory`.100101#### `parse(fp, headersonly=False)`102103Читает все данные из файлоподобного объекта в текстовом режиме *fp*, разбирает полученный текст и возвращает корневой объект сообщения. *fp* должен поддерживать как метод [`readline()`](https://python-all.ru/3.10/library/io.html#io.TextIOBase.readline), так и метод [`read()`](https://python-all.ru/3.10/library/io.html#io.TextIOBase.read) для файлоподобных объектов.104105За исключением требования текстового режима, этот метод работает как [`BytesParser.parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser.parse).106107#### `parsestr(text, headersonly=False)`108109Аналогичен методу [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser.parse), но принимает строковый объект вместо файлоподобного. Вызов этого метода для строки eквивалентен предварительной обёртке *text* в экземпляр [`StringIO`](https://python-all.ru/3.10/library/io.html#io.StringIO) и вызову [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser.parse).110111Необязательный параметр *headersonly* действует так же, как в методе [`parse()`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser.parse).112113#### `class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)`114115Точно как [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser), за исключением того, что *headersonly* по умолчанию равен `True`.116117Поскольку создание структуры объекта сообщения из строки или файлового объекта является распространённой задачей, для удобства предоставляются четыре функции. Они доступны в пространстве имён пакета верхнего уровня [`email`](https://python-all.ru/3.10/library/email.html#module-email).118119#### `email.message_from_bytes(s, _class=None, *, policy=policy.compat32)`120121Return a message object structure from a [bytes-like object](https://python-all.ru/3.10/glossary.html#term-bytes-like-object). This is equivalent to `BytesParser().parsebytes(s)`. Optional *\_class* and *policy* are interpreted as with the [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser) class constructor.122123Новое в версии 3.2.124125Изменено в версии 3.3: Удалён аргумент *strict*. Добавлен ключевой аргумент *policy*.126127#### `email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)`128129Return a message object structure tree from an open binary [file object](https://python-all.ru/3.10/glossary.html#term-file-object). This is equivalent to `BytesParser().parse(fp)`. *\_class* and *policy* are interpreted as with the [`BytesParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.BytesParser) class constructor.130131Новое в версии 3.2.132133Изменено в версии 3.3: Удалён аргумент *strict*. Добавлен ключевой аргумент *policy*.134135#### `email.message_from_string(s, _class=None, *, policy=policy.compat32)`136137Возвращает структуру объекта сообщения из строки. Это эквивалентно `Parser().parsestr(s)`. Параметры *\_class* и *policy* интерпретируются как в конструкторе класса [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser).138139Изменено в версии 3.3: Удалён аргумент *strict*. Добавлен ключевой аргумент *policy*.140141#### `email.message_from_file(fp, _class=None, *, policy=policy.compat32)`142143Return a message object structure tree from an open [file object](https://python-all.ru/3.10/glossary.html#term-file-object). This is equivalent to `Parser().parse(fp)`. *\_class* and *policy* are interpreted as with the [`Parser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.Parser) class constructor.144145Изменено в версии 3.3: Удалён аргумент *strict*. Добавлен ключевой аргумент *policy*.146147Изменено в версии 3.6: *\_class* по умолчанию использует политику `message_factory`.148149Вот пример использования [`message_from_bytes()`](https://python-all.ru/3.10/library/email.parser.html#email.message_from_bytes) в интерактивной подсказке Python:150151```python152>>> import email153>>> msg = email.message_from_bytes(myBytes)  154```155156## Дополнительные примечания157158Вот некоторые замечания по семантике разбора:159160- Большинство сообщений, не являющихся *multipart*, разбираются как одиночный объект сообщения с строковой полезной нагрузкой. Такие объекты возвращают `False` для [`is_multipart()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.is_multipart), а [`iter_parts()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.iter_parts) возвращает пустой список.161- Все сообщения типа *multipart* разбираются как контейнерное сообщение с полезной нагрузкой в виде списка объектов-подсообщений. Внешнее контейнерное сообщение возвращает `True` для [`is_multipart()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.is_multipart), а [`iter_parts()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.iter_parts) возвращает список подчастей.162- Большинство сообщений с типом содержимого *message/\** (такие как *message/delivery-status* и *message/rfc822*) также разбираются как контейнерный объект, содержащий полезную нагрузку в виде списка из одного элемента. Их метод [`is_multipart()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.is_multipart) возвращает `True`. Единственный элемент, возвращаемый [`iter_parts()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.iter_parts), будет объектом-подсообщением.163- Некоторые сообщения, не соответствующие стандартам, могут быть внутренне непоследовательны в отношении своей *multipart*-ности. Такие сообщения могут иметь заголовок *Content-Type* типа *multipart*, но их метод [`is_multipart()`](https://python-all.ru/3.10/library/email.message.html#email.message.EmailMessage.is_multipart) может возвращать `False`. Если такие сообщения были разобраны с помощью [`FeedParser`](https://python-all.ru/3.10/library/email.parser.html#email.parser.FeedParser), они будут содержать экземпляр класса `MultipartInvariantViolationDefect` в своем списке атрибутов *defects*. Подробнее см. [`email.errors`](https://python-all.ru/3.10/library/email.errors.html#module-email.errors).164