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.

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

message_factory

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

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

verify_generated_headers

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

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

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

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

clone(**kw)

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

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

handle_defect(obj, defect)

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

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

register_defect(obj, 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.

Примечания