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

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

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

---

Главный фокус пакета email - обработка электронных писем, как описано различной электронной почтой и MIME RFCs. Однако общий формат электронных писем (блок полей заголовка, каждый состоящий из имени, сопровождаемого двоеточием, сопровождаемым значение, целый блок, сопровождаемый пустой строкой и произвольным „телом“), формат, который нашел полезность за пределами сферы электронной почты. Некоторые из этих применений достаточно тесно соответствуют основным RFC электронной почты, даже при работе с электронной почтой бывают случаи, когда желательно нарушить строгое соблюдение RFC, например, создание сообщений электронной почты, взаимодействующих с серверами электронной почты, которые сами не соответствуют стандартам, или реализуют расширения, которые необходимо использовать в нарушение стандартов.

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

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

Есть политика по умолчанию используемый всеми классами в почтовом пакете. Для всех классов parser и связанных функций удобства, и для класса Message, это - политика Compat32 через ее соответствующий предопределенный сущность compat32. Эта политика обеспечивает полную обратную совместимость (в некоторых случаях, включая совместимость с ошибками) с пре Python3.3 версией пакета электронной почты.

Этот дефолт значение для policy ключевой к EmailMessage является политикой EmailPolicy через ее предопределенный сущность default.

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

Дефолт значение для policy ключевой для классов email.parser и удобства парсер функционирует будет меняться в будущей версии Python. Поэтому вы должны всегда четко указывайте, какую политику вы хотите использовать, называя любой из классов и функций описанным в модуле parser.

Первая часть этой документации описывает особенности Policy, абстрактный базовый класс, который определяет черты, которые характерны для всех стратегических объектов, включая compat32. Это включает определенные методы перехвата, вызываемые внутри пакета электронной почты, которые настраиваемая политика может переопределить для получения другого поведения. Во второй части описываются конкретные классы 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.

Некоторые методы пакета электронной почты принимают аргумент 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

Управляет типом кодировок передачи контента, которые могут быть или должны быть используемый. Возможный значения are:

7bit	все данные должны быть «7-разрядными чистыми» (только ASCII). Это означает это, где необходимые данные будут кодированный, используя или указанный - закавыченная печатать или base64 кодировку.
8bit	данные не ограничены 7-разрядной чистотой. Данные в заголовках по-прежнему должны быть только ASCII и поэтому будут кодированный (см. fold_binary() и utf8 ниже для исключений), но части body могут использовать 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.

Добавлено в версии 3.5: Параметр mangle_from_.

message_factory

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

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

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

clone(**kw)

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

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

handle_defect(obj, defect)

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

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

register_defect(obj, defect)

Зарегистрировать defect на obj. В пакете электронной почты defect всегда будет подкласс Defect.

Реализация по умолчанию вызывает метод append defects атрибут obj. Когда почтовый пакет назовет handle_defect, у obj обычно будет defects атрибут, у которого есть метод append. Пользовательский объект печатает используемый с почтовым пакетом (например, пользовательские объекты Message) должен также обеспечить такой атрибут, иначе дефекты в размеченных сообщениях поднимут неожиданные ошибки.

header_max_count(name)

Возвращает максимально допустимое число заголовков с именем name.

Вызывается при добавлении заголовка к объекту EmailMessage или Message. Если возвращенныйзначение не является 0 или None, и уже существует ряд заголовков с именем name, большим или равным возвращаемому значение, возникает ValueError.

Поскольку поведение Message.__setitem__ по умолчанию заключается в добавлении значение в список заголовков, легко создать дубликаты заголовков, не реализуя их. Этот способ позволяет ограничить некоторые заголовки количеством сущности этого заголовка, которые могут быть добавлены к Message программным способом. (Предел не соблюдается парсер, который верно создает столько заголовков, сколько существует в анализируемом сообщении.

Реализация по умолчанию возвращает None для всех имен заголовков.

header_source_parse(sourcelines)

Почтовый пакет называет этот метод со списком строки, каждый строка, заканчивающийся знаками разделения линии найденный в источнике разбираемый. Первая строка включает имя заголовка поля и разделитель. Все пробелы в источнике сохраняются. Метод должен кортеж возвращает (name, value), который должен быть сохранен в Message, чтобы представлять размеченный заголовок.

Если внедрение хочет сохранить совместимость с существующей почтовой политикой пакета, name должен быть сохраненным именем случая (все знаки до сепаратора „:“), в то время как value должен быть развернутым значение (все удаленные знаки сепаратора линии, но сохраненный в целости пробел), лишенный ведущего пробела.

sourcelines может содержать двоичные данные суррогатного типа.

Реализация по умолчанию отсутствует

header_store_parse(name, value)

Пакет электронной почты вызывает этот метод с именем и значение, предоставленными прикладной программой, когда прикладная программа изменяет Message программным образом (в отличие от Message, созданного парсер). Метод должен кортеж возвращает (name, value), который должен быть сохранен в Message, чтобы представлять заголовок.

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

Реализация по умолчанию отсутствует

header_fetch_parse(name, value)

Пакет электронной почты вызывает этот метод с name и value, хранящимися в настоящее время в Message, когда этот заголовок запрашивается прикладной программой, и что бы метод не возвращал, это то, что передается обратно приложению как значение извлекаемого заголовка. Следует отметить, что в Message может быть несколько заголовков с одинаковым именем; метод передан собственное имя и значение заголовка, предназначенного, чтобы быть возвращенныйto применение.

value может содержать двоичные данные суррогатного типа. Не должно быть никаких surrogateescaped двоичных данных в значение возвращенныйby метод.

Реализация по умолчанию отсутствует

fold(name, value)

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

value может содержать двоичные данные суррогатного типа. Не должно быть никаких surrogateescaped двоичных данных в строка возвращенныйby метод.

fold_binary(name, value)

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

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

class email.policy.EmailPolicy(**kw)

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

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

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)

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

header_fetch_parse(name, value)

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

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 пакета электронной почты изменяется по сравнению с API Python 3.2 следующим образом: * установка заголовка на Message приводит к анализу этого заголовка и созданию объекта заголовка.

• Выборка заголовка значение из Message приводит к тому, что этот заголовок анализируется, а объект заголовка создается и возвращается.
• Любой объект заголовка или любой заголовок, повторно свернутый из-за параметров политики, сворачивается с использованием алгоритма, полностью реализующего алгоритмы сворачивания RFC, включая информацию о том, где требуется и разрешено использование слов кодированный.

Из представления приложения это означает, что любой заголовок, полученный через EmailMessage, является объектом заголовка с дополнительным атрибуты, чей строка значение является полностью декодированным значение юникода заголовка. Также, заголовку можно назначить новый значение или новый созданный заголовок, используя unicode строка, и политика будет заботиться о преобразовании unicode строка в правильную форму RFC кодированный.

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

class email.policy.Compat32(**kw)

Этот конкретный Policy - политика обратной совместимости. Он реплицирует поведение пакета электронной почты в Python 3.2. Модуль policy также определяет сущность этого класса, compat32, который является используемый как политикой по умолчанию. Таким образом, по умолчанию пакет электронной почты поддерживает совместимость с Python 3.2.

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

mangle_from_

Значение по умолчанию - True.

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

header_source_parse(sourcelines)

Название анализируется как все до „:“ и возвращенныйunmodified. значение определяется путем удаления ведущего пробела с остальной части первой строки, соединения всех последующих строк вместе и удаления любых задних символов каретки возвращает or линии.

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

email.policy.compat32

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

Сноски

[1]	Первоначально добавлен в 3.3 как временная особенность.