email.policy: Объекты Политики

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

Основное внимание пакета email уделяется обработке электронных сообщений, как описано в различных RFC для электронной почты и MIME. Однако общий формат электронных сообщений (блок полей заголовка, каждый из которых состоит из имени, за которым следует двоеточие, а затем значение, весь блок, за которым следует пустая строка и произвольное «тело»), нашел применение и за пределами электронной почты. Некоторые из этих применений довольно точно соответствуют основным RFC электронной почты, другие — нет. Даже при работе с электронной почтой бывают случаи, когда желательно нарушить строгое соблюдение RFC, например, при создании электронных писем, которые взаимодействуют с серверами электронной почты, которые сами не следуют стандартам, или которые реализуют расширения, которые вы хотите использовать способами, нарушающими стандарты.

Объекты Политики обеспечивают пакет email гибкость для обработки всех этих различных случаев использования.

Объект Policy инкапсулирует набор атрибутов и методов, которые контролируют поведение различных компонентов пакета email во время использования. Экземпляры Policy могут быть переданы различным классам и методам в пакете email, чтобы изменить поведение по умолчанию. Устанавливаемые значения и их значения по умолчанию описаны ниже.

Все классы пакета email используют политику по умолчанию. Для всех классов parser и связанных с ними функций удобства, а также для класса Message, это политика Compat32 через соответствующий предопределенный экземпляр compat32. Эта политика обеспечивает полную обратную совместимость (в некоторых случаях, включая совместимость с ошибками) с предшествующей версией пакета email до Python 3.3.

Это значение по умолчанию для ключевого слова policy для EmailMessage — это политика EmailPolicy через предопределенный экземпляр default.

Когда создается объект Message или EmailMessage, он получает политику. Если сообщение создано с помощью parser, политика, переданная парсеру, будет политикой, используемой сообщением, которое он создает. Если сообщение создается программой, политика может быть указана при его создании. Когда сообщение передается generator, генератор по умолчанию использует политику из сообщения, но вы также можете передать генератору определенную политику, которая переопределит политику, хранящуюся в объекте сообщения.

Значение по умолчанию для ключевого слова policy для классов email.parser и функций удобства парсера будет изменяться в будущей версии Python. Поэтому вы должны всегда явно указывать используемую политику при вызове любого из классов и функций, описанных в модуле parser.

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

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

В качестве примера, следующий код может быть использован для чтения сообщения электронной почты из файла на диске и передачи его системе sendmail на системе Unix:

>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()

Здесь мы говорим BytesGenerator использовать правильные разделители строк RFC при создании двоичной строки для передачи в sendmail's stdin, где политика по умолчанию использовала бы \n разделители строк.

Некоторые методы пакета email принимают ключевой аргумент policy, позволяя переопределить политику для этого метода. Например, следующий код использует метод as_bytes() объекта msg из предыдущего примера и записывает сообщение в файл с использованием собственных разделителей строк для платформы, на которой он выполняется:

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

Объекты Политики также могут быть объединены с помощью оператора сложения, создавая объект политики, настройки которого являются комбинацией значений отличных от значений по умолчанию для суммированных объектов:

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

Эта операция не коммутативна; то есть порядок, в котором добавляются объекты, имеет значение. В качестве иллюстрации:

>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100

class email.policy.Policy(**kw)

Это базовый класс для всех классов политики. Он предоставляет реализацию по умолчанию для нескольких тривиальных методов, а также реализацию свойства неизменяемости, метод clone() и семантику конструктора.

Конструктор класса политики может принимать различные ключевые аргументы. Аргументы, которые могут быть указаны, — это любые свойства, не являющиеся методами, в этом классе, плюс любые дополнительные свойства, не являющиеся методами, в конкретном классе. Указанное в конструкторе значение переопределит значение по умолчанию для соответствующего атрибута.

Этот класс определяет следующие свойства, а значит, значения для них могут быть переданы в конструктор любого класса политики:

