`email.header.md`

108 строк · 16.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/email.header.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.1.5. [`email.header`](https://python-all.ru/3.2/library/email.header.html#module-email.header): Интернационализированные заголовки89[**RFC 2822**](https://python-all.ru/3.2/library/email.header.html) – это базовый стандарт, описывающий формат email-сообщений. Он происходит от более старого стандарта [**RFC 822**](https://python-all.ru/3.2/library/email.header.html), который получил широкое распространение в то время, когда большинство писем состояло только из символов ASCII. [**RFC 2822**](https://python-all.ru/3.2/library/email.header.html) – это спецификация, написанная в предположении, что email содержит только 7-битные символы ASCII.1011Разумеется, с распространением электронной почты по всему миру она стала интернационализированной, так что теперь в сообщениях можно использовать языковые кодировки. Однако базовый стандарт по-прежнему требует, чтобы сообщения передавались только с использованием 7-битных символов ASCII, поэтому было написано множество RFC, описывающих, как кодировать не-ASCII символы в формат, совместимый с [**RFC 2822**](https://python-all.ru/3.2/library/email.header.html). Эти RFC включают [**RFC 2045**](https://python-all.ru/3.2/library/email.header.html), [**RFC 2046**](https://python-all.ru/3.2/library/email.header.html), [**RFC 2047**](https://python-all.ru/3.2/library/email.header.html) и [**RFC 2231**](https://python-all.ru/3.2/library/email.header.html). Пакет [`email`](https://python-all.ru/3.2/library/email.html#module-email) поддерживает эти стандарты в своих модулях [`email.header`](https://python-all.ru/3.2/library/email.header.html#module-email.header) и [`email.charset`](https://python-all.ru/3.2/library/email.charset.html#module-email.charset).1213Если нужно включить не-ASCII символы в заголовки писем, например, в поля *Subject* или *To*, следует использовать класс [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) и присвоить полю в объекте [`Message`](https://python-all.ru/3.2/library/email.message.html#email.message.Message) экземпляр [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) вместо строки для значения заголовка. Импортируйте класс [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) из модуля [`email.header`](https://python-all.ru/3.2/library/email.header.html#module-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.2/library/email.header.html#email.header.Header) и передали кодировку, в которой закодирована байтовая строка. Когда последующий экземпляр [`Message`](https://python-all.ru/3.2/library/email.message.html#email.message.Message) был преобразован в линейную форму, поле *Subject* было правильно закодировано по [**RFC 2047**](https://python-all.ru/3.2/library/email.header.html). Почтовые клиенты, поддерживающие MIME, отобразят этот заголовок с использованием встроенного символа ISO-8859-1.2627Вот описание класса [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header):2829#### `class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')`3031Создаёт заголовок, совместимый с MIME, который может содержать строки в разных наборах символов.3233Необязательный параметр *s* – это начальное значение заголовка. Если `None` (значение по умолчанию), начальное значение не задаётся. Позднее можно добавлять данные в заголовок вызовами метода [`append()`](https://python-all.ru/3.2/library/email.header.html#email.header.Header.append). *s* может быть экземпляром [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) или [`str`](https://python-all.ru/3.2/library/functions.html#str), но за разъяснением семантики обратитесь к документации [`append()`](https://python-all.ru/3.2/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.2/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.2/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.2/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.2/library/email.header.html), и обычно это пробел или символ табуляции. Этот символ будет добавляться в начало строк продолжения. По умолчанию *continuation\_ws* – это одиночный пробел.4041Необязательный параметр *errors* передаётся напрямую методу [`append()`](https://python-all.ru/3.2/library/email.header.html#email.header.Header.append).4243#### `append(s, charset=None, errors='strict')`4445Добавляет строку *s* к MIME-заголовку.4647Необязательный параметр *charset*, если указан, должен быть экземпляром [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) (см. [`email.charset`](https://python-all.ru/3.2/library/email.charset.html#module-email.charset)) или именем кодировки, которая будет преобразована в экземпляр [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset). Значение `None` (по умолчанию) означает, что используется *charset*, заданный в конструкторе.4849*s* может быть экземпляром [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes) или [`str`](https://python-all.ru/3.2/library/functions.html#str). Если это экземпляр [`bytes`](https://python-all.ru/3.2/library/functions.html#bytes), то *charset* – это кодировка этой байтовой строки, и будет вызвано исключение [`UnicodeError`](https://python-all.ru/3.2/library/exceptions.html#UnicodeError), если строку невозможно декодировать с помощью этой кодировки.5051Если *s* – экземпляр [`str`](https://python-all.ru/3.2/library/functions.html#str), то *charset* – это подсказка, указывающая кодировку символов в строке.5253В любом случае, при создании заголовка, совместимого с [**RFC 2822**](https://python-all.ru/3.2/library/email.header.html), с использованием правил [**RFC 2047**](https://python-all.ru/3.2/library/email.header.html), строка будет закодирована с помощью выходного кодека набора символов. Если строка не может быть закодирована с помощью выходного кодека, будет возбуждено исключение UnicodeError.5455Необязательный *errors* передаётся как аргумент errors при вызове decode, если *s* является байтовой строкой.5657#### `encode(splitchars=';, \t', maxlinelen=None, linesep='\n')`5859Кодирует заголовок сообщения в формат, соответствующий RFC, возможно, перенося длинные строки и инкапсулируя не-ASCII части в кодировки base64 или quoted-printable.6061Необязательный параметр *splitchars* – это строка, содержащая символы, которым следует придавать дополнительный вес при разбиении во время обычного переноса заголовка. Это очень грубая поддержка «синтаксических разрывов высшего уровня» из [**RFC 2822**](https://python-all.ru/3.2/library/email.header.html): точки разбиения перед символом splitchar предпочтительнее при разбиении строк, причём символы предпочтительнее в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, какому из них отдавать предпочтение в качестве точки разбиения, когда другие символы разбиения отсутствуют в разбиваемой строке. Splitchars не влияет на строки, закодированные по [**RFC 2047**](https://python-all.ru/3.2/library/email.header.html).6263*maxlinelen*, если указан, переопределяет значение экземпляра для максимальной длины строки.6465*linesep* задаёт символы, используемые для разделения строк свёрнутого заголовка. По умолчанию используется наиболее полезное значение для кода приложений Python (`\n`), но можно указать `\r\n` для получения заголовков с разделителями строк, соответствующими RFC.6667Изменено в версии 3.2: Добавлен аргумент *linesep*.6869Класс [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.7071#### `__str__()`7273Возвращает приближённое представление [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) в виде строки с неограниченной длиной строки. Все части преобразуются в Юникод с использованием указанной кодировки и соответствующим образом соединяются. Любые части с кодировкой `'unknown-8bit'` декодируются как ASCII с использованием обработчика ошибок `'replace'`.7475Изменено в версии 3.2: Добавлена обработка кодировки `'unknown-8bit'`.7677#### `__eq__(other)`7879Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) на равенство.8081#### `__ne__(other)`8283Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) на неравенство.8485Модуль [`email.header`](https://python-all.ru/3.2/library/email.header.html#module-email.header) также предоставляет следующие удобные функции.8687#### `email.header.decode_header(header)`8889Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка находится в *header*.9091Эта функция возвращает список пар `(decoded_string, charset)`, содержащих каждую из декодированных частей заголовка. *charset* равен `None` для незакодированных частей заголовка, в противном случае это строка в нижнем регистре, содержащая имя кодировки, указанной в закодированной строке.9293Вот пример:9495```python96>>> from email.header import decode_header97>>> decode_header('=?iso-8859-1?q?p=F6stal?=')98[('p\xf6stal', 'iso-8859-1')]99```100101#### `email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')`102103Создаёт экземпляр [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header) из последовательности пар, возвращённой функцией [`decode_header()`](https://python-all.ru/3.2/library/email.header.html#email.header.decode_header).104105Функция [`decode_header()`](https://python-all.ru/3.2/library/email.header.html#email.header.decode_header) принимает строку значения заголовка и возвращает последовательность пар формата `(decoded_string, charset)`, где *charset* – имя кодировки.106107Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header). Необязательные параметры *maxlinelen*, *header\_name* и *continuation\_ws* такие же, как в конструкторе [`Header`](https://python-all.ru/3.2/library/email.header.html#email.header.Header).108