email.headerregistry: Custom Header Objects

Вихідний код: Lib/email/headerregistry.py

---

Нове в версії 3.6: 1

Заголовки представлені налаштованими підкласами str. Конкретний клас, який використовується для представлення даного заголовка, визначається header_factory policy, що діє під час створення заголовків. У цьому розділі описано конкретну header_factory, реалізовану пакетом електронної пошти для обробки RFC 5322 сумісних повідомлень електронної пошти, яка не тільки надає налаштовані об’єкти заголовків для різних типів заголовків, але також забезпечує механізм розширення для додатків для додавання своїх власні типи заголовків.

При використанні будь-якого з об’єктів політики, отриманих від EmailPolicy, усі заголовки створюються HeaderRegistry і мають BaseHeader як останній базовий клас. Кожен клас заголовка має додатковий базовий клас, який визначається типом заголовка. Наприклад, багато заголовків мають клас UnstructuredHeader як інший базовий клас. Спеціалізований другий клас для заголовка визначається назвою заголовка за допомогою таблиці пошуку, що зберігається в HeaderRegistry. Усім цим керується прозоро для типової прикладної програми, але надаються інтерфейси для зміни типової поведінки для використання більш складними програмами.

У розділах нижче спочатку описані базові класи заголовків та їх атрибути, потім API для зміни поведінки HeaderRegistry і, нарешті, класи підтримки, які використовуються для представлення даних, проаналізованих із структурованих заголовків.

class email.headerregistry.BaseHeader(name, value)

name і value передаються в BaseHeader з виклику header_factory. Рядкове значення будь-якого об’єкта заголовка є значенням, повністю декодованим у Юнікод.

Цей базовий клас визначає наступні властивості лише для читання:

name

Назва заголовка (частина поля перед «:»). Це саме значення, передане у виклику header_factory для name; тобто регістр зберігається.

defects

Кортеж екземплярів HeaderDefect, які повідомляють про будь-які проблеми відповідності RFC, виявлені під час аналізу. Пакет електронної пошти намагається бути повним щодо виявлення проблем відповідності. Перегляньте модуль errors для обговорення типів дефектів, про які можна повідомити.

max_count

Максимальна кількість заголовків цього типу, які можуть мати однакову назву. Значення None означає необмежений. Значення BaseHeader для цього атрибута є None; очікується, що спеціалізовані класи заголовків замінять це значення за потреби.

BaseHeader також надає наступний метод, який викликається кодом бібліотеки електронної пошти і, як правило, не повинен викликатися прикладними програмами:

fold(*, policy)

Повертає рядок, що містить символи linesep, необхідні для правильного згортання заголовка відповідно до policy. cte_type 8bit буде розглядатися як 7bit, оскільки заголовки не можуть містити довільних двійкових даних. Якщо utf8 має значення False, дані, відмінні від ASCII, будуть закодовані RFC 2047.

BaseHeader сам по собі не може використовуватися для створення об’єкта заголовка. Він визначає протокол, з яким співпрацює кожен спеціалізований заголовок, щоб створити об’єкт заголовка. Зокрема, BaseHeader вимагає, щоб спеціалізований клас надавав classmethod() під назвою parse. Цей метод називається наступним чином:

parse(string, kwds)

kwds — це словник, що містить один попередньо ініціалізований ключ, defects. дефекти – порожній список. Метод аналізу має додати всі виявлені дефекти до цього списку. Після повернення словник kwds має містити значення принаймні для ключів decoded і defects. decoded має бути значенням рядка для заголовка (тобто, значення заголовка, повністю декодоване в Юнікод). Метод синтаксичного аналізу має припускати, що рядок може містити частини, закодовані перенесенням вмісту, але також має правильно обробляти всі дійсні символи Unicode, щоб він міг аналізувати незакодовані значення заголовка.

Потім __new__ BaseHeader створює екземпляр заголовка та викликає його метод init. Спеціалізованому класу потрібно лише надати метод init, якщо він бажає встановити додаткові атрибути крім тих, що надаються самим BaseHeader. Такий метод init має виглядати так:

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

Тобто все зайве, що спеціалізований клас поміщає до словника kwds, має бути видалено та оброблено, а решта вмісту kw (та args) передано до BaseHeader Метод init.

class email.headerregistry.UnstructuredHeader

«Неструктурований» заголовок є типовим типом заголовка в RFC 5322. Будь-який заголовок, який не має визначеного синтаксису, вважається неструктурованим. Класичним прикладом неструктурованого заголовка є заголовок Subject.

У RFC 5322 неструктурований заголовок — це довільний текст у наборі символів ASCII. RFC 2047, однак, має RFC 5322 сумісний механізм для кодування не-ASCII тексту як символів ASCII у значенні заголовка. Коли значення, що містить закодовані слова, передається конструктору, аналізатор UnstructuredHeader перетворює такі закодовані слова в юнікод, дотримуючись правил RFC 2047 для неструктурованого тексту. Синтаксичний аналізатор використовує евристику, щоб спробувати декодувати певні невідповідні закодовані слова. У таких випадках реєструються дефекти, а також такі дефекти, як недійсні символи в закодованих словах або незакодований текст.

