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 внутри программы, хотя согласно RFC требуется \r\n.

cte_type

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

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

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

raise_on_defect

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

mangle_from_

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

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

message_factory

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

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

verify_generated_headers

Если установлено значение True (по умолчанию), генератор вызовет исключение HeaderWriteError вместо записи заголовка с неправильными переносами или разделителями, из-за которых он будет разобран как несколько заголовков или объединён с соседними данными. Такие заголовки могут создавать пользовательские классы заголовков или ошибки в модуле email.

Поскольку это функция безопасности, значение по умолчанию — True даже для политики Compat32. Чтобы получить обратно совместимое, но небезопасное поведение, необходимо явно установить значение False.

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

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

clone(**kw)

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

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

handle_defect(obj, defect)

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

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

register_defect(obj, defect)

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

Реализация по умолчанию вызывает метод 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 может содержать двоичные данные, преобразованные в суррогатные escape-последовательности.

Реализация по умолчанию отсутствует.

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 может содержать двоичные данные, преобразованные в суррогатные escape-последовательности. Возвращаемое методом значение не должно содержать таких двоичных данных.

Реализация по умолчанию отсутствует.

fold(name, value)

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

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

fold_binary(name, value)

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

value может содержать двоичные данные, преобразованные в суррогатные escape-последовательности. В возвращаемом объекте 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 и он соответствует name без учёта регистра, значение возвращается без изменений. В противном случае header_factory передаются name и value, а полученный объект заголовка возвращается в качестве значения. В этом случае, если входное значение содержит символы CR или LF, вызывается исключение ValueError.

header_fetch_parse(name, value)

Если у значения есть атрибут name, оно возвращается без изменений. В противном случае header_factory передаются name и value без символов CR и LF, после чего возвращается полученный объект заголовка. Байты, обработанные с помощью surrogateescape, преобразуются в символ Юникода для неизвестного символа.

fold(name, value)

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

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

fold_binary(name, value)

Работает так же, как fold(), если cte_type имеет значение 7bit, однако возвращаемое значение имеет тип bytes.

Если cte_type имеет значение 8bit, двоичные данные не ASCII преобразуются обратно в байты. Заголовки с двоичными данными не сворачиваются повторно независимо от настройки 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, является объектом заголовка с дополнительными атрибутами, строковое значение которого представляет собой полностью декодированное значение заголовка. Аналогично, заголовку можно присвоить новое значение или создать новый заголовок, используя строку; политика преобразует строку в правильную форму, закодированную согласно 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.

Примечание

Политику compat32 не следует использовать для объектов EmailMessage; её следует применять только для сериализации сообщений, созданных с использованием политики compat32.

Сноски