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.

New in version 3.5: Параметр mangle_from_.

message_factory

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

New in version 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 вызывает этот метод со значениями 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.

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

New in version 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.

New in version 3.4.

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

header_max_count(name)

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

header_source_parse(sourcelines)

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

header_store_parse(name, value)

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

header_fetch_parse(name, value)

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

fold(name, value)

Складывание заголовков контролируется настройкой политики refold_source. Значение считается «исходным значением» только тогда, когда у него нет атрибута name (наличие атрибута name означает, что это объект заголовка какого-то типа). Если исходное значение нужно перескладывать в соответствии с политикой, оно преобразуется в объект заголовка путём передачи имени и значения, из которого удалены любые символы CR и LF, в 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, является объектом заголовка с дополнительными атрибутами, значение которого в виде строки — полностью декодированное значение юникода заголовка. Аналогично, заголовку можно присвоить новое значение или создать новый заголовок, используя строку юникода, и политика позаботится о преобразовании строки юникода в правильную закодированную форму 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 в качестве промежуточной функции.