`email.header.md`

140 строк · 14.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/email.header.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email`](https://python-all.ru/3.0/library/email.html#module-email): Интернационализированные заголовки89[**RFC 2822**](https://python-all.ru/3.0/library/email.header.html) – это базовый стандарт, описывающий формат email-сообщений. Он происходит от более старого стандарта [**RFC 822**](https://python-all.ru/3.0/library/email.header.html), который получил широкое распространение в то время, когда большинство писем состояло только из символов ASCII. [**RFC 2822**](https://python-all.ru/3.0/library/email.header.html) – это спецификация, написанная в предположении, что email содержит только 7-битные символы ASCII.1011Of course, as email has been deployed worldwide, it has become internationalized, such that language specific character sets can now be used in email messages. The base standard still requires email messages to be transferred using only 7-bit ASCII characters, so a slew of RFCs have been written describing how to encode email containing non-ASCII characters into [**RFC 2822**](https://python-all.ru/3.0/library/email.header.html)-compliant format. These RFCs include [**RFC 2045**](https://python-all.ru/3.0/library/email.header.html), [**RFC 2046**](https://python-all.ru/3.0/library/email.header.html), [**RFC 2047**](https://python-all.ru/3.0/library/email.header.html), and [**RFC 2231**](https://python-all.ru/3.0/library/email.header.html). The [`email`](https://python-all.ru/3.0/library/email.html#module-email) package supports these standards in its `email.header` and [`email.charset`](https://python-all.ru/3.0/library/email.charset.html#module-email.charset) modules.1213Чтобы включить не-ASCII символы в заголовки электронных писем, например в поля *Subject* или *To*, следует использовать класс [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header) и присвоить полю в объекте `Message` экземпляр [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header), а не строку для значения заголовка. Класс [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header) импортируется из модуля `email.header`. Например:1415```python16>>> from email.message import Message17>>> from email.header import Header18>>> msg = Message()19>>> h = Header('p\xf6stal', 'iso-8859-1')20>>> msg['Subject'] = h21>>> print(msg.as_string())22Subject: =?iso-8859-1?q?p=F6stal?=23```2425Обратите внимание: мы хотели, чтобы поле *Subject* содержало не-ASCII символ? Мы сделали это, создав экземпляр [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header) и передав кодировку, в которой была закодирована байтовая строка. Когда после этого экземпляр `Message` был преобразован в плоскую форму, поле *Subject* было правильно закодировано [**RFC 2047**](https://python-all.ru/3.0/library/email.header.html). MIME-совместимые почтовые клиенты отобразили бы этот заголовок с использованием встроенного символа ISO-8859-1.2627Вот описание класса [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header):2829#### `[email.header.Header]class email.header.Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])`3031Создаёт заголовок, совместимый с MIME, который может содержать строки в разных наборах символов.3233Необязательный параметр *s* – это начальное значение заголовка. Если `None` (значение по умолчанию), начальное значение не задаётся. Позднее можно добавлять данные в заголовок вызовами метода [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append). *s* может быть экземпляром [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes) или [`str`](https://python-all.ru/3.0/library/functions.html#str), но за разъяснением семантики обратитесь к документации [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append).3435Optional *charset* serves two purposes: it has the same meaning as the *charset* argument to the [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append) method. It also sets the default character set for all subsequent [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append) calls that omit the *charset* argument. If *charset* is not provided in the constructor (the default), the `us-ascii` character set is used both as *s*‘s initial charset and as the default for subsequent [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append) calls.3637Максимальную длину строки можно явно указать через *maxlinelen*. Чтобы разбить первую строку на более короткое значение (с учётом заголовка поля, который не включён в *s*, например, *Subject*), передайте имя поля в *header\_name*. Значение *maxlinelen* по умолчанию равно 76, а значение *header\_name* по умолчанию – `None`, то есть оно не учитывается для первой строки длинного разделённого заголовка.3839Необязательный параметр *continuation\_ws* должен быть [**RFC 2822**](https://python-all.ru/3.0/library/email.header.html)-совместимым пробельным символом для переноса и обычно представляет собой либо пробел, либо символ табуляции. Этот символ будет добавляться в начало строк продолжения.4041Необязательный параметр *errors* передаётся напрямую методу [`append()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.append).4243#### `[email.header.Header.append]append(s[, charset[, errors]])`4445Добавляет строку *s* к MIME-заголовку.4647Необязательный параметр *charset*, если указан, должен быть экземпляром `Charset` (см. [`email.charset`](https://python-all.ru/3.0/library/email.charset.html#module-email.charset)) или именем кодировки, которая будет преобразована в экземпляр `Charset`. Значение `None` (по умолчанию) означает, что используется *charset*, указанный в конструкторе.4849*s* может быть экземпляром [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes) или [`str`](https://python-all.ru/3.0/library/functions.html#str). Если это экземпляр [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes), то *charset* – это кодировка этой байтовой строки, и будет вызвано исключение [`UnicodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeError), если строку невозможно декодировать с помощью этой кодировки.5051Если *s* является экземпляром [`str`](https://python-all.ru/3.0/library/functions.html#str), то *charset* – это подсказка, указывающая кодировку символов в строке. В этом случае при создании заголовка, совместимого с [**RFC 2822**](https://python-all.ru/3.0/library/email.header.html), с использованием правил [**RFC 2047**](https://python-all.ru/3.0/library/email.header.html), строка Unicode будет закодирована с помощью следующих кодировок по порядку: `us-ascii`, подсказка *charset*, `utf-8`. Используется первая кодировка, которая не вызывает [`UnicodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeError).5253Необязательный параметр *errors* передаётся в любой вызов [`encode()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.encode) или `ustr.encode()` и по умолчанию равен "strict".5455#### `[email.header.Header.encode]encode([splitchars])`5657Кодирует заголовок сообщения в формат, совместимый с RFC, возможно, с переносом длинных строк и заключением не-ASCII частей в кодировки base64 или quoted-printable. Необязательный параметр5859*splitchars*6061– это строка, содержащая символы, по которым можно разбивать длинные ASCII-строки, в грубом соответствии с6263[**RFC 2822**](https://python-all.ru/3.0/library/email.header.html)6465‘s6667*синтаксическими разрывами наивысшего уровня*6869. Это не влияет на строки, закодированные согласно7071[**RFC 2047**](https://python-all.ru/3.0/library/email.header.html)7273.7475Класс [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header) также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.7677#### `[email.header.Header.__str__]__str__()`7879Синоним для8081[`Header.encode()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.encode)8283. Полезно для8485`str(aHeader)`8687.8889#### `[email.header.Header.__unicode__]__unicode__()`9091Вспомогательная функция для метода9293[`str`](https://python-all.ru/3.0/library/functions.html#str)9495‘s9697[`encode()`](https://python-all.ru/3.0/library/email.header.html#email.header.Header.encode)9899. Возвращает заголовок в виде строки Unicode.100101#### `[email.header.Header.__eq__]__eq__(other)`102103Этот метод позволяет сравнивать два экземпляра104105[`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header)106107на равенство.108109#### `[email.header.Header.__ne__]__ne__(other)`110111Этот метод позволяет сравнивать два экземпляра112113[`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header)114115на неравенство.116117Модуль `email.header` также предоставляет следующие удобные функции.118119#### `[email.header.decode_header]email.header.decode_header(header)`120121Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка находится в *header*.122123Эта функция возвращает список пар `(decoded_string, charset)`, содержащих каждую из декодированных частей заголовка. *charset* равен `None` для незакодированных частей заголовка, в противном случае это строка в нижнем регистре, содержащая имя кодировки, указанной в закодированной строке.124125Вот пример:126127```python128>>> from email.header import decode_header129>>> decode_header('=?iso-8859-1?q?p=F6stal?=')130[('p\xf6stal', 'iso-8859-1')]131```132133#### `[email.header.make_header]email.header.make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])`134135Создаёт экземпляр [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header) из последовательности пар, возвращённой функцией [`decode_header()`](https://python-all.ru/3.0/library/email.header.html#email.header.decode_header).136137Функция [`decode_header()`](https://python-all.ru/3.0/library/email.header.html#email.header.decode_header) принимает строку значения заголовка и возвращает последовательность пар формата `(decoded_string, charset)`, где *charset* – имя кодировки.138139Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header). Необязательные параметры *maxlinelen*, *header\_name* и *continuation\_ws* такие же, как в конструкторе [`Header`](https://python-all.ru/3.0/library/email.header.html#email.header.Header).140