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 ниже для исключений), но части тела могут использовать CTE 8bit.

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

raise_on_defect

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

mangle_from_

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

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

message_factory

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

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

verify_generated_headers

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

В качестве меры безопасности по умолчанию установлено значение True даже в политике Compat32. Для совместимости со старыми версиями, но небезопасного поведения, его необходимо явно установить в значение False.

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

Следующий метод 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 программно (в отличие от заголовка, созданного анализатором). Метод должен вернуть кортеж (name, value), который будет сохранен в Message для представления заголовка.

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

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

header_fetch_parse(name, value)

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

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

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

fold(name, value)

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

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

fold_binary(name, value)

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

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

header_fetch_parse(name, value)

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

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.

Примечания