email.policy.md

1> **Источник:** https://python-all.ru/3.3/library/email.policy.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 19.1.4. [`email.policy`](https://python-all.ru/3.3/library/email.policy.html#module-email.policy): объекты Policy89Новое в версии 3.3.1011Пакет [`email`](https://python-all.ru/3.3/library/email.html#module-email) в первую очередь предназначен для обработки сообщений электронной почты в соответствии с различными RFC, описывающими формат email и MIME. Однако общий формат email-сообщений – блок заголовков, каждый из которых состоит из имени и следующего за ним двоеточия и значения, затем пустая строка и произвольное «тело» – нашёл применение и за пределами электронной почты. Некоторые из этих применений достаточно строго следуют основным RFC, другие – нет. И даже при работе с электронной почтой иногда возникает необходимость отойти от строгого соблюдения RFC.1213Объекты Policy обеспечивают пакету email гибкость для обработки всех этих разнородных сценариев использования.1415Объект [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) инкапсулирует набор атрибутов и методов, управляющих поведением различных компонентов пакета email во время использования. Экземпляры [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) можно передавать различным классам и методам пакета email, чтобы изменить поведение по умолчанию. Устанавливаемые значения и их значения по умолчанию описаны ниже.1617Все классы пакета email используют политику по умолчанию. Эта политика называется [`Compat32`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Compat32) с соответствующим предопределённым экземпляром `compat32`. Она обеспечивает полную обратную совместимость (в некоторых случаях включая совместимость с ошибками) с версией пакета email, предшествующей Python 3.3.1819Первая часть этой документации описывает возможности [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) – [*абстрактного базового класса*](https://python-all.ru/3.3/glossary.html#term-abstract-base-class), определяющего общие для всех объектов политики возможности, включая `compat32`. Сюда входят некоторые методы-хуки, внутренне вызываемые пакетом email; пользовательская политика может переопределить их для получения иного поведения.2021При создании объекта [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) он получает политику. По умолчанию это будет `compat32`, но можно указать другую политику. Если `Message` создаётся [`парсером`](https://python-all.ru/3.3/library/email.parser.html#module-email.parser), то переданная парсеру политика станет политикой создаваемого им `Message`. Если `Message` создаётся программой, то политику можно указать при его создании. Когда `Message` передаётся [`генератору`](https://python-all.ru/3.3/library/email.generator.html#module-email.generator), генератор по умолчанию использует политику из `Message`, но можно также передать генератору конкретную политику, которая переопределит сохранённую в объекте `Message`.2223Экземпляры [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) неизменяемы, но их можно клонировать, принимающие те же именованные аргументы, что и конструктор класса, и возвращающие новый экземпляр [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy), который является копией исходного, но с изменёнными значениями указанных атрибутов.2425Например, следующий код можно использовать для чтения электронного письма из файла на диске и передачи его системной программе `sendmail` в Unix-системе:2627```python28>>> from email import message_from_binary_file29>>> from email.generator import BytesGenerator30>>> from email import policy31>>> from subprocess import Popen, PIPE32>>> with open('mymsg.txt', 'rb') as f:33...     msg = message_from_binary_file(f, policy=policy.default)34>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)35>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))36>>> g.flatten(msg)37>>> p.stdin.close()38>>> rc = p.wait()39```4041Здесь мы указываем [`BytesGenerator`](https://python-all.ru/3.3/library/email.generator.html#email.generator.BytesGenerator) использовать правильные разделители строк согласно RFC при создании двоичной строки для передачи в `stdin` программы `sendmail`, тогда как политика по умолчанию использовала бы разделители строк `\n`.4243Объекты Policy также можно комбинировать с помощью оператора сложения, получая объект политики, настройки которого представляют собой комбинацию нестандартных значений суммируемых объектов:4445```python46>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')47>>> compat_strict = policy.compat32.clone(raise_on_defect=True)48>>> compat_strict_SMTP = compat_SMTP + compat_strict49```5051Эта операция не является коммутативной; то есть порядок добавления объектов имеет значение. Для иллюстрации:5253```python54>>> policy100 = policy.compat32.clone(max_line_length=100)55>>> policy80 = policy.compat32.clone(max_line_length=80)56>>> apolicy = policy100 + policy8057>>> apolicy.max_line_length588059>>> apolicy = policy80 + policy10060>>> apolicy.max_line_length6110062```6364#### `class email.policy.Policy(**kw)`6566Это [*абстрактный базовый класс*](https://python-all.ru/3.3/glossary.html#term-abstract-base-class) для всех классов политик. Он предоставляет реализации по умолчанию для пары тривиальных методов, а также реализацию свойства неизменяемости, метода [`clone()`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.clone) и семантику конструктора.6768Конструктору класса политики можно передавать различные ключевые аргументы. Аргументы, которые могут быть указаны, – это любые свойства, не являющиеся методами, этого класса, плюс любые дополнительные свойства, не являющиеся методами, конкретного класса. Значение, указанное в конструкторе, переопределит значение по умолчанию для соответствующего атрибута.6970Этот класс определяет следующие свойства, и, соответственно, значения для следующих могут быть переданы в конструктор любого класса политики:7172#### `max_line_length`7374Максимальная длина любой строки в сериализованном выводе, не считая символов конца строки. По умолчанию 78, согласно [**RFC 5322**](https://python-all.ru/3.3/library/email.policy.html). Значение `0` или [`None`](https://python-all.ru/3.3/library/constants.html#None) означает, что перенос строк вообще не должен выполняться.7576#### `linesep`7778Строка, используемая для завершения строк в сериализованном выводе. По умолчанию `\n`, поскольку это внутреннее правило завершения строк, используемое Python, хотя `\r\n` требуется RFC.7980#### `cte_type`8182Управляет типом кодирования передачи содержимого, которое может или должно использоваться. Возможные значения:8384| `7bit` | все данные должны быть «7-битно чистыми» (только ASCII). Это означает, что при необходимости данные будут закодированы с использованием quoted-printable или base64-кодировки. |85| --- | --- |86| `8bit` | Данные не обязаны быть чистыми 7-битными. Данные в заголовках по-прежнему должны содержать только ASCII и поэтому будут кодироваться (см. исключение «binary\_fold» ниже), но части тела могут использовать CTE `8bit`. |8788Значение `cte_type` равное `8bit` работает только с `BytesGenerator`, а не с `Generator`, поскольку строки не могут содержать двоичные данные. Если `Generator` работает в рамках политики, указывающей `cte_type=8bit`, он будет вести себя так, как если бы `cte_type` было `7bit`.8990#### `raise_on_defect`9192Если [`True`](https://python-all.ru/3.3/library/constants.html#True), любые обнаруженные дефекты будут вызываться как ошибки. Если [`False`](https://python-all.ru/3.3/library/constants.html#False) (по умолчанию), дефекты передаются методу [`register_defect()`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.register_defect).9394Следующий метод [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) предназначен для вызова кодом, использующим библиотеку email, для создания экземпляров политик с произвольными настройками:9596#### `clone(**kw)`9798Возвращает новый экземпляр [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy), атрибуты которого имеют те же значения, что и у текущего экземпляра, за исключением тех атрибутов, которым присвоены новые значения через именованные аргументы.99100Остальные методы [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) вызываются кодом пакета email и не предназначены для вызова приложением, использующим этот пакет. Пользовательская политика должна реализовывать все эти методы.101102#### `handle_defect(obj, defect)`103104Обрабатывает *дефект*, обнаруженный на *obj*. Когда пакет email вызывает этот метод, *defect* всегда будет подклассом `Defect`.105106Реализация по умолчанию проверяет флаг [`raise_on_defect`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.raise_on_defect). Если он равен `True`, *defect* возбуждается как исключение. Если он равен `False` (по умолчанию), *obj* и *defect* передаются [`register_defect()`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.register_defect).107108#### `register_defect(obj, defect)`109110Регистрирует *дефект* на *obj*. В пакете email *дефект* всегда является подклассом `Defect`.111112Реализация по умолчанию вызывает метод `append` атрибута `defects` объекта *obj*. Когда пакет email вызывает [`handle_defect`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.handle_defect), *obj* обычно имеет атрибут `defects` с методом `append` method. Пользовательские типы объектов, используемые с пакетом email (например, пользовательские объекты `Message`), также должны предоставлять такой атрибут, иначе дефекты в разобранных сообщениях вызовут неожиданные ошибки.113114#### `header_max_count(name)`115116Возвращает максимально допустимое количество заголовков с именем *name*.117118Вызывается, когда заголовок добавляется к [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) объекту. Если возвращаемое значение не равно `0` или `None`, и уже имеется количество заголовков с именем *name*, равное возвращённому значению, возбуждается [`ValueError`](https://python-all.ru/3.3/library/exceptions.html#ValueError).119120Поскольку поведение по умолчанию `Message.__setitem__` заключается в добавлении значения к списку заголовков, можно случайно создать дублирующиеся заголовки, не осознавая этого. Этот метод позволяет программно ограничить количество экземпляров некоторых заголовков, которые могут быть добавлены в `Message`. (Парсер это ограничение не соблюдает; он добросовестно создаст столько заголовков, сколько есть в разбираемом сообщении.)121122Реализация по умолчанию возвращает `None` для всех имён заголовков.123124#### `header_source_parse(sourcelines)`125126Пакет email вызывает этот метод со списком строк, каждая строка заканчивается символами разделителя строк, найденными в разбираемом исходном тексте. Первая строка включает имя поля заголовка и разделитель. Все пробельные символы в исходнике сохраняются. Метод должен вернуть кортеж `(name, value)`, который будет сохранён в `Message` для представления разобранного заголовка.127128Если реализация хочет сохранить совместимость с существующими политиками пакета email, *name* должен быть именем с сохранённым регистром (все символы до разделителя ‘`:`‘), а *value* должно быть развёрнутым значением (все символы разделителя строк удалены, но пробельные символы сохранены), с удалёнными ведущими пробелами.129130*sourcelines* может содержать двоичные данные, экранированные суррогатами.131132Реализация по умолчанию отсутствует133134#### `header_store_parse(name, value)`135136Пакет email вызывает этот метод с именем и значением, предоставленными прикладной программой, когда она программно изменяет объект `Message` (в отличие от `Message`, созданного парсером). Метод должен вернуть кортеж `(name, value)`, который будет сохранён в `Message` для представления заголовка.137138Если реализация хочет сохранить совместимость с существующими политиками пакета email, *name* и *value* должны быть строками или подклассами строк, которые не изменяют содержимое переданных аргументов.139140Реализация по умолчанию отсутствует141142#### `header_fetch_parse(name, value)`143144Пакет email вызывает этот метод с *name* и *value*, в данный момент сохранёнными в `Message`, когда прикладная программа запрашивает этот заголовок; что бы метод ни вернул, это и передаётся прикладной программе в качестве значения запрашиваемого заголовка. Обратите внимание, что в `Message` может храниться более одного заголовка с одним и тем же именем; методу передаются конкретные имя и значение заголовка, который должен быть возвращён приложению.145146*value* может содержать бинарные данные с суррогатным экранированием. В возвращаемом методом значении не должно быть таких бинарных данных.147148Реализация по умолчанию отсутствует149150#### `fold(name, value)`151152Пакет email вызывает этот метод с *name* и *value*, в данный момент сохранёнными в `Message` для данного заголовка. Метод должен вернуть строку, представляющую этот заголовок, правильно «свёрнутым» (в соответствии с настройками политики), объединяя *name* с *value* и вставляя символы [`linesep`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.linesep) в соответствующих местах. См. [**RFC 5322**](https://python-all.ru/3.3/library/email.policy.html) для обсуждения правил сворачивания заголовков email.153154*value* может содержать бинарные данные с суррогатным экранированием. В возвращаемой методом строке не должно быть таких бинарных данных.155156#### `fold_binary(name, value)`157158То же, что и [`fold()`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.fold), за исключением того, что возвращаемое значение должно быть объектом bytes, а не строкой.159160*value* может содержать бинарные данные с суррогатным экранированием. Они могут быть преобразованы обратно в бинарные данные в возвращаемом байтовом объекте.161162#### `class email.policy.Compat32(**kw)`163164Этот конкретный [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) является политикой обратной совместимости. Он воспроизводит поведение пакета email в Python 3.2. Модуль [`policy`](https://python-all.ru/3.3/library/email.policy.html#module-email.policy) также определяет экземпляр этого класса, `compat32`, который используется в качестве политики по умолчанию. Таким образом, поведение пакета email по умолчанию заключается в сохранении совместимости с Python 3.2.165166Класс предоставляет следующие конкретные реализации абстрактных методов [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy):167168#### `header_source_parse(sourcelines)`169170Имя разбирается как всё до символа ‘`:`‘ и возвращается без изменений. Значение определяется путём удаления ведущих пробелов из оставшейся части первой строки, объединения всех последующих строк вместе и удаления всех завершающих символов возврата каретки или перевода строки.171172#### `header_store_parse(name, value)`173174Имя и значение возвращаются без изменений.175176#### `header_fetch_parse(name, value)`177178Если значение содержит двоичные данные, оно преобразуется в объект [`Header`](https://python-all.ru/3.3/library/email.header.html#email.header.Header) с использованием charset `unknown-8bit`. В противном случае оно возвращается без изменений.179180#### `fold(name, value)`181182Заголовки сворачиваются с использованием алгоритма сворачивания [`Header`](https://python-all.ru/3.3/library/email.header.html#email.header.Header), который сохраняет существующие разрывы строк в значении и оборачивает каждую результирующую строку до `max_line_length`. Не-ASCII двоичные данные кодируются CTE с использованием charset `unknown-8bit`.183184#### `fold_binary(name, value)`185186Заголовки сворачиваются с использованием алгоритма сворачивания [`Header`](https://python-all.ru/3.3/library/email.header.html#email.header.Header), который сохраняет существующие разрывы строк в значении и оборачивает каждую результирующую строку до `max_line_length`. Если `cte_type` равен `7bit`, не-ASCII двоичные данные кодируются CTE с использованием charset `unknown-8bit`. В противном случае используется исходный заголовок, с его существующими разрывами строк и любыми (не соответствующими RFC) двоичными данными, которые он может содержать.187188> **Примечание**189>190> The documentation below describes new policies that are included in the standard library on a [*provisional basis*](https://python-all.ru/3.3/glossary.html#term-provisional-package). Backwards incompatible changes (up to and including removal of the feature) may occur if deemed necessary by the core developers.191192#### `class email.policy.EmailPolicy(**kw)`193194Этот конкретный [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy) обеспечивает поведение, предназначенное для полного соответствия текущим RFC email. К ним относятся (но не ограничиваясь) [**RFC 5322**](https://python-all.ru/3.3/library/email.policy.html), [**RFC 2047**](https://python-all.ru/3.3/library/email.policy.html) и текущие MIME RFC.195196Эта политика добавляет новые алгоритмы разбора и свёртывания заголовков. Вместо простых строк заголовки представляют собой пользовательские объекты с пользовательскими атрибутами, зависящими от типа поля. Алгоритмы разбора и свёртывания полностью реализуют [**RFC 2047**](https://python-all.ru/3.3/library/email.policy.html) и [**RFC 5322**](https://python-all.ru/3.3/library/email.policy.html).197198В дополнение к настраиваемым атрибутам, перечисленным выше и относящимся ко всем политикам, эта политика добавляет следующие дополнительные атрибуты:199200#### `refold_source`201202If the value for a header in the `Message` object originated from a [`parser`](https://python-all.ru/3.3/library/email.parser.html#module-email.parser) (as opposed to being set by a program), this attribute indicates whether or not a generator should refold that value when transforming the message back into stream form. The possible values are:203204| `none` | все исходные значения используют исходное сворачивание |205| --- | --- |206| `long` | исходные значения, содержащие строки длиннее `max_line_length`, будут переформированы |207| `все` | все значения сворачиваются заново. |208209По умолчанию `long`.210211#### `header_factory`212213Вызываемый объект, который принимает два аргумента, `name` и `value`, где `name` – это имя поля заголовка, а `value` – развёрнутое значение поля заголовка, и возвращает подкласс строки, представляющий этот заголовок. Предоставляется стандартная `header_factory` (см. [`headerregistry`](https://python-all.ru/3.3/library/email.headerregistry.html#module-email.headerregistry)), которая понимает некоторые типы полей заголовков [**RFC 5322**](https://python-all.ru/3.3/library/email.policy.html). (В настоящее время поля адресов и дат обрабатываются особым образом, а все остальные поля считаются неструктурированными. Этот список будет дополнен до того, как расширение будет помечено как стабильное.)214215Класс предоставляет следующие конкретные реализации абстрактных методов [`Policy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy):216217#### `header_max_count(name)`218219Возвращает значение атрибута [`max_count`](https://python-all.ru/3.3/library/email.headerregistry.html#email.headerregistry.BaseHeader.max_count) специализированного класса, используемого для представления заголовка с заданным именем.220221#### `header_source_parse(sourcelines)`222223Реализация этого метода такая же, как для политики [`Compat32`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Compat32).224225#### `header_store_parse(name, value)`226227Имя возвращается без изменений. Если входное значение имеет атрибут `name`, и он совпадает с *name* без учёта регистра, значение возвращается без изменений. В противном случае *name* и *value* передаются в `header_factory`, и полученный пользовательский объект заголовка возвращается в качестве значения. В этом случае возбуждается `ValueError`, если входное значение содержит символы CR или LF.228229#### `header_fetch_parse(name, value)`230231Если значение имеет атрибут `name`, оно возвращается без изменений. В противном случае *name* и *value* с удалёнными символами CR или LF передаются в `header_factory`, и возвращается полученный пользовательский объект заголовка. Любые байты с суррогатным экранированием преобразуются в глиф неизвестного символа Unicode.232233#### `fold(name, value)`234235Свёртывание заголовков управляется настройкой политики [`refold_source`](https://python-all.ru/3.3/library/email.policy.html#email.policy.EmailPolicy.refold_source). Значение считается «исходным значением» тогда и только тогда, когда оно не имеет атрибута `name` (наличие атрибута `name` означает, что это некоторый объект заголовка). Если исходное значение необходимо заново свернуть в соответствии с политикой, оно преобразуется в пользовательский объект заголовка путём передачи *name* и *value* с удалёнными символами CR и LF в `header_factory`. Свёртывание пользовательского объекта заголовка выполняется вызовом его метода `fold` с текущей политикой.236237Исходные значения разбиваются на строки с помощью [`splitlines()`](https://python-all.ru/3.3/library/stdtypes.html#str.splitlines). Если значение не нужно переформировывать, строки объединяются обратно с использованием `linesep` из политики и возвращаются. Исключение составляют строки, содержащие не-ASCII двоичные данные. В этом случае значение переформировывается независимо от настройки `refold_source`, что приводит к кодированию двоичных данных с помощью CTE, используя кодировку `unknown-8bit`.238239#### `fold_binary(name, value)`240241То же, что и [`fold()`](https://python-all.ru/3.3/library/email.policy.html#email.policy.EmailPolicy.fold), если [`cte_type`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.cte_type) равно `7bit`, за исключением того, что возвращаемое значение – это байты.242243Если [`cte_type`](https://python-all.ru/3.3/library/email.policy.html#email.policy.Policy.cte_type) равно `8bit`, не-ASCII двоичные данные преобразуются обратно в байты. Заголовки с двоичными данными не переформировываются, независимо от настройки `refold_header`, поскольку невозможно определить, состоят ли двоичные данные из однобайтовых или многобайтовых символов.244245Следующие экземпляры [`EmailPolicy`](https://python-all.ru/3.3/library/email.policy.html#email.policy.EmailPolicy) предоставляют значения по умолчанию, подходящие для конкретных областей применения. Обратите внимание, что в будущем поведение этих экземпляров (в частности, экземпляра `HTTP`) может быть скорректировано для ещё более точного соответствия RFC, имеющим отношение к их областям.246247#### `email.policy.default`248249Экземпляр `EmailPolicy` со всеми значениями по умолчанию без изменений. Эта политика использует стандартные для Python окончания строк `\n`, а не правильные по RFC `\r\n`.250251#### `email.policy.SMTP`252253Подходит для сериализации сообщений в соответствии с email RFC. Как и `default`, но с `linesep`, установленным в `\r\n`, что соответствует RFC.254255#### `email.policy.HTTP`256257Подходит для сериализации заголовков для использования в HTTP-трафике. Как и `SMTP`, за исключением того, что `max_line_length` установлено в `None` (без ограничений).258259#### `email.policy.strict`260261Удобный экземпляр. То же, что и `default`, за исключением того, что `raise_on_defect` установлено в `True`. Это позволяет сделать любую политику строгой, написав:262263```python264somepolicy + policy.strict265```266267Со всеми этими [`EmailPolicies`](https://python-all.ru/3.3/library/email.policy.html#email.policy.EmailPolicy) эффективный API пакета email изменяется по сравнению с API Python 3.2 следующим образом:268269> - Установка заголовка в [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) приводит к его разбору и созданию пользовательского объекта заголовка.270> - Получение значения заголовка из [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message) приводит к его разбору и созданию и возврату пользовательского объекта заголовка.271> - Любой пользовательский объект заголовка или заголовок, который повторно свёртывается из-за настроек политики, сворачивается с использованием алгоритма, полностью реализующего алгоритмы свёртывания RFC, включая знание того, где требуются и разрешены закодированные слова.272273С точки зрения приложения это означает, что любой заголовок, полученный через [`Message`](https://python-all.ru/3.3/library/email.message.html#email.message.Message), является пользовательским объектом заголовка с пользовательскими атрибутами, строковое значение которого – полностью декодированное значение заголовка в Unicode. Точно так же заголовку может быть присвоено новое значение, или создан новый заголовок с использованием строки Unicode, и политика позаботится о преобразовании строки Unicode в правильную закодированную форму RFC.274275Пользовательские объекты заголовков и их атрибуты описаны в [`headerregistry`](https://python-all.ru/3.3/library/email.headerregistry.html#module-email.headerregistry).276