max_line_length

Максимальная длина любой строки в сериализованном выводе, не считая символа(ов) конца строки. Значение по умолчанию — 78, в соответствии с RFC 5322. Значение 0 или None указывает на то, что никакой перенос строк не должен выполняться.

linesep

Строка, используемая для завершения строк в сериализованном выводе. Значение по умолчанию — \n, так как это внутреннее правило завершения строки, используемое Python, хотя \r\n требуется RFC.

cte_type

Управляет типом кодировок Content Transfer Encoding, которые могут быть или должны быть использованы. Возможные значения:

7bit	все данные должны быть «7-битными» (только ASCII). Это означает, что при необходимости данные будут закодированы с использованием кодировки quoted-printable или base64.
8bit	данные не ограничены 7-битными значениями. Данные в заголовках по-прежнему должны быть только ASCII и будут закодированы (см. fold_binary() и utf8 ниже для исключений), но части тела могут использовать CTE 8bit.

Значение cte_type 8bit работает только с BytesGenerator, а не с Generator, потому что строки не могут содержать двоичные данные. Если Generator работает в политике, которая задает cte_type=8bit, то она будет действовать так, как если бы cte_type была 7bit.

raise_on_defect

Если True, любые обнаруженные дефекты будут подняты как ошибки. Если False (значение по умолчанию), дефекты будут переданы методу register_defect().

mangle_from_

Если True, строки, начинающиеся с «From « в теле, экранируются, помещая > перед ними. Этот параметр используется при сериализации сообщения с помощью генератора. Значение по умолчанию: False.

Новое в версии 3.5: Параметр mangle_from_.

message_factory

Функция-фабрика для создания нового пустого объекта сообщения. Используется парсером при создании сообщений. Значение по умолчанию — None, в этом случае используется Message.

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

Следующий метод Policy предназначен для вызова кодом, использующим библиотеку email, для создания экземпляров политики с пользовательскими настройками:

clone(**kw)

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

Остальные методы Policy вызываются кодом пакета email и не предназначены для вызова приложением, использующим пакет email. Пользовательская политика должна реализовывать все эти методы.

handle_defect(obj, defect)

Обрабатывает дефект, обнаруженный в obj. Когда пакет email вызывает этот метод, defect всегда будет подклассом Defect.

Реализация по умолчанию проверяет флаг raise_on_defect. Если он True, defect поднимается как исключение. Если он False (значение по умолчанию), obj и defect передаются методу register_defect().

register_defect(obj, defect)

Регистрирует дефект в obj. В пакете email defect всегда будет подклассом Defect.

Реализация по умолчанию вызывает метод append атрибута defects объекта obj. Когда пакет email вызывает handle_defect, obj обычно будет иметь атрибут defects, который имеет метод append. Пользовательские типы объектов, используемые с пакетом email (например, пользовательские объекты Message), также должны предоставлять такой атрибут, иначе дефекты в парсируемых сообщениях приведут к неожиданным ошибкам.

header_max_count(name)

Возвращает максимальное разрешенное количество заголовков с именем name.

Вызывается при добавлении заголовка к объекту EmailMessage или Message. Если возвращаемое значение не 0 или None, и уже имеется количество заголовков с именем name, равное или больше возвращаемого значения, генерируется исключение ValueError.

Поскольку поведение по умолчанию Message.__setitem__ заключается в добавлении значения в список заголовков, легко создать дублируемые заголовки, не осознавая этого. Этот метод позволяет ограничить количество экземпляров определенного заголовка, которые могут быть добавлены в программу Message программно. (Ограничение не учитывается парсером, который будет верным образом создавать столько заголовков, сколько существует в анализируемом сообщении.)

Реализация по умолчанию возвращает None для всех имен заголовков.

header_source_parse(sourcelines)

