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 метод.
-
-
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 как временная особенность. |