Цей тип заголовка не містить додаткових атрибутів.

class email.headerregistry.DateHeader

RFC 5322 визначає дуже специфічний формат для дат у заголовках електронних листів. Синтаксичний аналізатор DateHeader розпізнає цей формат дати, а також розпізнає низку варіантних форм, які іноді зустрічаються «в дикій природі».

Цей тип заголовка надає такі додаткові атрибути:

datetime

If the header value can be recognized as a valid date of one form or another, this attribute will contain a datetime instance representing that date. If the timezone of the input date is specified as -0000 (indicating it is in UTC but contains no information about the source timezone), then datetime will be a naive datetime. If a specific timezone offset is found (including +0000), then datetime will contain an aware datetime that uses datetime.timezone to record the timezone offset.

Значення decoded заголовка визначається форматуванням datetime відповідно до правил RFC 5322; тобто встановлено:

email.utils.format_datetime(self.datetime)

Під час створення DateHeader значення може бути екземпляром datetime. Це означає, наприклад, що наступний код дійсний і виконує те, що можна очікувати:

msg['Date'] = datetime(2011, 7, 15, 21)

Оскільки це проста datetime, вона буде інтерпретована як мітка часу UTC, а результуюче значення матиме часовий пояс -0000. Набагато кориснішим є використання функції localtime() з модуля utils:

msg['Date'] = utils.localtime()

У цьому прикладі в заголовку дати встановлюється поточний час і дата з використанням поточного зміщення часового поясу.

class email.headerregistry.AddressHeader

Заголовки адрес є одним із найскладніших структурованих типів заголовків. Клас AddressHeader забезпечує загальний інтерфейс для будь-якого заголовка адреси.

Цей тип заголовка надає такі додаткові атрибути:

groups

Кортеж об’єктів Group, що кодує адреси та групи, знайдені у значенні заголовка. Адреси, які не є частиною групи, представлені в цьому списку як одноадресні Групи, у яких display_name має значення None.

addresses

Кортеж об’єктів Address, що кодує всі окремі адреси зі значення заголовка. Якщо значення заголовка містить будь-які групи, окремі адреси з групи включаються до списку в тому місці, де група зустрічається у значенні (тобто список адрес «зрівнюється» в одновимірний список).

The decoded value of the header will have all encoded words decoded to unicode. idna encoded domain names are also decoded to unicode. The decoded value is set by joining the str value of the elements of the groups attribute with ', '.

Для встановлення значення заголовка адреси можна використовувати список об’єктів Address і Group у будь-якій комбінації. Об’єкти Групи, у яких display_name є None, інтерпретуватимуться як окремі адреси, що дозволяє скопіювати список адрес із недоторканими групами за допомогою списку, отриманого з атрибута groups вихідний заголовок.

class email.headerregistry.SingleAddressHeader

Підклас AddressHeader, який додає один додатковий атрибут:

address

Єдина адреса, закодована значенням заголовка. Якщо значення заголовка насправді містить більше однієї адреси (що було б порушенням RFC за умовчанням policy), доступ до цього атрибута призведе до ValueError.

Багато з наведених вище класів також мають варіант Unique (наприклад, UniqueUnstructuredHeader). Єдина відмінність полягає в тому, що у варіанті Unique max_count має значення 1.

class email.headerregistry.MIMEVersionHeader

Насправді існує лише одне дійсне значення для заголовка MIME-Version, і це 1.0. Для майбутньої перевірки цей клас заголовка підтримує інші дійсні номери версій. Якщо номер версії має дійсне значення для RFC 2045, тоді об’єкт заголовка матиме значення, відмінні від None для таких атрибутів:

version

Номер версії у вигляді рядка з видаленими пробілами та/або коментарями.

major

Основний номер версії як ціле число

minor

Номер другорядної версії як ціле число

class email.headerregistry.ParameterizedMIMEHeader

Усі заголовки MIME починаються з префікса «Content-». Кожен конкретний заголовок має певне значення, описане в класі для цього заголовка. Деякі також можуть приймати список додаткових параметрів, які мають загальний формат. Цей клас служить основою для всіх заголовків MIME, які приймають параметри.

params

Словник, що зіставляє назви параметрів зі значеннями параметрів.

class email.headerregistry.ContentTypeHeader

Клас ParameterizedMIMEHeader, який обробляє заголовок Content-Type.

content_type

Рядок типу вмісту у формі maintype/subtype.

maintype

subtype

class email.headerregistry.ContentDispositionHeader

Клас ParameterizedMIMEHeader, який обробляє заголовок Content-Disposition.