Пакет email вызывает этот метод со списком строк, каждая из которых заканчивается символами разделителя строк, найденными в анализируемом источнике. Первая строка включает имя поля заголовка и разделитель. Все пробелы в исходном коде сохраняются. Метод должен вернуть кортеж (name, value), который будет храниться в Message для представления распарсенного заголовка.

Если реализация хочет сохранить совместимость с существующими политиками пакета email, name должен быть именем с сохранением регистра (все символы до разделителя ‘:’), а value — развернутым значением (все символы разделителя строк удаляются, но пробелы сохраняются), очищенным от начальных пробелов.

sourcelines может содержать данные с кодировкой суррогатов.

Реализации по умолчанию нет

header_store_parse(name, value)

Пакет email вызывает этот метод с именем и значением, предоставленными приложением, когда приложение модифицирует программу Message программно (в отличие от программы Message, созданной парсером). Метод должен вернуть кортеж (name, value), который будет храниться в Message для представления заголовка.

Если реализация хочет сохранить совместимость с существующими политиками пакета email, name и value должны быть строками или подклассами строк, которые не изменяют содержимое переданных аргументов.

Реализации по умолчанию нет

header_fetch_parse(name, value)

Пакет email вызывает этот метод с name и value, хранящимися в Message при запросе этого заголовка приложением, а возвращаемое методом значение передается обратно приложению как значение запрашиваемого заголовка. Обратите внимание, что в Message может быть храниться более одного заголовка с одинаковым именем; методу передается конкретное имя и значение заголовка, предназначенного для возврата приложению.

value может содержать данные с кодировкой суррогатов. В возвращаемом методом значении не должно быть данных с кодировкой суррогатов.

Реализации по умолчанию нет

fold(name, value)

Пакет email вызывает этот метод со значениями имя и значение, хранящимися в Message для данного заголовка. Метод должен вернуть строку, представляющую этот заголовок, «сложенный» правильно (в соответствии с настройками политики), соединяя имя со значением и вставляя символы linesep в соответствующих местах. См. RFC 5322 для обсуждения правил «складывания» заголовков электронной почты.

значение может содержать закодированные двоичные данные. В возвращаемой методом строке не должно быть закодированных двоичных данных.

fold_binary(name, value)

То же, что и fold(), за исключением того, что возвращаемое значение должно быть объектом типа bytes, а не строкой.

значение может содержать закодированные двоичные данные. Эти данные могут быть преобразованы обратно в двоичные данные в возвращаемом объекте bytes.

class email.policy.EmailPolicy(**kw)

Этот конкретный Policy обеспечивает поведение, полностью соответствующее текущим RFC для электронной почты. Это включает в себя (но не ограничивается ими) RFC 5322, RFC 2047 и текущие RFC для MIME.

Эта политика добавляет новые алгоритмы анализа и «складывания» заголовков. Вместо простых строк, заголовки являются str подклассами с атрибутами, зависящими от типа поля. Алгоритм анализа и «складывания» полностью реализует RFC 2047 и RFC 5322.

Значение по умолчанию для атрибута message_factory — EmailMessage.

В дополнение к настраиваемым атрибутам, применяемым ко всем политикам, эта политика добавляет следующие дополнительные атрибуты:

Добавлена в версии 3.6: 1

utf8

Если False, следуйте RFC 5322, поддерживая символы, не из ASCII, в заголовках, кодируя их как «закодированные слова». Если True, следуйте RFC 6532 и используйте кодировку utf-8 для заголовков. Сообщения, отформатированные таким образом, могут быть переданы серверам SMTP, которые поддерживают расширение SMTPUTF8 (RFC 6531).

refold_source

Если значение для заголовка в объекте Message получено из parser (а не задано программно), этот атрибут указывает, следует ли генератору перескладывать это значение при преобразовании сообщения обратно в сериализованную форму. Возможные значения:

none	все исходные значения используют исходное «складывание»
long	исходные значения, у которых есть строки, длиннее max_line_length, будут перескладываться
all	все значения перескладываются.

