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

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

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

Значение 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)

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

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

register_defect(obj, defect)

Регистрирует 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 вызывает этот метод со значениями имени и значения, хранящимися в Message, когда приложение запрашивает этот заголовок, и всё, что возвращает метод, передаётся обратно приложению в качестве значения запрашиваемого заголовка. Обратите внимание, что в Message может храниться более одного заголовка с одинаковым именем; методу передаётся конкретное имя и значение заголовка, предназначенного для возврата приложению.

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

Нет реализации по умолчанию.

fold(name, value)

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

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

fold_binary(name, value)

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

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

class email.policy.EmailPolicy(**kw)

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

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

header_fetch_parse(name, value)

Если значение имеет атрибут name, оно возвращается без изменений. В противном случае name и value (с удаленными CR и LF символами) передаются в header_factory, и возвращается полученный объект заголовка. Любые суррогатные байты с экранированием преобразуются в глиф неизвестного символа Unicode.

fold(name, value)

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

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

fold_binary(name, value)

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

Если 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, является объектом заголовка с дополнительными атрибутами, чьё строковое значение — полностью декодированное значение 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 в качестве временной функции.