email.policy: Объекты Политики

Исходный код: Lib/email/policy.py

Основная задача пакета email — обработка сообщений электронной почты в соответствии с различными RFC для электронной почты и MIME. Однако общий формат сообщений электронной почты (блок полей заголовков, каждый из которых состоит из имени, за которым следует двоеточие и значение, весь блок, за которым следует пустая строка и произвольное «тело»), находит применение и за пределами области электронной почты. Некоторые из этих применений достаточно точно соответствуют основным RFC, другие — нет. И даже при работе с электронной почтой иногда желательно нарушить строгую приверженность RFC.

Объекты Политики обеспечивают пакету email гибкость для обработки всех этих различных случаев использования.

Объект Policy инкапсулирует набор атрибутов и методов, которые управляют поведением различных компонентов пакета email во время использования. Экземпляры Policy могут быть переданы различным классам и методам в пакете email для изменения стандартного поведения. Устанавливаемые значения и их значения по умолчанию описаны ниже.

Все классы в пакете email используют политику по умолчанию. Эта политика называется Compat32, с соответствующим предварительно определённым экземпляром, названным compat32. Она обеспечивает полную обратную совместимость (в некоторых случаях, включая совместимость с ошибками) с версией пакета email до Python 3.3.

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

При создании объекта Message, он получает политику. По умолчанию это будет compat32, но можно указать другую политику. Если Message создаётся с помощью parser, политика, переданная парсеру, будет политикой, используемой Message , которое он создаёт. Если Message создаётся программой, политика может быть указана при её создании. Когда Message передаётся в generator, генератор использует политику из Message по умолчанию, но вы также можете передать генератору определённую политику, которая переопределит ту, что хранится в объекте Message.

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, и поэтому будут закодированы (см. «binary_fold» ниже для исключения), но части тела могут использовать 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: Параметр mangle_from_.

Следующий метод 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.

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

value может содержать данные с суррогатным экранированием. В возвращаемой строке не должно быть данных с суррогатным экранированием.

fold_binary(name, value)

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

value может содержать бинарные данные, закодированные суррогатами. Они могут быть преобразованы обратно в бинарные данные в возвращаемом объекте типа bytes.

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)

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

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) бинарными данными, которые он может содержать.

Экземпляр Compat32 предоставляется как константа модуля:

email.policy.compat32

Экземпляр Compat32, обеспечивающий обратную совместимость с поведением пакета email в Python 3.2.

class email.policy.EmailPolicy(**kw)

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

Данный стандарт добавляет новые алгоритмы разбора и сворачивания заголовков. Вместо простых строк, заголовки представляют собой str подклассы с атрибутами, зависящими от типа поля. Алгоритм разбора и сворачивания полностью реализует RFC 2047 и RFC 5322.

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

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. (В настоящее время поля адресов и дат имеют специальное обращение, в то время как все остальные поля рассматриваются как неструктурированные. Этот список будет завершен до того, как расширение будет помечено как стабильное.)

content_manager

Объект, содержащий по крайней мере два метода: get_content и set_content. При вызове метода get_content() или set_content() объекта Message он вызывает соответствующий метод этого объекта, передавая ему объект сообщения в качестве первого аргумента и любые аргументы или ключевые слова, переданные ему в качестве дополнительных аргументов. По умолчанию content_manager установлен в raw_data_manager.

Новое в версии 3.4.

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

header_max_count(name)

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

header_source_parse(sourcelines)

Реализация этого метода такая же, как и для политики Compat32.

header_store_parse(name, value)

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

header_fetch_parse(name, value)

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

fold(name, value)

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

Исходные значения разбиваются на строки с помощью splitlines(). Если значение не должно пересчитываться, строки объединяются с помощью linesep из политики и возвращаются. Исключение составляют строки, содержащие не-ASCII бинарные данные. В этом случае значение пересчитывается независимо от значения refold_source , что приводит к кодированию бинарных данных с использованием кодировки 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, в том числе знающего, где требуются и разрешены закодированные слова.

С точки зрения приложения это означает, что любой заголовок, полученный через Message, представляет собой объект заголовка с дополнительными атрибутами, значение которого в строковом формате — полностью декодированное значение заголовка в Unicode. Аналогично, заголовку можно присвоить новое значение или создать новый заголовок, используя строку Unicode, и политика позаботится о преобразовании строки Unicode в правильный кодированный по RFC формат.

Объекты заголовков и их атрибуты описаны в headerregistry.