Значение по умолчанию — long.

header_factory

Функция, принимающая два аргумента, name и value, где name — имя поля заголовка, а value — значение поля заголовка без «складывания», и возвращающая подкласс строки, представляющий этот заголовок. Предоставляется по умолчанию header_factory (см. headerregistry), который поддерживает пользовательский анализ различных типов полей заголовков адресов и дат RFC 5322 и основных типов полей MIME заголовков. Поддержка дополнительного пользовательского анализа будет добавлена в будущем.

content_manager

Объект с по крайней мере двумя методами: get_content и set_content. Когда вызывается метод get_content() или set_content() объекта EmailMessage, он вызывает соответствующий метод этого объекта, передавая ему объект сообщения в качестве первого аргумента и любые аргументы или ключевые слова, переданные ему в качестве дополнительных аргументов. По умолчанию content_manager установлено в raw_data_manager.

Добавлена в версии 3.4.

Класс предоставляет следующие конкретные реализации абстрактных методов Policy:

header_max_count(name)

Возвращает значение атрибута max_count специализированного класса, используемого для представления заголовка с данным именем.

header_source_parse(sourcelines)

Имя анализируется как все до «:» и возвращается без изменений. Значение определяется путем удаления начальных пробелов из оставшейся части первой строки, объединения всех последующих строк и удаления любых конечных символов возврата каретки или перевода строки.

header_store_parse(name, value)

Имя возвращается без изменений. Если входное значение имеет атрибут name и оно совпадает с именем, не учитывая регистр, значение возвращается без изменений. В противном случае имя и значение передаются в header_factory, и полученный объект заголовка возвращается в качестве значения. В этом случае возникает ValueError если входное значение содержит символы возврата каретки или перевода строки.

header_fetch_parse(name, value)

Если значение имеет атрибут name, оно возвращается без изменений. В противном случае имя и значение с удаленными символами возврата каретки и перевода строки передаются в header_factory, и полученный объект заголовка возвращается. Любые закодированные двоичные данные преобразуются в глифы неизвестных символов Юникода.

fold(name, value)

«Складывание» заголовков контролируется настройкой политики refold_source. Значение считается «исходным значением», только если оно не имеет атрибута name (наличие атрибута name означает, что это объект заголовка). Если исходное значение необходимо перескладить в соответствии с политикой, оно преобразуется в объект заголовка путем передачи имени и значения с удаленными символами возврата каретки и перевода строки в header_factory. Складывание объекта заголовка выполняется путем вызова его метода fold с текущей политикой.

Исходные значения разбиваются на строки с помощью splitlines(). Если значение не должно перескладываться, строки объединяются с помощью linesep из политики и возвращаются. Исключение составляют строки, содержащие двоичные данные, не являющиеся ASCII. В этом случае значение перескладывается независимо от настройки refold_source, что приводит к кодированию двоичных данных CTE с использованием набора символов unknown-8bit.

fold_binary(name, value)

То же, что и fold(), если cte_type равно 7bit, за исключением того, что возвращаемое значение — объект bytes.

Если cte_type равно 8bit, двоичные данные, не являющиеся ASCII, преобразуются обратно в bytes. Заголовки с двоичными данными не перескладываются, независимо от настройки refold_header , поскольку нет способа узнать, состоят ли двоичные данные из однобайтовых символов или многобайтовых.

Следующие примеры EmailPolicy предоставляют значения по умолчанию, подходящие для конкретных областей применения. Обратите внимание, что в будущем поведение этих экземпляров (в частности, экземпляра HTTP ) может быть скорректировано для ещё более точного соответствия RFC, относящимся к их областям.

email.policy.default

Экземпляр EmailPolicy со всеми значениями по умолчанию без изменений. Данная политика использует стандартные символы конца строки Python \n вместо корректных согласно RFC \r\n.

email.policy.SMTP

