> **Источник:** https://python-all.ru/3.6/library/email.header.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 19.1.11. [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header): Интернационализированные заголовки **Исходный код:** [Lib/email/header.py](https://python-all.ru/src/3.6/Lib/email/header.py) --- Этот модуль является частью устаревшего (`Compat32`) API email. В текущем API кодирование и декодирование заголовков обрабатывается прозрачно через API, подобный словарю, класса [`EmailMessage`](https://python-all.ru/3.6/library/email.message.html#email.message.EmailMessage). В дополнение к использованию в устаревшем коде, этот модуль может быть полезен в приложениях, которым требуется полный контроль над наборами символов, используемыми при кодировании заголовков. Оставшийся текст в этом разделе является оригинальной документацией модуля. [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html) – это базовый стандарт, описывающий формат email-сообщений. Он происходит от более старого стандарта [**RFC 822**](https://python-all.ru/3.6/library/email.header.html), который получил широкое распространение в то время, когда большинство писем состояло только из символов ASCII. [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html) – это спецификация, написанная в предположении, что email содержит только 7-битные символы ASCII. Конечно, с распространением email по всему миру он стал интернационализированным, так что теперь в email-сообщениях можно использовать наборы символов, специфичные для языка. Базовый стандарт по-прежнему требует, чтобы email-сообщения передавались только с использованием 7-битных символов ASCII, поэтому был написан ряд RFC, описывающих, как кодировать email, содержащий не-ASCII символы, в формат, совместимый с [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html). Эти RFC включают [**RFC 2045**](https://python-all.ru/3.6/library/email.header.html), [**RFC 2046**](https://python-all.ru/3.6/library/email.header.html), [**RFC 2047**](https://python-all.ru/3.6/library/email.header.html) и [**RFC 2231**](https://python-all.ru/3.6/library/email.header.html). Пакет [`email`](https://python-all.ru/3.6/library/email.html#module-email) поддерживает эти стандарты в своих модулях [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header) и [`email.charset`](https://python-all.ru/3.6/library/email.charset.html#module-email.charset). Если вы хотите включить не-ASCII символы в заголовки email, например, в поля *Subject* или *To*, следует использовать класс [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) и присвоить поле в объекте [`Message`](https://python-all.ru/3.6/library/email.compat32-message.html#email.message.Message) экземпляру [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) вместо использования строки для значения заголовка. Импортируйте класс [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) из модуля [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header). Например: ```python >>> from email.message import Message >>> from email.header import Header >>> msg = Message() >>> h = Header('p\xf6stal', 'iso-8859-1') >>> msg['Subject'] = h >>> msg.as_string() 'Subject: =?iso-8859-1?q?p=F6stal?=\n\n' ``` Обратите внимание, как мы хотели, чтобы поле *Subject* содержало не-ASCII символ? Мы сделали это, создав экземпляр [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) и передав набор символов, в котором была закодирована байтовая строка. Когда последующий экземпляр [`Message`](https://python-all.ru/3.6/library/email.compat32-message.html#email.message.Message) был преобразован в плоскую строку, поле *Subject* было должным образом закодировано с помощью [**RFC 2047**](https://python-all.ru/3.6/library/email.header.html). Почтовые программы, поддерживающие MIME, покажут этот заголовок, используя встроенный символ ISO-8859-1. Вот описание класса [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header): #### `class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')` Создаёт заголовок, совместимый с MIME, который может содержать строки в разных наборах символов. Необязательный параметр *s* – это начальное значение заголовка. Если `None` (по умолчанию), начальное значение заголовка не установлено. Позже можно добавлять данные в заголовок с помощью вызовов метода [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append). *s* может быть экземпляром [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) или [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), но смотрите документацию [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append) о семантике. Необязательный параметр *charset* служит двум целям: он имеет то же значение, что и аргумент *charset* метода [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append). Он также устанавливает набор символов по умолчанию для всех последующих вызовов [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append), в которых опущен аргумент *charset*. Если *charset* не указан в конструкторе (по умолчанию), набор символов `us-ascii` используется как начальный набор символов для *s*, так и как набор по умолчанию для последующих вызовов [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append). Максимальную длину строки можно указать явно через *maxlinelen*. Чтобы первая строка разбивалась на более короткое значение (с учётом заголовка поля, который не входит в *s*, например *Subject*), передаётся имя поля в *header\_name*. Значение по умолчанию *maxlinelen* – 76, а значение по умолчанию для *header\_name* – `None`, то есть он не учитывается для первой строки длинного разбитого заголовка. Необязательный параметр *continuation\_ws* должен быть пробельным символом для переноса, совместимым с [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html), и обычно это пробел или символ табуляции. Этот символ будет добавляться в начало строк продолжения. По умолчанию *continuation\_ws* – это одиночный пробел. Необязательный параметр *errors* передаётся напрямую методу [`append()`](https://python-all.ru/3.6/library/email.header.html#email.header.Header.append). #### `append(s, charset=None, errors='strict')` Добавляет строку *s* к MIME-заголовку. Необязательный *charset*, если указан, должен быть экземпляром [`Charset`](https://python-all.ru/3.6/library/email.charset.html#email.charset.Charset) (см. [`email.charset`](https://python-all.ru/3.6/library/email.charset.html#module-email.charset)) или именем набора символов, который будет преобразован в экземпляр [`Charset`](https://python-all.ru/3.6/library/email.charset.html#email.charset.Charset). Значение `None` (по умолчанию) означает, что используется *charset*, указанный в конструкторе. *s* может быть экземпляром [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) или [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Если это экземпляр [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), то *charset* – это кодировка этой байтовой строки, и будет возбуждено исключение [`UnicodeError`](https://python-all.ru/3.6/library/exceptions.html#UnicodeError), если строка не может быть декодирована с этим набором символов. Если *s* является экземпляром [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), то *charset* – это подсказка, указывающая набор символов для символов в строке. В любом случае, при создании заголовка, совместимого с [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html), с использованием правил [**RFC 2047**](https://python-all.ru/3.6/library/email.header.html), строка будет закодирована с помощью выходного кодека набора символов. Если строка не может быть закодирована с помощью выходного кодека, будет возбуждено исключение UnicodeError. Необязательный *errors* передаётся как аргумент errors при вызове decode, если *s* является байтовой строкой. #### `encode(splitchars=';, \t', maxlinelen=None, linesep='\n')` Кодирует заголовок сообщения в формат, соответствующий RFC, возможно, перенося длинные строки и инкапсулируя не-ASCII части в кодировки base64 или quoted-printable. Необязательный параметр *splitchars* – это строка, содержащая символы, которым алгоритм разбиения должен придавать дополнительный вес при обычном переносе заголовков. Это очень грубая поддержка «синтаксических разрывов более высокого уровня» из [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html): точки разбиения, перед которыми стоит символ splitchar, предпочтительны при разбиении строки, причем символы предпочтительны в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, следует ли отдавать предпочтение одному перед другим в качестве точки разбиения, когда другие символы splitchar не встречаются в разбиваемой строке. Параметр splitchars не влияет на строки, закодированные по [**RFC 2047**](https://python-all.ru/3.6/library/email.header.html). *maxlinelen*, если указан, переопределяет значение экземпляра для максимальной длины строки. *linesep* задаёт символы, используемые для разделения строк свернутого заголовка. По умолчанию используется наиболее полезное значение для кода приложений Python (`\n`), но можно указать `\r\n`, чтобы создавать заголовки с разделителями строк, соответствующими RFC. Изменено в версии 3.2: Добавлен аргумент *linesep*. Класс [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций. #### `__str__()` Возвращает приближение объекта [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) в виде строки с неограниченной длиной строки. Все фрагменты преобразуются в Unicode с использованием указанной кодировки и соответствующим образом объединяются. Любые фрагменты с charset `'unknown-8bit'` декодируются как ASCII с использованием обработчика ошибок `'replace'`. Изменено в версии 3.2: Добавлена обработка для charset `'unknown-8bit'`. #### `__eq__(other)` Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) на равенство. #### `__ne__(other)` Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) на неравенство. Модуль [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header) также предоставляет следующие удобные функции. #### `email.header.decode_header(header)` Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка находится в *header*. Эта функция возвращает список пар `(decoded_string, charset)`, содержащих каждую из декодированных частей заголовка. *charset* равно `None` для незакодированных частей заголовка, в противном случае – это строка в нижнем регистре, содержащая имя кодировки, указанной в закодированной строке. Вот пример: ```python >>> from email.header import decode_header >>> decode_header('=?iso-8859-1?q?p=F6stal?=') [(b'p\xf6stal', 'iso-8859-1')] ``` #### `email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')` Создаёт экземпляр [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) из последовательности пар, возвращаемой функцией [`decode_header()`](https://python-all.ru/3.6/library/email.header.html#email.header.decode_header). Функция [`decode_header()`](https://python-all.ru/3.6/library/email.header.html#email.header.decode_header) принимает строку значения заголовка и возвращает последовательность пар формата `(decoded_string, charset)`, где *charset* – это имя набора символов. Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header). Необязательные параметры *maxlinelen*, *header\_name* и *continuation\_ws* такие же, как в конструкторе [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header).