content_disposition

inline і attachment є єдиними допустимими значеннями, які широко використовуються.

class email.headerregistry.ContentTransferEncoding

Обробляє заголовок Content-Transfer-Encoding.

cte

Дійсні значення: 7bit, 8bit, base64 і quoted-printable. Перегляньте RFC 2045 для отримання додаткової інформації.

class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

This is the factory used by EmailPolicy by default. HeaderRegistry builds the class used to create a header instance dynamically, using base_class and a specialized class retrieved from a registry that it holds. When a given header name does not appear in the registry, the class specified by default_class is used as the specialized class. When use_default_map is True (the default), the standard mapping of header names to classes is copied in to the registry during initialization. base_class is always the last class in the generated class’s __bases__ list.

Відображення за замовчуванням:

тема

UniqueUnstructuredHeader

дата

UniqueDateHeader

дата повторного відправлення

DateHeader

дата виходу

UniqueDateHeader

відправник

UniqueSingleAddressHeader

resent-sender

SingleAddressHeader

до

UniqueAddressHeader

обурюватися

AddressHeader

cc

UniqueAddressHeader

resent-cc

AddressHeader

прихована копія

UniqueAddressHeader

resent-bcc

AddressHeader

від

UniqueAddressHeader

обурюватися-від

AddressHeader

відповідати на

UniqueAddressHeader

мім-версія

MIMEVersionHeader

тип вмісту

ContentTypeHeader

зміст-диспозиція

ContentDispositionHeader

кодування передачі вмісту

ContentTransferEncodingHeader

ідентифікатор повідомлення

MessageIDHeader

HeaderRegistry має такі методи:

map_to_type(self, name, cls)

ім’я — це ім’я заголовка, який буде зіставлено. У реєстрі його буде перетворено на нижній регістр. cls — це спеціалізований клас, який використовується разом із base_class для створення класу, що використовується для створення екземплярів заголовків, які відповідають name.

__getitem__(name)

Створіть і поверніть клас для створення заголовка name.

__call__(name, value)

Отримує спеціальний заголовок, пов’язаний з name, із реєстру (використовуючи default_class, якщо name не відображається в реєстрі) і створює його з base_class для створення класу, викликає конструктор створеного класу, передаючи йому те саме список аргументів і, нарешті, повертає екземпляр класу, створений таким чином.

Наступні класи є класами, які використовуються для представлення даних, розібраних із структурованих заголовків, і можуть, загалом, використовуватися прикладною програмою для створення структурованих значень для призначення певним заголовкам.

class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)

Клас, який використовується для представлення електронної адреси. Загальна форма адреси:

[display_name] <username@domain>

або:

username@domain

де кожна частина має відповідати певним правилам синтаксису, викладеним у RFC 5322.

Для зручності можна вказати addr_spec замість username і domain, у цьому випадку username і domain будуть аналізуватися з addr_spec. addr_spec має бути належним чином цитованим рядком RFC; якщо це не Address, викличе помилку. Дозволяються символи Юнікоду, які будуть закодовані властивостями під час серіалізації. Однак, згідно з RFC, Юнікод не дозволений у частині імені користувача адреси.

display_name

Частина відображуваної назви адреси, якщо така є, без лапок. Якщо адреса не має відображуваного імені, цей атрибут буде порожнім рядком.

username

Частина ім’я користувача адреси з видаленням лапок.

domain

Частина domain адреси.

addr_spec

Частина адреси username@domain, правильно взята в лапки для використання як чистої адреси (друга форма, показана вище). Цей атрибут не змінний.

__str__()

Значення str об’єкта є адресою в цитатах відповідно до правил RFC 5322, але без кодування передачі вмісту будь-яких символів, відмінних від ASCII.

Щоб підтримувати SMTP (RFC 5321), Address обробляє один особливий випадок: якщо username і domain є порожнім рядком (або None), тоді рядкове значення Address - <>.

class email.headerregistry.Group(display_name=None, addresses=None)

Клас, який використовується для представлення групи адрес. Загальна форма групи адрес:

display_name: [address-list];

Для зручності обробки списків адрес, які складаються з суміші груп і окремих адрес, Група також може використовуватися для представлення окремих адрес, які не є частиною групи, встановивши display_name на None і надання списку однієї адреси як адрес.

display_name

display_name групи. Якщо значення None і в адресах є точно одна Адреса, тоді Група представляє одну адресу, яка не входить до групи.

addresses

Можливо, порожній кортеж об’єктів Address, що представляє адреси в групі.

__str__()

Значення str Group відформатовано відповідно до RFC 5322, але без кодування передачі вмісту будь-яких символів, відмінних від ASCII. Якщо display_name не має значення, а в списку addresses є одна Address, значення str буде таким самим, як str цього одного Address.

Виноски

1

Спочатку додано в 3.3 як проміжний модуль