Подходит для сериализации сообщений в соответствии с RFC электронной почты. Подобно default, но с linesep установленным в значение \r\n, что соответствует RFC.

email.policy.SMTPUTF8

То же, что и SMTP, за исключением того, что utf8 установлено в значение True. Полезно для сериализации сообщений в хранилище сообщений без использования закодированных слов в заголовках. Следует использовать только для передачи по SMTP, если адреса отправителя или получателя содержат символы, отличные от ASCII (метод smtplib.SMTP.send_message() обрабатывает это автоматически).

email.policy.HTTP

Подходит для сериализации заголовков для использования в HTTP-трафике. Подобно SMTP, за исключением того, что max_line_length установлено в значение None (без ограничений).

email.policy.strict

Удобный экземпляр. Такой же, как default, за исключением того, что raise_on_defect установлено в значение True. Это позволяет сделать любую политику строгой, написав:

somepolicy + policy.strict

При использовании всех этих EmailPolicies эффективный API пакета email изменяется по сравнению с API Python 3.2 следующим образом:

• Установка заголовка в Message приводит к анализу этого заголовка и созданию объекта заголовка.
• Получение значения заголовка из Message приводит к анализу этого заголовка и возвращению созданного объекта заголовка.
• Любой объект заголовка или любой заголовок, который перестраивается из-за настроек политики, складывается с помощью алгоритма, который полностью реализует алгоритмы сворачивания RFC, включая знание того, где требуются и разрешены закодированные слова.

С точки зрения приложения это означает, что любой заголовок, полученный через EmailMessage, является объектом заголовка с дополнительными атрибутами, значение которого в виде строки — это полностью декодированное значение заголовка в формате Unicode. Аналогично, заголовку можно присвоить новое значение или создать новый заголовок с помощью строки Unicode, и политика позаботится о преобразовании строки Unicode в правильный закодированный согласно RFC формат.

Объекты заголовков и их атрибуты описаны в headerregistry.

class email.policy.Compat32(**kw)

Этот конкретный Policy — политика обратной совместимости. Она дублирует поведение пакета email в Python 3.2. Модуль policy также определяет экземпляр этого класса, compat32, который используется в качестве политики по умолчанию. Таким образом, по умолчанию пакет email поддерживает совместимость с Python 3.2.

Следующие атрибуты имеют значения, отличные от значений по умолчанию Policy:

mangle_from_

Значение по умолчанию — True.

Класс предоставляет следующие конкретные реализации абстрактных методов Policy:

header_source_parse(sourcelines)

Имя анализируется как всё до «:» и возвращается без изменений. Значение определяется удалением начальных пробелов из оставшейся части первой строки, объединением всех последующих строк и удалением любых конечных символов возврата каретки или новой строки.

header_store_parse(name, value)

Имя и значение возвращаются без изменений.

header_fetch_parse(name, value)

Если значение содержит двоичные данные, оно преобразуется в объект Header с помощью набора символов unknown-8bit. В противном случае оно возвращается без изменений.

fold(name, value)

Заголовки сворачиваются с помощью алгоритма сворачивания Header, который сохраняет имеющиеся переводы строк в значении и обрезает каждую полученную строку до max_line_length. Двоичные данные, не являющиеся ASCII, кодируются CTE с помощью набора символов unknown-8bit.

fold_binary(name, value)

Заголовки сворачиваются с помощью алгоритма сворачивания Header, который сохраняет имеющиеся переводы строк в значении и обрезает каждую полученную строку до max_line_length. Если cte_type равно 7bit, двоичные данные, не являющиеся ASCII, кодируются CTE с помощью набора символов unknown-8bit.

В противном случае используется исходный заголовок с имеющимися переводами строк и любыми (некорректными по RFC) двоичными данными, которые он может содержать.

email.policy.compat32

Экземпляр Compat32, обеспечивающий обратную совместимость с поведением пакета email в Python 3.2.

Примечания

1

Первоначально добавлен в 3.3 как временная функция.