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_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)

Обрабатывает дефект, обнаруженный в 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.

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

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